diff --git a/.gitignore b/.gitignore index b223ab335..c54745f8c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,16 +1,2 @@ -# vscode stuff -.vscode/* -!.vscode/tasks.json - # docs-builder default output -.artifacts - -# vs stuff -.vs/ - -# osx stuff -.DS_Store - -# jetbrains -*.iml -.idea +.artifacts \ No newline at end of file diff --git a/cloud-account/add-a-login-method.md b/cloud-account/add-a-login-method.md new file mode 100644 index 000000000..4bc925000 --- /dev/null +++ b/cloud-account/add-a-login-method.md @@ -0,0 +1,29 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-change-login-method.html +--- + +# Add a login method [ec-change-login-method] + +When you create your account, you can choose one of the the following methods to log in: + +* A password-based login +* Log in with Google +* Log in with Microsoft + +After your account is created, you and can an additional login method. You can’t remove a login method after it’s added. + +## Enable password-based login [ec_enable_password_based_login] + +To enable password-based login in addition to Google or Microsoft sign-in, go to the [Forgot password](https://cloud.elastic.co/forgot) page and enter your email address. This will trigger the forgot password flow and will allow you to create a password for your account. + +After you create a password, log in. You’ll be prompted to [enable multifactor authentication](multifactor-authentication.md). + +You will now be able to change the email address in your [user settings](https://cloud.elastic.co/user/settings). + + +## Enable Google or Microsoft sign-in [ec_enable_google_or_microsoft_sign_in] + +To enable Google or Microsoft sign-in in addition to password-based login, go to the [Login](https://cloud.elastic.co/login) page and select **Log in with Google** or **Log in with Microsoft**. + + diff --git a/cloud-account/change-your-password.md b/cloud-account/change-your-password.md new file mode 100644 index 000000000..cb451fa9e --- /dev/null +++ b/cloud-account/change-your-password.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-change-password.html +--- + +# Change your password [ec-change-password] + +If you created a password when you signed up for a Elasticsearch Service account, or you added the password-based login method to your account, then you can change your password if needed. + +If you know your current password: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Open the user menu in the header bar. +3. Go to **Profile**. +4. Select **Change password**. +5. Enter the current password and provide the new password that you want to use. + +If you don’t know your current password: + +1. At the login screen for the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), select the link **Forgot password?**. +2. Enter the primary email address for your account and select **Reset password**. + + By default, to sign up for Elasticsearch Service you use your primary email address. If you change it at some point, use your current email address to log in to Elasticsearch Service. + + An email is sent to the address you specified with a link to reset the password. If you don’t get the email after a few minutes, check your spam folder. + + diff --git a/cloud-account/index.md b/cloud-account/index.md new file mode 100644 index 000000000..75f73e00c --- /dev/null +++ b/cloud-account/index.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-account-user-settings.html + - https://www.elastic.co/guide/en/serverless/current/general-user-profile.html +--- + +# Cloud account + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/304 + +% Scope notes: https://github.com/elastic/docs-projects/issues/304 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-account-user-settings.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-user-profile.md \ No newline at end of file diff --git a/cloud-account/join-or-leave-an-organization.md b/cloud-account/join-or-leave-an-organization.md new file mode 100644 index 000000000..34e6e145f --- /dev/null +++ b/cloud-account/join-or-leave-an-organization.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-invite-users.html + - https://www.elastic.co/guide/en/serverless/current/general-manage-organization.html +--- + +# Join or leave an organization + +% What needs to be done: Refine + +% Scope notes: https://github.com/elastic/docs-projects/issues/304 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-invite-users.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-manage-organization.md \ No newline at end of file diff --git a/cloud-account/multifactor-authentication.md b/cloud-account/multifactor-authentication.md new file mode 100644 index 000000000..25741b898 --- /dev/null +++ b/cloud-account/multifactor-authentication.md @@ -0,0 +1,120 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-account-security-mfa.html +--- + +# Multifactor authentication [ec-account-security-mfa] + +If you use a password-based login, Elastic requires that you add an extra layer of security to your Elasticsearch Service account by enabling a multifactor authentication (MFA) method. + +You can choose from the following methods: + +* Set up an **authenticator app** such as Google Authenticator, Microsoft Authenticator, or Okta Verify. These apps generate a time-based one-time password (TOTP) that you enter along with your password when you log in. +* Authenticate using a **hardware security key or biometric data**, such as a YubiKey or a fingerprint reader. +* Receive a verification code through **email**. You enter this code along with your password when you log in. + +Elastic recommends that you enable multiple methods so that you can still access your account if you lose access to one method. + +If you use only a Google or Microsoft account to log in, then you can’t configure MFA in Elasticsearch Service. You can check and manage your multifactor authentication options in your Google or Microsoft account security settings. + +::::{note} +You can no longer configure SMS as a multifactor authentication method. If you already use SMS for multifactor authentication, then you can continue using it. You’ll be prompted to switch to a new MFA method in the future. + +:::: + + +## Configure an authenticator app [ec-account-security-mfa-authenticator] + +To enable multifactor authentication using an authenticator app, you must enroll your device. + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Go to [User settings](https://cloud.elastic.co/user/settings) and choose **Profile**. Navigate to the **Multifactor authentication** section. +3. On the **Authenticator app** card, select **Set up**. +4. Scan the QR code with your authenticator app. If you can’t scan the QR code, then you can enter the code manually. +5. Enter the verification code generated by your authenticator app and select **Enable authentication method**. + + +## Configure a security key or biometrics [ec_configure_a_security_key_or_biometrics] + +To enable multifactor authentication using a security key or biometrics, you must register your security key or biometric data. + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Go to [User settings](https://cloud.elastic.co/user/settings) and choose **Profile**. Navigate to the **Multifactor authentication** section. +3. On the **Security key or biometrics** card, select **Set up**. +4. Follow the prompts on your screen to register your hardware security key or your biometric authentication method. + + +## Configure email authentication [ec_configure_email_authentication] + +To enable multifactor authentication using an authenticator app, you must verify your email address. + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Go to [User settings](https://cloud.elastic.co/user/settings) and choose **Profile**. Navigate to the **Multifactor authentication** section. +3. On the **Email** card, select **Set up**. +4. Enter the verification code sent to your email address, and then select **Enable authentication method**. + + +## Remove a multifactor authentication method [ec_remove_a_multifactor_authentication_method] + +You can remove a multifactor authentication method after it’s added by clicking **Remove**. + +Before you remove an authentication method, you must set up an alternate method. If you can’t use any of your configured authentication methods — for example, if your device is lost or stolen — then [contact support](../troubleshoot/troubleshoot/cloud.md). + + +## Frequently asked questions [ec-account-security-mfa-faq] + +Below are some frequently asked questions about the multifactor authentication changes added in September 2024. + +**What changes are being introduced as part of the Elastic Cloud MFA initiative?** + +The following changes were introduced to Elastic Cloud MFA starting September 9th, 2024: + +* All users authenticating to any Elastic service through Elastic Cloud ([cloud.elastic.co/login](https://cloud.elastic.co/login)) with a username and password who have not yet set up an MFA method will be redirected to an MFA setup screen when they log in. Users will only be able to access their service after they successfully set up at least one MFA method, such as Authenticator or Email. +* SMS MFA is gradually being phased out. This aligns with our internal information security policy and the industry best practice to move away from SMS as an additional authentication factor due to it not being phishing-resistant. All users with SMS MFA will eventually be redirected to the MFA setup screen to set up a different MFA method. + +We will be adding the following features in the future: + +* Support for customer email notifications for suspicious logins, such as logins from a new device or subsequent logins from geographically distant locations. + +Users who authenticate to Elastic Cloud using Google or Microsoft identities, or [SAML SSO](../deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md), are not impacted by the MFA changes. In these cases, MFA is managed by the external identity provider. + +**What are the Elastic services that can be accessed through Elastic Cloud?** + +Elastic Cloud login ([cloud.elastic.co/login](https://cloud.elastic.co/login)) is used to authenticate the following services or portals provided by Elastic: + +* Elastic Cloud - [cloud.elastic.co](https://cloud.elastic.co). In Elastic Cloud, MFA enforcement will apply to both Elastic Cloud trial and non-trial organizations. +* Support Hub - [support.elastic.co](https://support.elastic.co) +* Learning Portal - [learn.elastic.co](https://learn.elastic.co) +* *Coming soon:* Partner Portal - [partners.elastic.co](https://partners.elastic.co) + +**Does MFA enforcement apply to all Elastic Cloud regions and organizations?** + +Yes, the Elastic Cloud default MFA enforcement applies to all Elastic Cloud regions, including GovCloud, and all organizations, both trial and non-trial. + +**Does MFA enforcement apply to direct login to Kibana or Elasticsearch?** + +No, the Elastic Cloud default MFA enforcement does not apply when selecting **Log in with Elasticsearch** on the Kibana login screen or connecting to an Elasticsearch endpoint. However, it does apply when using the **Log in with Elastic Cloud** option. + +**My team uses a generic account or distribution/mailing list and shares the password to access Elastic Cloud. How will my team be able to log in and access our Elastic Cloud organization after the MFA enforcement?** + +There are ways to work around the limitations of generic account access, but the more secure approach is to use one Elastic account for each Elastic Cloud user. + +You can explore the following workarounds: + +* Grant your team members access to that account’s Elastic Cloud organization by inviting and making them organization members. This may involve creating additional Elastic user accounts for each team member, depending on their organization access and ownership needs since we have yet to support multi-organization membership. When each team member has their own account to access your Elastic Cloud organization, they will be able to set up their own MFA method. +* Use the email MFA method, assuming all of your team members have access to the generic account or distribution list’s mailbox. +* Keep using the generic account to log in and set up multifactor authentication [using an authenticator app](#ec-account-security-mfa-authenticator). + + ``` + During the setup, take a photo of the QR code, or note its numeric version, and share it across your team. This code is sensitive and should be stored and shared securely. For example, it should be stored in an encrypted place using a secure algorithm such as AES-256, and transmitted over a secure encrypted channel such as TLS 1.3. + ``` + ``` + This QR code is the "base" number used by the Authenticator app to generate codes based on the current time. There is no danger of synchronization issues. However, there is risk of a breach if the QR code picture or number is compromised. + ``` + + +**After I set up an MFA method, will I need to answer an MFA challenge every time I authenticate through Elastic Cloud?** + +For now, you will need to answer an MFA challenge on every login, but we are working on adding a **Trust this device** option, which will "silence" the MFA challenge for one month per user session. + + diff --git a/cloud-account/toc.yml b/cloud-account/toc.yml new file mode 100644 index 000000000..018d46768 --- /dev/null +++ b/cloud-account/toc.yml @@ -0,0 +1,8 @@ +project: 'Cloud account' +toc: + - file: index.md + - file: join-or-leave-an-organization.md + - file: update-your-email-address.md + - file: change-your-password.md + - file: add-a-login-method.md + - file: multifactor-authentication.md \ No newline at end of file diff --git a/cloud-account/update-your-email-address.md b/cloud-account/update-your-email-address.md new file mode 100644 index 000000000..b3f65fc06 --- /dev/null +++ b/cloud-account/update-your-email-address.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-update-email-address.html +--- + +# Update your email address [ec-update-email-address] + +Each Elasticsearch Service account has a primary email associated with it. By default, the primary email address is used to sign up for Elasticsearch Service and to log in. If needed, you can change this primary email address: + +1. By **Email address**, select **edit**. +2. Enter a new email address and your current password. + + An email is sent to the new address with a link to confirm the change. If you don’t get the email after a few minutes, check your spam folder. + + +If you are using Google or Microsoft Sign-In and would like to change your email address, you will need to: + +1. Go to the [Forgot password](https://cloud.elastic.co/forgot) page and enter your email address. +2. Follow the instructions in the "Reset your password" email. +3. In the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), update your [User settings](https://cloud.elastic.co/user/settings) to the new email address. + +If your organization is associated with [Azure Marketplace](../deploy-manage/deploy/elastic-cloud/azure-native-isv-service.md), you can’t change your primary email address using the above methods. Instead, [invite another user](../deploy-manage/users-roles/cloud-organization/manage-users.md) with the desired email address to your organization. + diff --git a/deploy-manage/api-keys.md b/deploy-manage/api-keys.md new file mode 100644 index 000000000..9f3a35c05 --- /dev/null +++ b/deploy-manage/api-keys.md @@ -0,0 +1,7 @@ +# Manage API keys + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/349 + +% Scope notes: Elasticsearch & Kibana authentication API Keys \ No newline at end of file diff --git a/deploy-manage/api-keys/elastic-cloud-api-keys.md b/deploy-manage/api-keys/elastic-cloud-api-keys.md new file mode 100644 index 000000000..783c66718 --- /dev/null +++ b/deploy-manage/api-keys/elastic-cloud-api-keys.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-api-authentication.html +--- + +# Elastic Cloud API keys [ec-api-authentication] + +With a valid Elastic Cloud API key, you can access the API from its base URL at `api.elastic-cloud.com`. + +Only **Organization owners** can create and manage API keys. An API key is not tied to the user who created it. When creating a key, you assign it specific roles to control its access to organizational resources, including hosted deployments and serverless projects. If a user leaves the organization, the API keys they have created will still function until they expire. + +You can have multiple API keys for different purposes, and you can revoke them when you no longer need them. + + +## Create an API key [ec-api-keys] + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Go to your avatar in the upper right corner and choose **Organization**. +3. On the API keys tab of the **Organization** page, click **Create API Key**. + + ::::{note} + This key provides access to the API that enables you to manage your deployments. It does not provide access to {{es}}. To access {{es}} with an API key, create a key [in {{kib}}](elasticsearch-api-keys.md) or [using the {{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html). + :::: + +4. From the **Create API Key** page, you can configure your new key by adding a name, set expiration, or assign [roles](../users-roles/cloud-organization/user-roles.md). + + By default, API keys expire after three months. You can set the expiration to a different preset value or to a specific date, up to one year. If you need the key to work indefinitely, you can also set its expiration to Never. In this case, the key won’t expire. + + ::::{note} + When an API key is nearing expiration, Elastic sends an email to the creator of the API key and each of the operational contacts. When you use an API key to authenticate, the API response header `X-Elastic-Api-Key-Expiration` indicates the key’s expiration date. You can log this value to detect API keys that are nearing expiration. + :::: + +5. Click **Create API key**, copy the generated API key, and store it in a safe place. You can also download the key as a CSV file. + +The API key needs to be supplied in the `Authorization` header of a request, in the following format: + +```sh +Authorization: ApiKey $EC_API_KEY +``` + + +## Revoke an API key [ec_revoke_an_api_key] + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Go to your avatar in the upper right corner and choose **Organization**. + + The keys currently associated with your organization are listed under the API keys tab of the **Organization** page. + +3. Find the key you want to revoke, and click the trash icon under **Actions**. diff --git a/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md b/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md new file mode 100644 index 000000000..f988432f8 --- /dev/null +++ b/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md @@ -0,0 +1,74 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restful-api-authentication.html +--- + +# Elastic Cloud Enterprise API keys [ece-restful-api-authentication] + +::::{note} +This documentation applies to the Elastic Cloud Enterprise API only. If you are using [Elasticsearch Service](https://cloud.elastic.co/home), check the [Elastic Cloud API information](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html) instead. +:::: + + +The Elastic Cloud Enterprise RESTful APIs support both key-based and token-based authentication. Key-based is generally the preferred method. + + +## Authenticate using an API key [ece-api-keys] + +For key-based API authentication, you can create an API key through the Elastic Cloud Enterprise UI. Once created, you can specify the key in the header of your API calls to authenticate. + +::::{note} +API keys are not available for the built-in users (`admin` and `readonly`). Therefore, the **API Keys** settings page on the UI does not appear for these users. +:::: + + +To create an API key: + +1. Sign in to the Cloud UI. +2. Go to **Profile**, **Settings**, and then **API Keys**. +3. Select **Generate API key**. +4. Specify a name and expiration for the API key. +5. Copy the generated API key and store it in a safe place. You can also download the key as a CSV file. + + ::::{note} + By default, the API key will expire three months after its creation date, but you can set the expiration to Never. When you use an API key to authenticate, the API response header `X-Elastic-Api-Key-Expiration` indicates the key’s expiration date. You can log this value to detect API keys that are nearing expiration. + :::: + + +The API key has the same permissions as the API key owner. You may have multiple API keys for different purposes and you can revoke them when you no longer need them. + +Currently, API keys cannot be generated for the `admin` and `readonly` users that come pre-configured with your Elastic Cloud Enterprise installation. + +To revoke an API key: + +1. Sign in to the Cloud UI. +2. Go to **Profile**, **Settings**, and then **API Keys**. +3. Select the trash icon under the **Revoke** column for any keys that you want to delete. + + +## Authenticate using a bearer token [ece-restful-api-authentication-token] + +For token-based API authentication, you can use the same username and password that you use to log into the Cloud UI. If you want to use the credentials that were provided when you installed Elastic Cloud Enterprise on your first host, for example `admin`, you can [retrieve them separately](../users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md#ece-retrieve-passwords). + +For operations that only read information, but don’t create, update or delete, you can authenticate with a user that has restricted permissions, such as the `readonly` user. + +To create a bearer token: + +1. Open a terminal and send your credentials to the login endpoint: + + ```sh + curl -k -X POST -H 'Content-Type: application/json' https://$COORDINATOR_HOST:12443/api/v1/users/auth/_login --data-binary ' + { + "username": "USER", + "password": "PASSWORD" + }' + ``` + + If your credentials are valid, the response from the login API will contain a JSON Web Token (JWT): + + ```text + { "token": "eyJ0eXa......MgBmsw4s" } + ``` + +2. Specify the bearer token in the Authentication header of your API requests. To learn more, check [accessing the API from the command line](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-api-command-line.html). + diff --git a/deploy-manage/api-keys/elasticsearch-api-keys.md b/deploy-manage/api-keys/elasticsearch-api-keys.md new file mode 100644 index 000000000..1340d4d8b --- /dev/null +++ b/deploy-manage/api-keys/elasticsearch-api-keys.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/api-keys.html +--- + +# Elasticsearch API keys [api-keys] + +API keys are security mechanisms used to authenticate and authorize access to {{es}} resources. They ensure that only authorized users or applications interact with {{es}}. + +For example, if you extract data from an {{es}} cluster on a daily basis, you might create an API key tied to your credentials, configure it with minimum access, and then put the API credentials into a cron job. Or you might create API keys to automate ingestion of new data from remote sources, without a live user interaction. + +You can use {{kib}} to manage your different API keys: + +* User API key: allows external services to access the Elastic Stack on behalf of a user. +* Cross-cluster API key: allows other clusters to connect to this cluster. +* Managed API key: created and managed by Kibana to run background tasks. + +To manage API keys, go to the **API Keys** management page using the navigation menu or the [global search field](../../get-started/the-stack.md#kibana-navigation-search). + +![API Keys UI](../../images/kibana-api-keys.png "") + + +## Security privileges [api-keys-security-privileges] + +* To use API keys in {{kib}}, you must have the `manage_security`, `manage_api_key`, or the `manage_own_api_key` cluster privileges. +* To delete API keys, you must have the `manage_api_key` or `manage_own_api_key` privileges. +* To create or update a **user API key**, you must have the `manage_api_key` or the `manage_own_api_key` privilege. +* To create or update a **cross-cluster API key**, you must have the `manage_security` privilege and an Enterprise license. +* To have a read-only view on the API keys, you must have access to the page and the `read_security` cluster privilege. + +To manage roles, go to the **Roles** management page using the navigation menu or the [global search field](../../get-started/the-stack.md#kibana-navigation-search), or use the [role APIs](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-roles). + + +## Create an API key [create-api-key] + +To create an API key, go to the **API Keys** management page using the navigation menu or the [global search field](../../get-started/the-stack.md#kibana-navigation-search), and select **Create API key**. + +![Create API Key UI](../../images/kibana-create-ccr-api-key.png "") + +Refer to the [create API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) documentation to learn more about creating user API keys. + +Refer to the [create cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) documentation to learn more about creating cross-cluster API keys. + + +## Update an API key [udpate-api-key] + +To update an API key, go to the **API Keys** management page using the navigation menu or the [global search field](../../get-started/the-stack.md#kibana-navigation-search), and then click on the name of the key. You cannot update the name or the type of API key. + +Refer to the [update API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-api-key.html) documentation to learn more about updating user API keys. + +Refer to the [update cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-cross-cluster-api-key.html) documentation to learn more about updating cross-cluster API keys. + + +## View and delete API keys [view-api-keys] + +The **API Keys** feature in {{kib}} lists your API keys, including the name, date created, and status. If an API key expires, its status changes from `Active` to `Expired`. + +If you have `manage_security` or `manage_api_key` permissions, you can view the API keys of all users, and see which API key was created by which user in which realm. If you have only the `manage_own_api_key` permission, you see only a list of your own keys. + +You can delete API keys individually or in bulk, but you need the `manage_api_keys` or `manage_own_api_key` privileges. + diff --git a/deploy-manage/api-keys/serverless-project-api-keys.md b/deploy-manage/api-keys/serverless-project-api-keys.md new file mode 100644 index 000000000..c01ff0516 --- /dev/null +++ b/deploy-manage/api-keys/serverless-project-api-keys.md @@ -0,0 +1,87 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/api-keys.html +--- + +# Serverless project API keys [api-keys] + +This content applies to: [![Elasticsearch](../../images/serverless-es-badge.svg "")](../../solutions/search.md) [![Observability](../../images/serverless-obs-badge.svg "")](../../solutions/observability.md) [![Security](../../images/serverless-sec-badge.svg "")](../../solutions/security/elastic-security-serverless.md) + +API keys are security mechanisms used to authenticate and authorize access to {{stack}} resources, and ensure that only authorized users or applications are able to interact with the {{stack}}. + +For example, if you extract data from an {{es}} cluster on a daily basis, you might create an API key tied to your credentials, configure it with minimum access, and then put the API credentials into a cron job. Or, you might create API keys to automate ingestion of new data from remote sources, without a live user interaction. + +You can manage your keys in **{{project-settings}} → {{manage-app}} → {{api-keys-app}}**: + +:::{image} ../../images/serverless-api-key-management.png +:alt: API keys UI +:class: screenshot +::: + +A *personal API key* allows external services to access the {{stack}} on behalf of a user. + +A *managed API key* is created and managed by {{kib}} to correctly run background tasks. + + +## Create an API key [api-keys-create-an-api-key] + +In **{{api-keys-app}}**, click **Create API key**: + +:::{image} ../../images/serverless-create-personal-api-key.png +:alt: Create API key UI +:class: screenshot +::: + +Once created, you can copy the encoded API key and use it to send requests to the {{es}} HTTP API. For example: + +```bash +curl "${ES_URL}" \ +-H "Authorization: ApiKey ${API_KEY}" +``` + +::::{important} +API keys are intended for programmatic access. Don’t use API keys to authenticate access using a web browser. + +:::: + + + +### Restrict privileges [api-keys-restrict-privileges] + +When you create or update an API key, use **Restrict privileges** to limit the permissions. Define the permissions using a JSON `role_descriptors` object, where you specify one or more roles and the associated privileges. + +For example, the following `role_descriptors` object defines a `books-read-only` role that limits the API key to `read` privileges on the `books` index. + +```json +{ + "books-read-only": { + "cluster": [], + "indices": [ + { + "names": ["books"], + "privileges": ["read"] + } + ], + "applications": [], + "run_as": [], + "metadata": {}, + "transient_metadata": { + "enabled": true + } + } +} +``` + +For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html#security-api-create-api-key-request-body) docs. For supported privileges, check [Security privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices). + + +## Update an API key [api-keys-update-an-api-key] + +In **{{api-keys-app}}**, click on the name of the key. You can update only **Restrict privileges** and **Include metadata**. + + +## View and delete API keys [api-keys-view-and-delete-api-keys] + +The **{{api-keys-app}}** app lists your API keys, including the name, date created, and status. When API keys expire, the status changes from `Active` to `Expired`. + +You can delete API keys individually or in bulk. diff --git a/deploy-manage/autoscaling.md b/deploy-manage/autoscaling.md new file mode 100644 index 000000000..28bc04ce0 --- /dev/null +++ b/deploy-manage/autoscaling.md @@ -0,0 +1,63 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-autoscaling.html + - https://www.elastic.co/guide/en/cloud/current/ec-autoscaling.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-autoscaling.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-autoscaling.html +--- + +# Autoscaling + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/344 + +% Scope notes: Creating a new landing page and subheadings/pages for different deployment types. Merge content when appropriate + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-autoscaling.md +% Notes: 1 child +% - [ ] ./raw-migrated-files/cloud/cloud/ec-autoscaling.md +% Notes: 2 children +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-autoscaling.md +% Notes: 2 children +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/xpack-autoscaling.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-autoscaling-intro$$$ + +$$$ec-autoscaling-factors$$$ + +$$$ec-autoscaling-notifications$$$ + +$$$ec-autoscaling-restrictions$$$ + +$$$ec-autoscaling-enable$$$ + +$$$ec-autoscaling-update$$$ + +$$$ece-autoscaling-intro$$$ + +$$$ece-autoscaling-factors$$$ + +$$$ece-autoscaling-notifications$$$ + +$$$ece-autoscaling-restrictions$$$ + +$$$ece-autoscaling-enable$$$ + +$$$ece-autoscaling-update$$$ + +$$$ech-autoscaling-intro$$$ + +$$$ech-autoscaling-factors$$$ + +$$$ech-autoscaling-notifications$$$ + +$$$ech-autoscaling-restrictions$$$ + +$$$ech-autoscaling-enable$$$ + +$$$ech-autoscaling-update$$$ \ No newline at end of file diff --git a/deploy-manage/autoscaling/autoscaling-deciders.md b/deploy-manage/autoscaling/autoscaling-deciders.md new file mode 100644 index 000000000..d2646d233 --- /dev/null +++ b/deploy-manage/autoscaling/autoscaling-deciders.md @@ -0,0 +1,30 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-deciders.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-reactive-storage-decider.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-proactive-storage-decider.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-frozen-shards-decider.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-frozen-storage-decider.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-frozen-existence-decider.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-machine-learning-decider.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-fixed-decider.html +--- + +# Autoscaling deciders + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/344 + +% Scope notes: Collapse to a single page, explain what deciders are + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-deciders.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-reactive-storage-decider.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-proactive-storage-decider.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-frozen-shards-decider.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-frozen-storage-decider.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-frozen-existence-decider.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-machine-learning-decider.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/autoscaling-fixed-decider.md \ No newline at end of file diff --git a/deploy-manage/autoscaling/autoscaling-stateless-applications-on-eck.md b/deploy-manage/autoscaling/autoscaling-stateless-applications-on-eck.md new file mode 100644 index 000000000..6033ace9e --- /dev/null +++ b/deploy-manage/autoscaling/autoscaling-stateless-applications-on-eck.md @@ -0,0 +1,54 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-stateless-autoscaling.html +--- + +# Autoscaling stateless applications on ECK [k8s-stateless-autoscaling] + +::::{note} +This section only applies to stateless applications. Check [Elasticsearch autoscaling](deployments-autoscaling-on-eck.md) for more details about scaling automatically Elasticsearch. +:::: + + +The [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale) can be used to automatically scale the deployments of the following resources: + +* Kibana +* APM Server +* Enterprise Search +* Elastic Maps Server + +These resources expose the `scale` subresource which can be used by the Horizontal Pod Autoscaler controller to automatically adjust the number of replicas according to the CPU load or any other custom or external metric. This example shows how to create an `HorizontalPodAutoscaler` resource to adjust the replicas of a Kibana deployment according to the CPU load: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + config: + node.store.allow_mmap: false + +apiVersion: autoscaling/v2beta2 +kind: HorizontalPodAutoscaler +metadata: + name: kb +spec: + scaleTargetRef: + apiVersion: kibana.k8s.elastic.co/v1 + kind: Kibana + name: kibana-sample + minReplicas: 1 + maxReplicas: 4 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 50 +``` + diff --git a/deploy-manage/autoscaling/deployments-autoscaling-on-eck.md b/deploy-manage/autoscaling/deployments-autoscaling-on-eck.md new file mode 100644 index 000000000..df47ddffc --- /dev/null +++ b/deploy-manage/autoscaling/deployments-autoscaling-on-eck.md @@ -0,0 +1,293 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-autoscaling.html +--- + +# Deployments autoscaling on ECK [k8s-autoscaling] + +::::{note} +Elasticsearch autoscaling requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +ECK can leverage the [autoscaling API](https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-apis.html) introduced in Elasticsearch 7.11 to adjust automatically the number of Pods and the allocated resources in a tier. Currently, autoscaling is supported for Elasticsearch [data tiers](https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tiers.html) and machine learning nodes. + + +## Enable autoscaling [k8s-enable] + +To enable autoscaling on an Elasticsearch cluster, you need to define one or more autoscaling policies. Each autoscaling policy applies to one or more NodeSets which share the same set of roles specified in the `node.roles` setting in the Elasticsearch configuration. + + +### Define autoscaling policies [k8s-autoscaling-policies] + +Autoscaling policies can be defined in an `ElasticsearchAutoscaler` resource. Each autoscaling policy must have the following fields: + +* `name` is a unique name used to identify the autoscaling policy. +* `roles` contains a set of node roles, unique across all the autoscaling policies, used to identify the NodeSets to which this policy applies. At least one NodeSet with the exact same set of roles must exist in the Elasticsearch resource specification. +* `resources` helps define the minimum and maximum compute resources usage: + + * `nodeCount` defines the minimum and maximum nodes allowed in the tier. + * `cpu` and `memory` enforce minimum and maximum compute resources usage for the Elasticsearch container. + * `storage` enforces minimum and maximum storage request per PersistentVolumeClaim. + + +If there is no recommendation from the Autoscaling API for a given resource, and if this resource is not set in the policy, then the resource is not managed by the operator and existing requirements in the NodeSets remain unchanged. + +```yaml +apiVersion: autoscaling.k8s.elastic.co/v1alpha1 +kind: ElasticsearchAutoscaler +metadata: + name: autoscaling-sample +spec: + ## The name of the Elasticsearch cluster to be scaled automatically. + elasticsearchRef: + name: elasticsearch-sample + ## The autoscaling policies. + policies: + - name: data-ingest + roles: ["data", "ingest" , "transform"] + resources: + nodeCount: + min: 3 + max: 8 + cpu: + min: 2 + max: 8 + memory: + min: 2Gi + max: 16Gi + storage: + min: 64Gi + max: 512Gi + - name: ml + roles: + - ml + resources: + nodeCount: + min: 1 + max: 9 + cpu: + min: 1 + max: 4 + memory: + min: 2Gi + max: 8Gi + storage: + min: 1Gi + max: 1Gi +``` + +::::{warning} +A node role should not be referenced in more than one autoscaling policy. +:::: + + +In the case of storage the following restrictions apply: + +* Scaling the storage size automatically requires the `ExpandInUsePersistentVolumes` feature to be enabled. It also requires a storage class that supports [volume expansion](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/). +* Only one persistent volume claim per Elasticsearch node is supported when autoscaling is enabled. +* Volume size cannot be scaled down. +* Scaling up (vertically) is only supported if the available capacity in a PersistentVolume matches the capacity claimed in the PersistentVolumeClaim. Refer to the next section for more information. + + +### Scale Up and Scale Out [k8s-autoscaling-algorithm] + +In order to adapt the resources to the workload, the operator first attempts to scale up the resources (cpu, memory, and storage) allocated to each node in the NodeSets. The operator always ensures that the requested resources are within the limits specified in the autoscaling policy. If each individual node has reached the limits specified in the autoscaling policy, but more resources are required to handle the load, then the operator adds some nodes to the NodeSets. Nodes are added up to the `max` value specified in the `nodeCount` of the policy. + +::::{warning} +Scaling up (vertically) is only supported if the actual storage capacity of the persistent volumes matches the capacity claimed. If the physical capacity of a PersistentVolume may be greater than the capacity claimed in the PersistentVolumeClaim, it is advised to set the same value for the `min` and the `max` setting of each resource. It is however still possible to let the operator scale out the NodeSets automatically, as in the following example: +:::: + + +```yaml +apiVersion: autoscaling.k8s.elastic.co/v1alpha1 +kind: ElasticsearchAutoscaler +metadata: + name: autoscaling-sample +spec: + elasticsearchRef: + name: elasticsearch-sample + policies: + - name: data-ingest + roles: ["data", "ingest" , "transform"] + resources: + nodeCount: + min: 3 + max: 9 + cpu: + min: 4 + max: 4 + memory: + min: 16Gi + max: 16Gi + storage: + min: 512Gi + max: 512Gi +``` + + +### Set the limits [k8s-autoscaling-resources] + +The value set for memory and CPU limits are computed by applying a ratio to the calculated resource request. The default ratio between the request and the limit for both CPU and memory is 1. This means that request and limit have the same value. You can change the default ratio between the request and the limit for both the CPU and memory ranges by using the `requestsToLimitsRatio` field. + +For example, you can set a CPU limit to twice the value of the request, as follows: + +```yaml +apiVersion: autoscaling.k8s.elastic.co/v1alpha1 +kind: ElasticsearchAutoscaler +metadata: + name: autoscaling-sample +spec: + elasticsearchRef: + name: elasticsearch-sample + policies: + - name: data-ingest + roles: ["data", "ingest" , "transform"] + resources: + nodeCount: + min: 2 + max: 5 + cpu: + min: 1 + max: 2 + requestsToLimitsRatio: 2 + memory: + min: 2Gi + max: 6Gi + storage: + min: 512Gi + max: 512Gi +``` + +You can find [a complete example in the ECK GitHub repository](https://github.com/elastic/cloud-on-k8s/blob/2.16/config/recipes/autoscaling/elasticsearch.yaml) which will also show you how to fine-tune the [autoscaling deciders](https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-deciders.html). + + +### Change the polling interval [k8s-autoscaling-polling-interval] + +The Elasticsearch autoscaling capacity endpoint is polled every minute by the operator. This interval duration can be controlled using the `pollingPeriod` field in the autoscaling specification: + +```yaml +apiVersion: autoscaling.k8s.elastic.co/v1alpha1 +kind: ElasticsearchAutoscaler +metadata: + name: autoscaling-sample +spec: + pollingPeriod: "42s" + elasticsearchRef: + name: elasticsearch-sample + policies: + - name: data-ingest + roles: ["data", "ingest" , "transform"] + resources: + nodeCount: + min: 2 + max: 5 + cpu: + min: 1 + max: 2 + memory: + min: 2Gi + max: 6Gi + storage: + min: 512Gi + max: 512Gi +``` + + +## Monitoring [k8s-monitoring] + + +### Autoscaling status [k8s-autoscaling-status] + +In addition to the logs generated by the operator, an autoscaling status is maintained in the `ElasticsearchAutoscaler` resource. This status holds several `Conditions` to summarize the health and the status of the autoscaling mechanism. For example, dedicated `Conditions` may report if the controller cannot connect to the Elasticsearch cluster, or if a resource limit has been reached: + +```sh +kubectl get elasticsearchautoscaler autoscaling-sample \ + -o jsonpath='{ .status.conditions }' | jq +``` + +```json +[ + { + "lastTransitionTime": "2022-09-09T08:07:10Z", + "message": "Limit reached for policies data-ingest", + "status": "True", + "type": "Limited" + }, + { + "lastTransitionTime": "2022-09-09T07:55:08Z", + "status": "True", + "type": "Active" + }, + { + "lastTransitionTime": "2022-09-09T08:07:10Z", + "status": "True", + "type": "Healthy" + }, + { + "lastTransitionTime": "2022-09-09T07:56:22Z", + "message": "Elasticsearch is available", + "status": "True", + "type": "Online" + } +] +``` + + +### Expected resources [k8s-autoscaling-expected-resources] + +The autoscaler status also contains a `policies` section which describes the expected resources for each NodeSet managed by an autoscaling policy. + +```sh +kubectl get elasticsearchautoscaler.autoscaling.k8s.elastic.co/autoscaling-sample \ + -o jsonpath='{ .status.policies }' | jq +``` + +```json +[ + { + "lastModificationTime": "2022-10-05T05:47:13Z", + "name": "data-ingest", + "nodeSets": [ + { + "name": "nodeset-1", + "nodeCount": 2 + } + ], + "resources": { + "limits": { + "cpu": "1", + "memory": "2Gi" + }, + "requests": { + "cpu": "500m", + "memory": "2Gi", + "storage": "1Gi" + } + } + } +] +``` + + +### Events [k8s-events] + +Important events are also reported through Kubernetes events, for example when the maximum autoscaling size limit is reached: + +```sh +> kubectl get events + +40m Warning HorizontalScalingLimitReached elasticsearch/sample Can't provide total required storage 32588740338, max number of nodes is 5, requires 6 nodes +``` + + +## Disable autoscaling [k8s-disable] + +You can disable autoscaling at any time by deleting the `ElasticsearchAutoscaler` resource. For machine learning the following settings are not automatically reset: + +* `xpack.ml.max_ml_node_size` +* `xpack.ml.max_lazy_ml_nodes` +* `xpack.ml.use_auto_machine_memory_percent` + +You should adjust those settings manually to match the size of your deployment when you disable autoscaling. + diff --git a/deploy-manage/autoscaling/ec-autoscaling-api-example.md b/deploy-manage/autoscaling/ec-autoscaling-api-example.md new file mode 100644 index 000000000..d7eb0d9a3 --- /dev/null +++ b/deploy-manage/autoscaling/ec-autoscaling-api-example.md @@ -0,0 +1,267 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoscaling-api-example.html +--- + +# Autoscaling through the API [ec-autoscaling-api-example] + +This example demonstrates how to use the Elasticsearch Service RESTful API to create a deployment with autoscaling enabled. + +The example deployment has a hot data and content tier, warm data tier, cold data tier, and a machine learning node, all of which will scale within the defined parameters. To learn about the autoscaling settings, check [Deployment autoscaling](../autoscaling.md) and [Autoscaling example](ec-autoscaling-example.md). For more information about using the Elasticsearch Service API in general, check [RESTful API](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html). + + +## Requirements [ec_requirements] + +Note the following requirements when you run this API request: + +* All Elasticsearch components must be included in the request, even if they are not enabled (that is, if they have a zero size). All components are included in this example. +* The request requires a format that supports data tiers. Specifically, all Elasticsearch components must contain the following properties: + + * `id` + * `node_attributes` + * `node_roles` + +* The `size`, `autoscaling_min`, and `autoscaling_max` properties must be specified according to the following rules. This is because: + + * On data tiers only upward scaling is currently supported. + * On machine learning nodes both upward and downward scaling is supported. + * On all other components autoscaling is not currently supported. + + +$$$ec-autoscaling-api-example-requirements-table$$$ ++ + +| | | | | +| --- | --- | --- | --- | +| | `size` | `autoscaling_min` | `autoscaling_max` | +| data tier | ✓ | ✕ | ✓ | +| machine learning node | ✕ | ✓ | ✓ | +| coordinating and master nodes | ✓ | ✕ | ✕ | +| Kibana | ✓ | ✕ | ✕ | +| APM | ✓ | ✕ | ✕ | +| Enterprise Search | ✓ | ✕ | ✕ | + ++ + ++ ✓ = Include the property. + ++ ✕ = Do not include the property. + ++ These rules match the behavior of the Elasticsearch Service user console. + ++ * The `elasticsearch` object must contain the property `"autoscaling_enabled": true`. + + +## API request example [ec_api_request_example] + +Run this example API request to create a deployment with autoscaling: + + +```sh +curl -XPOST \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments" \ +-d ' +{ + "name": "my-first-autoscaling-deployment", + "resources": { + "elasticsearch": [ + { + "ref_id": "main-elasticsearch", + "region": "us-east-1", + "plan": { + "autoscaling_enabled": true, + "cluster_topology": [ + { + "id": "hot_content", + "node_roles": [ + "remote_cluster_client", + "data_hot", + "transform", + "data_content", + "master", + "ingest" + ], + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "hot" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.data.highio.i3", + "size": { + "resource": "memory", + "value": 8192 + }, + "autoscaling_max": { + "value": 118784, + "resource": "memory" + } + }, + { + "id": "warm", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "warm" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.data.highstorage.d3", + "size": { + "value": 0, + "resource": "memory" + }, + "autoscaling_max": { + "value": 118784, + "resource": "memory" + } + }, + { + "id": "cold", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.data.highstorage.d3", + "size": { + "value": 0, + "resource": "memory" + }, + "autoscaling_max": { + "value": 59392, + "resource": "memory" + } + }, + { + "id": "coordinating", + "zone_count": 2, + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "instance_configuration_id": "aws.coordinating.m5d", + "size": { + "value": 0, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "id": "master", + "node_roles": [ + "master" + ], + "zone_count": 3, + "instance_configuration_id": "aws.master.r5d", + "size": { + "value": 0, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "id": "ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "zone_count": 1, + "instance_configuration_id": "aws.ml.m5d", + "autoscaling_min": { + "value": 0, + "resource": "memory" + }, + "autoscaling_max": { + "value": 61440, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + } + ], + "elasticsearch": { + "version": "7.11.0" + }, + "deployment_template": { + "id": "aws-io-optimized-v2" + } + }, + "settings": { + "dedicated_masters_threshold": 6 + } + } + ], + "kibana": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "us-east-1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "aws.kibana.r5d", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "kibana": { + "version": "7.11.0" + } + }, + "ref_id": "main-kibana" + } + ], + "apm": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "us-east-1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "aws.apm.r5d", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 512 + } + } + ], + "apm": { + "version": "7.11.0" + } + }, + "ref_id": "main-apm" + } + ], + "enterprise_search": [] + } +} +' +``` + +::::{note} +Although autoscaling can scale some tiers by CPU, the primary measurement of tier size is memory. Limits on tier size are in terms of memory. +:::: + + diff --git a/deploy-manage/autoscaling/ec-autoscaling-example.md b/deploy-manage/autoscaling/ec-autoscaling-example.md new file mode 100644 index 000000000..80d7787ba --- /dev/null +++ b/deploy-manage/autoscaling/ec-autoscaling-example.md @@ -0,0 +1,58 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoscaling-example.html +--- + +# Autoscaling example [ec-autoscaling-example] + +To help you better understand the available autoscaling settings, this example describes a typical autoscaling workflow on sample Elasticsearch Service deployment. + +1. Enable autoscaling: + + * On an **existing deployment**, open the deployment **Edit** page to find the option to turn on autoscaling. + * When you create a new deployment, you can find the autoscaling option under **Advanced settings**. + + Once you confirm your changes or create a new deployment, autoscaling is activated with system default settings that you can adjust as needed (though for most use cases the default settings will likely suffice). + +2. View and adjust autoscaling settings on data tiers: + + 1. Open the **Edit** page for your deployment to get the current and maximum size per zone of each Elasticsearch data tier. In this example, the hot data and content tier has the following settings: + + | | | | + | --- | --- | --- | + | **Current size per zone** | **Maximum size per zone** | | + | 45GB storage | 1.41TB storage | | + | 1GB RAM | 32GB RAM | | + | Up to 2.5 vCPU | 5 vCPU | | + + The fault tolerance for the data tier is set to 2 availability zones. + + :::{image} ../../images/cloud-ec-ce-autoscaling-data-summary2.png + :alt: A screenshot showing sizing information for the autoscaled data tier + ::: + + 2. Use the dropdown boxes to adjust the current and/or the maximum size of the data tier. Capacity will be added to the hot content and data tier when required, based on its past and present storage usage, until it reaches the maximum size per zone. Any scaling events are applied simultaneously across availability zones. In this example, the tier has plenty of room to scale relative to its current size, and it will not scale above the maximum size setting. There is no minimum size setting since downward scaling is currently not supported on data tiers. + +3. View and adjust autoscaling settings on a machine learning instance: + + 1. From the deployment **Edit** page you can check the minimum and maximum size of your deployment’s machine learning instances. In this example, the machine learning instance has the following settings: + + | | | | + | --- | --- | --- | + | **Minimum size per zone** | **Maximum size per zone** | | + | 1GB RAM | 64GB RAM | | + | 0.5 vCPU up to 8 vCPU | 32 vCPU | | + + The fault tolerance for the machine learning instance is set to 1 availability zone. + + :::{image} ../../images/cloud-ec-ce-autoscaling-ml-summary2.png + :alt: A screenshot showing sizing information for the autoscaled machine learning node + ::: + + 2. Use the dropdown boxes to adjust the minimum and/or the maximum size of the data tier. Capacity will be added to or removed from the machine learning instances as needed. The need for a scaling event is determined by the expected memory and vCPU requirements for the currently configured machine learning job. Any scaling events are applied simultaneously across availability zones. Note that unlike data tiers, machine learning nodes do not have a **Current size per zone** setting. That setting is not needed since machine learning nodes support both upward and downward scaling. + +4. Over time, the volume of data and the size of any machine learning jobs in your deployment are likely to grow. Let’s assume that to meet storage requirements your hot data tier has scaled up to its maximum allowed size of 64GB RAM and 32 vCPU. At this point, a notification appears on the deployment overview page letting you know that the tier has scaled to capacity. You’ll also receive an alert by email. +5. If you expect a continued increase in either storage, memory, or vCPU requirements, you can use the **Maximum size per zone** dropdown box to adjust the maximum capacity settings for your data tiers and machine learning instances, as appropriate. And, you can always re-adjust these levels downward if the requirements change. + +As you can see, autoscaling greatly reduces the manual work involved to manage a deployment. The deployment capacity adjusts automatically as demands change, within the boundaries that you define. Check our main [Deployment autoscaling](../autoscaling.md) page for more information. + diff --git a/deploy-manage/autoscaling/ec-autoscaling.md b/deploy-manage/autoscaling/ec-autoscaling.md new file mode 100644 index 000000000..04c7d4e75 --- /dev/null +++ b/deploy-manage/autoscaling/ec-autoscaling.md @@ -0,0 +1,126 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoscaling.html +--- + +# Deployment autoscaling [ec-autoscaling] + +Autoscaling helps you to more easily manage your deployments by adjusting their available resources automatically, and currently supports scaling for both data and machine learning nodes, or machine learning nodes only. Check the following sections to learn more: + +* [Overview](../autoscaling.md#ec-autoscaling-intro) +* [When does autoscaling occur?](../autoscaling.md#ec-autoscaling-factors) +* [Notifications](../autoscaling.md#ec-autoscaling-notifications) +* [Restrictions and limitations](../autoscaling.md#ec-autoscaling-restrictions) +* [Enable or disable autoscaling](../autoscaling.md#ec-autoscaling-enable) +* [Update your autoscaling settings](../autoscaling.md#ec-autoscaling-update) + +You can also have a look at our [autoscaling example](ec-autoscaling-example.md), as well as a sample request to [create an autoscaled deployment through the API](ec-autoscaling-api-example.md). + + +## Overview [ec-autoscaling-intro] + +When you first create a deployment it can be challenging to determine the amount of storage your data nodes will require. The same is relevant for the amount of memory and CPU that you want to allocate to your machine learning nodes. It can become even more challenging to predict these requirements for weeks or months into the future. In an ideal scenario, these resources should be sized to both ensure efficient performance and resiliency, and to avoid excess costs. Autoscaling can help with this balance by adjusting the resources available to a deployment automatically as loads change over time, reducing the need for monitoring and manual intervention. + +::::{note} +Autoscaling is enabled for the Machine Learning tier by default for new deployments. +:::: + + +Currently, autoscaling behavior is as follows: + +* **Data tiers** + + * Each Elasticsearch [data tier](../../manage-data/lifecycle/data-tiers.md) scales upward based on the amount of available storage. When we detect more storage is needed, autoscaling will scale up each data tier independently to ensure you can continue and ingest more data to your hot and content tier, or move data to the warm, cold, or frozen data tiers. + * In addition to scaling up existing data tiers, a new data tier will be automatically added when necessary, based on your [index lifecycle management policies](../../manage-data/lifecycle/index-lifecycle-management.md). + * To control the maximum size of each data tier and ensure it will not scale above a certain size, you can use the maximum size per zone field. + * Autoscaling based on memory or CPU, as well as autoscaling downward, is not currently supported. In case you want to adjust the size of your data tier to add more memory or CPU, or in case you deleted data and want to scale it down, you can set the current size per zone of each data tier manually. + +* **Machine learning nodes** + + * Machine learning nodes can scale upward and downward based on the configured machine learning jobs. + * When a machine learning job is opened, or a machine learning trained model is deployed, if there are no machine learning nodes in your deployment, the autoscaling mechanism will automatically add machine learning nodes. Similarly, after a period of no active machine learning jobs, any enabled machine learning nodes are disabled automatically. + * To control the maximum size of your machine learning nodes and ensure they will not scale above a certain size, you can use the maximum size per zone field. + * To control the minimum size of your machine learning nodes and ensure the autoscaling mechanism will not scale machine learning below a certain size, you can use the minimum size per zone field. + * The determination of when to scale is based on the expected memory and CPU requirements for the currently configured machine learning jobs and trained models. + + +::::{note} +For any Elasticsearch Service Elasticsearch component the number of availability zones is not affected by autoscaling. You can always set the number of availability zones manually and the autoscaling mechanism will add or remove capacity per availability zone. +:::: + + + +## When does autoscaling occur? [ec-autoscaling-factors] + +Several factors determine when data tiers or machine learning nodes are scaled. + +For a data tier, an autoscaling event can be triggered in the following cases: + +* Based on an assessment of how shards are currently allocated, and the amount of storage and buffer space currently available. + +When past behavior on a hot tier indicates that the influx of data can increase significantly in the near future. Refer to [Reactive storage decider](autoscaling-deciders.md) and [Proactive storage decider](autoscaling-deciders.md) for more detail. + +* Through ILM policies. For example, if a deployment has only hot nodes and autoscaling is enabled, it automatically creates warm or cold nodes, if an ILM policy is trying to move data from hot to warm or cold nodes. + +On machine learning nodes, scaling is determined by an estimate of the memory and CPU requirements for the currently configured jobs and trained models. When a new machine learning job tries to start, it looks for a node with adequate native memory and CPU capacity. If one cannot be found, it stays in an `opening` state. If this waiting job exceeds the queueing limit set in the machine learning decider, a scale up is requested. Conversely, as machine learning jobs run, their memory and CPU usage might decrease or other running jobs might finish or close. In this case, if the duration of decreased resource usage exceeds the set value for `down_scale_delay`, a scale down is requested. Check [Machine learning decider](autoscaling-deciders.md) for more detail. To learn more about machine learning jobs in general, check [Create anomaly detection jobs](https://www.elastic.co/guide/en/machine-learning/current/create-jobs.html). + +On a highly available deployment, autoscaling events are always applied to instances in each availability zone simultaneously, to ensure consistency. + + +## Notifications [ec-autoscaling-notifications] + +In the event that a data tier or machine learning node scales up to its maximum possible size, you’ll receive an email, and a notice also appears on the deployment overview page prompting you to adjust your autoscaling settings to ensure optimal performance. + + +## Restrictions and limitations [ec-autoscaling-restrictions] + +The following are known limitations and restrictions with autoscaling: + +* Autoscaling will not run if the cluster is unhealthy or if the last Elasticsearch plan failed. +* Trial deployments cannot be configured to autoscale beyond the normal Trial deployment size limits. The maximum size per zone is increased automatically from the Trial limit when you convert to a paid subscription. +* If Enterprise Search is left at the default size, and has no engines or sources configured for an extended period, it will be automatically disabled. This occurs whether autoscaling is enabled or not. Reactivate the service by editing the **Enterprise Search** settings for your deployment under **Cloud > Deployments > *your-deployment* > Edit**. +* ELSER deployments do not scale automatically. For more information, refer to [ELSER](../../explore-analyze/machine-learning/nlp/ml-nlp-elser.md) and [Trained model autoscaling](../../explore-analyze/machine-learning/nlp/ml-nlp-auto-scale.md). + + +## Enable or disable autoscaling [ec-autoscaling-enable] + +To enable or disable autoscaling on a deployment: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the **Deployments** page, select your deployment. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. In your deployment menu, select **Edit**. +4. Select desired autoscaling configuration for this deployment using **Enable Autoscaling for:** dropdown menu. +5. Select **Confirm** to have the autoscaling change and any other settings take effect. All plan changes are shown on the Deployment **Activity** page. + +When autoscaling has been enabled, the autoscaled nodes resize according to the [autoscaling settings](../autoscaling.md#ec-autoscaling-update). Current sizes are shown on the deployment overview page. + +When autoscaling has been disabled, you need to adjust the size of data tiers and machine learning nodes manually. + + +## Update your autoscaling settings [ec-autoscaling-update] + +Each autoscaling setting is configured with a default value. You can adjust these if necessary, as follows: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the **Deployments** page, select your deployment. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. In your deployment menu, select **Edit**. +4. To update a data tier: + + 1. Use the dropdown box to set the **Maximum size per zone** to the largest amount of resources that should be allocated to the data tier automatically. The resources will not scale above this value. + 2. You can also update the **Current size per zone**. If you update this setting to match the **Maximum size per zone**, the data tier will remain fixed at that size. + 3. For a hot data tier you can also adjust the **Forecast window**. This is the duration of time, up to the present, for which past storage usage is assessed in order to predict when additional storage is needed. + 4. Select **Save** to apply the changes to your deployment. + +5. To update machine learning nodes: + + 1. Use the dropdown box to set the **Minimum size per zone** and **Maximum size per zone** to the smallest and largest amount of resources, respectively, that should be allocated to the nodes automatically. The resources allocated to machine learning will not exceed these values. If you set these two settings to the same value, the machine learning node will remain fixed at that size. + 2. Select **Save** to apply the changes to your deployment. + + +You can also view our [example](ec-autoscaling-example.md) of how the autoscaling settings work. diff --git a/deploy-manage/autoscaling/ece-autoscaling-api-example.md b/deploy-manage/autoscaling/ece-autoscaling-api-example.md new file mode 100644 index 000000000..e2609e8b0 --- /dev/null +++ b/deploy-manage/autoscaling/ece-autoscaling-api-example.md @@ -0,0 +1,265 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-autoscaling-api-example.html +--- + +# Autoscaling through the API [ece-autoscaling-api-example] + +This example demonstrates how to use the Elastic Cloud Enterprise RESTful API to create a deployment with autoscaling enabled. + +The example deployment has a hot data and content tier, warm data tier, cold data tier, and a machine learning node, all of which will scale within the defined parameters. To learn about the autoscaling settings, check [Deployment autoscaling](../autoscaling.md) and [Autoscaling example](ece-autoscaling-example.md). For more information about using the Elastic Cloud Enterprise API in general, check [RESTful API](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restful-api.html). + + +## Requirements [ece_requirements_3] + +Note the following requirements when you run this API request: + +* On Elastic Cloud Enterprise, autoscaling is supported for custom deployment templates on version 2.12 and above. To learn more, refer to [Updating custom templates to support `node_roles` and autoscaling](../deploy/cloud-enterprise/ce-add-support-for-node-roles-autoscaling.md). +* All Elasticsearch components must be included in the request, even if they are not enabled (that is, if they have a zero size). All components are included in this example. +* The request requires a format that supports data tiers. Specifically, all Elasticsearch components must contain the following properties: + + * `id` + * `node_attributes` + * `node_roles` + +* The `size`, `autoscaling_min`, and `autoscaling_max` properties must be specified according to the following rules. This is because: + + * On data tiers only upward scaling is currently supported. + * On machine learning nodes both upward and downward scaling is supported. + * On all other components autoscaling is not currently supported. + + +$$$ece-autoscaling-api-example-requirements-table$$$ ++ + +| | | | | +| --- | --- | --- | --- | +| | `size` | `autoscaling_min` | `autoscaling_max` | +| data tier | ✓ | ✕ | ✓ | +| machine learning node | ✕ | ✓ | ✓ | +| coordinating and master nodes | ✓ | ✕ | ✕ | +| Kibana | ✓ | ✕ | ✕ | +| APM | ✓ | ✕ | ✕ | +| Enterprise Search | ✓ | ✕ | ✕ | + ++ + ++ ✓ = Include the property. + ++ ✕ = Do not include the property. + ++ These rules match the behavior of the Elastic Cloud Enterprise user console. + ++ * The `elasticsearch` object must contain the property `"autoscaling_enabled": true`. + + +## API request example [ece_api_request_example] + +Run this example API request to create a deployment with autoscaling: + +```sh +curl -k -X POST -H "Authorization: ApiKey $ECE_API_KEY" https://$COORDINATOR_HOST:12443/api/v1/deployments -H 'content-type: application/json' -d ' +{ + "name": "my-first-autoscaling-deployment", + "resources": { + "elasticsearch": [ + { + "ref_id": "main-elasticsearch", + "region": "ece-region", + "plan": { + "autoscaling_enabled": true, + "cluster_topology": [ + { + "id": "hot_content", + "node_roles": [ + "master", + "ingest", + "remote_cluster_client", + "data_hot", + "transform", + "data_content" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "hot" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.default", + "size": { + "value": 4096, + "resource": "memory" + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "warm", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "warm" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.highstorage", + "size": { + "value": 0, + "resource": "memory" + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "cold", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.highstorage", + "size": { + "value": 0, + "resource": "memory" + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "zone_count": 1, + "instance_configuration_id": "coordinating", + "size": { + "value": 0, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "id": "master", + "node_roles": [ + "master" + ], + "zone_count": 1, + "instance_configuration_id": "master", + "size": { + "value": 0, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "id": "ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "zone_count": 1, + "instance_configuration_id": "ml", + "autoscaling_min": { + "value": 0, + "resource": "memory" + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + } + ], + "elasticsearch": { + "version": "8.13.1" + }, + "deployment_template": { + "id": "default" + } + }, + "settings": { + "dedicated_masters_threshold": 6 + } + } + ], + "kibana": [ + { + "ref_id": "main-kibana", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "kibana": { + "version": "8.13.1" + } + } + } + ], + "apm": [ + { + "ref_id": "main-apm", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 512, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": { + "version": "8.13.1" + } + } + } + ], + "enterprise_search": [] + } +} +' +``` + + +::::{note} +Although autoscaling can scale some tiers by CPU, the primary measurement of tier size is memory. Limits on tier size are in terms of memory. +:::: + + diff --git a/deploy-manage/autoscaling/ece-autoscaling-example.md b/deploy-manage/autoscaling/ece-autoscaling-example.md new file mode 100644 index 000000000..b0a905359 --- /dev/null +++ b/deploy-manage/autoscaling/ece-autoscaling-example.md @@ -0,0 +1,58 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-autoscaling-example.html +--- + +# Autoscaling example [ece-autoscaling-example] + +To help you better understand the available autoscaling settings, this example describes a typical autoscaling workflow on sample Elastic Cloud Enterprise deployment. + +1. Enable autoscaling: + + * On an **existing deployment**, open the deployment **Edit** page to find the option to turn on autoscaling. + * When you create a new deployment, you can find the autoscaling option under **Advanced settings**. + + Once you confirm your changes or create a new deployment, autoscaling is activated with system default settings that you can adjust as needed (though for most use cases the default settings will likely suffice). + +2. View and adjust autoscaling settings on data tiers: + + 1. Open the **Edit** page for your deployment to get the current and maximum size per zone of each Elasticsearch data tier. In this example, the hot data and content tier has the following settings: + + | | | | + | --- | --- | --- | + | **Current size per zone** | **Maximum size per zone** | | + | 45GB storage | 1.41TB storage | | + | 1GB RAM | 32GB RAM | | + | Up to 2.5 vCPU | 5 vCPU | | + + The fault tolerance for the data tier is set to 2 availability zones. + + :::{image} ../../images/cloud-enterprise-ec-ce-autoscaling-data-summary2.png + :alt: A screenshot showing sizing information for the autoscaled data tier + ::: + + 2. Use the dropdown boxes to adjust the current and/or the maximum size of the data tier. Capacity will be added to the hot content and data tier when required, based on its past and present storage usage, until it reaches the maximum size per zone. Any scaling events are applied simultaneously across availability zones. In this example, the tier has plenty of room to scale relative to its current size, and it will not scale above the maximum size setting. There is no minimum size setting since downward scaling is currently not supported on data tiers. + +3. View and adjust autoscaling settings on a machine learning instance: + + 1. From the deployment **Edit** page you can check the minimum and maximum size of your deployment’s machine learning instances. In this example, the machine learning instance has the following settings: + + | | | | + | --- | --- | --- | + | **Minimum size per zone** | **Maximum size per zone** | | + | 1GB RAM | 64GB RAM | | + | 0.5 vCPU up to 8 vCPU | 32 vCPU | | + + The fault tolerance for the machine learning instance is set to 1 availability zone. + + :::{image} ../../images/cloud-enterprise-ec-ce-autoscaling-ml-summary2.png + :alt: A screenshot showing sizing information for the autoscaled machine learning node + ::: + + 2. Use the dropdown boxes to adjust the minimum and/or the maximum size of the data tier. Capacity will be added to or removed from the machine learning instances as needed. The need for a scaling event is determined by the expected memory and vCPU requirements for the currently configured machine learning job. Any scaling events are applied simultaneously across availability zones. Note that unlike data tiers, machine learning nodes do not have a **Current size per zone** setting. That setting is not needed since machine learning nodes support both upward and downward scaling. + +4. Over time, the volume of data and the size of any machine learning jobs in your deployment are likely to grow. Let’s assume that to meet storage requirements your hot data tier has scaled up to its maximum allowed size of 64GB RAM and 32 vCPU. At this point, a notification appears on the deployment overview page indicating that the tier has scaled to capacity. +5. If you expect a continued increase in either storage, memory, or vCPU requirements, you can use the **Maximum size per zone** dropdown box to adjust the maximum capacity settings for your data tiers and machine learning instances, as appropriate. And, you can always re-adjust these levels downward if the requirements change. + +As you can see, autoscaling greatly reduces the manual work involved to manage a deployment. The deployment capacity adjusts automatically as demands change, within the boundaries that you define. Check our main [Deployment autoscaling](../autoscaling.md) page for more information. + diff --git a/deploy-manage/autoscaling/ece-autoscaling.md b/deploy-manage/autoscaling/ece-autoscaling.md new file mode 100644 index 000000000..7bfca2447 --- /dev/null +++ b/deploy-manage/autoscaling/ece-autoscaling.md @@ -0,0 +1,130 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-autoscaling.html +--- + +# Deployment autoscaling [ece-autoscaling] + +Autoscaling helps you to more easily manage your deployments by adjusting their available resources automatically, and currently supports scaling for both data and machine learning nodes, or machine learning nodes only. Check the following sections to learn more: + +* [Overview](../autoscaling.md#ece-autoscaling-intro) +* [When does autoscaling occur?](../autoscaling.md#ece-autoscaling-factors) +* [Notifications](../autoscaling.md#ece-autoscaling-notifications) +* [Restrictions and limitations](../autoscaling.md#ece-autoscaling-restrictions) +* [Enable or disable autoscaling](../autoscaling.md#ece-autoscaling-enable) +* [Update your autoscaling settings](../autoscaling.md#ece-autoscaling-update) + +You can also have a look at our [autoscaling example](ece-autoscaling-example.md), as well as a sample request to [create an autoscaled deployment through the API](ece-autoscaling-api-example.md). + + +## Overview [ece-autoscaling-intro] + +When you first create a deployment it can be challenging to determine the amount of storage your data nodes will require. The same is relevant for the amount of memory and CPU that you want to allocate to your machine learning nodes. It can become even more challenging to predict these requirements for weeks or months into the future. In an ideal scenario, these resources should be sized to both ensure efficient performance and resiliency, and to avoid excess costs. Autoscaling can help with this balance by adjusting the resources available to a deployment automatically as loads change over time, reducing the need for monitoring and manual intervention. + +::::{note} +Autoscaling is enabled for the Machine Learning tier by default for new deployments. +:::: + + +Currently, autoscaling behavior is as follows: + +* **Data tiers** + + * Each Elasticsearch [data tier](../../manage-data/lifecycle/data-tiers.md) scales upward based on the amount of available storage. When we detect more storage is needed, autoscaling will scale up each data tier independently to ensure you can continue and ingest more data to your hot and content tier, or move data to the warm, cold, or frozen data tiers. + * In addition to scaling up existing data tiers, a new data tier will be automatically added when necessary, based on your [index lifecycle management policies](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-index-management.html). + * To control the maximum size of each data tier and ensure it will not scale above a certain size, you can use the maximum size per zone field. + * Autoscaling based on memory or CPU, as well as autoscaling downward, is not currently supported. In case you want to adjust the size of your data tier to add more memory or CPU, or in case you deleted data and want to scale it down, you can set the current size per zone of each data tier manually. + +* **Machine learning nodes** + + * Machine learning nodes can scale upward and downward based on the configured machine learning jobs. + * When a machine learning job is opened, or a machine learning trained model is deployed, if there are no machine learning nodes in your deployment, the autoscaling mechanism will automatically add machine learning nodes. Similarly, after a period of no active machine learning jobs, any enabled machine learning nodes are disabled automatically. + * To control the maximum size of your machine learning nodes and ensure they will not scale above a certain size, you can use the maximum size per zone field. + * To control the minimum size of your machine learning nodes and ensure the autoscaling mechanism will not scale machine learning below a certain size, you can use the minimum size per zone field. + * The determination of when to scale is based on the expected memory and CPU requirements for the currently configured machine learning jobs and trained models. + + +::::{note} +For any Elastic Cloud Enterprise Elasticsearch component the number of availability zones is not affected by autoscaling. You can always set the number of availability zones manually and the autoscaling mechanism will add or remove capacity per availability zone. +:::: + + + +## When does autoscaling occur? [ece-autoscaling-factors] + +Several factors determine when data tiers or machine learning nodes are scaled. + +For a data tier, an autoscaling event can be triggered in the following cases: + +* Based on an assessment of how shards are currently allocated, and the amount of storage and buffer space currently available. + +When past behavior on a hot tier indicates that the influx of data can increase significantly in the near future. Refer to [Reactive storage decider](autoscaling-deciders.md) and [Proactive storage decider](autoscaling-deciders.md) for more detail. + +* Through ILM policies. For example, if a deployment has only hot nodes and autoscaling is enabled, it automatically creates warm or cold nodes, if an ILM policy is trying to move data from hot to warm or cold nodes. + +On machine learning nodes, scaling is determined by an estimate of the memory and CPU requirements for the currently configured jobs and trained models. When a new machine learning job tries to start, it looks for a node with adequate native memory and CPU capacity. If one cannot be found, it stays in an `opening` state. If this waiting job exceeds the queueing limit set in the machine learning decider, a scale up is requested. Conversely, as machine learning jobs run, their memory and CPU usage might decrease or other running jobs might finish or close. In this case, if the duration of decreased resource usage exceeds the set value for `down_scale_delay`, a scale down is requested. Check [Machine learning decider](autoscaling-deciders.md) for more detail. To learn more about machine learning jobs in general, check [Create anomaly detection jobs](https://www.elastic.co/guide/en/machine-learning/current/create-jobs.html). + +On a highly available deployment, autoscaling events are always applied to instances in each availability zone simultaneously, to ensure consistency. + + +## Notifications [ece-autoscaling-notifications] + +In the event that a data tier or machine learning node scales up to its maximum possible size, a notice appears on the deployment overview page prompting you to adjust your autoscaling settings in order to ensure optimal performance. + +A warning is also issued in the ECE `service-constructor` logs with the field `labels.autoscaling_notification_type` and a value of `data-tier-at-limit` (for a fully scaled data tier) or `ml-tier-at-limit` (for a fully scaled machine learning node). The warning is indexed in the `logging-and-metrics` deployment, so you can use that event to [configure an email notification](../../explore-analyze/alerts/watcher/actions-email.md). + + +## Restrictions and limitations [ece-autoscaling-restrictions] + +The following are known limitations and restrictions with autoscaling: + +* Autoscaling will not run if the cluster is unhealthy or if the last Elasticsearch plan failed. +* In the event that an override is set for the instance size or disk quota multiplier for an instance by means of the [Instance Overrides API](https://www.elastic.co/guide/en/cloud-enterprise/current/set-all-instances-settings-overrides.html), autoscaling will be effectively disabled. It’s recommended to avoid adjusting the instance size or disk quota multiplier for an instance that uses autoscaling, since the setting prevents autoscaling. + + +## Enable or disable autoscaling [ece-autoscaling-enable] + +To enable or disable autoscaling on a deployment: + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. In your deployment menu, select **Edit**. +4. Select desired autoscaling configuration for this deployment using **Enable Autoscaling for:** dropdown menu. +5. Select **Confirm** to have the autoscaling change and any other settings take effect. All plan changes are shown on the Deployment **Activity** page. + +When autoscaling has been enabled, the autoscaled nodes resize according to the [autoscaling settings](../autoscaling.md#ece-autoscaling-update). Current sizes are shown on the deployment overview page. + +When autoscaling has been disabled, you need to adjust the size of data tiers and machine learning nodes manually. + + +## Update your autoscaling settings [ece-autoscaling-update] + +Each autoscaling setting is configured with a default value. You can adjust these if necessary, as follows: + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. In your deployment menu, select **Edit**. +4. To update a data tier: + + 1. Use the dropdown box to set the **Maximum size per zone** to the largest amount of resources that should be allocated to the data tier automatically. The resources will not scale above this value. + 2. You can also update the **Current size per zone**. If you update this setting to match the **Maximum size per zone**, the data tier will remain fixed at that size. + 3. For a hot data tier you can also adjust the **Forecast window**. This is the duration of time, up to the present, for which past storage usage is assessed in order to predict when additional storage is needed. + 4. Select **Save** to apply the changes to your deployment. + +5. To update machine learning nodes: + + 1. Use the dropdown box to set the **Minimum size per zone** and **Maximum size per zone** to the smallest and largest amount of resources, respectively, that should be allocated to the nodes automatically. The resources allocated to machine learning will not exceed these values. If you set these two settings to the same value, the machine learning node will remain fixed at that size. + 2. Select **Save** to apply the changes to your deployment. + + +You can also view our [example](ece-autoscaling-example.md) of how the autoscaling settings work. + +::::{note} +On Elastic Cloud Enterprise, system-owned deployment templates include the default values for all deployment autoscaling settings. +:::: diff --git a/deploy-manage/autoscaling/ech-autoscaling-example.md b/deploy-manage/autoscaling/ech-autoscaling-example.md new file mode 100644 index 000000000..556d0f1a3 --- /dev/null +++ b/deploy-manage/autoscaling/ech-autoscaling-example.md @@ -0,0 +1,58 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-autoscaling-example.html +--- + +# Autoscaling example [ech-autoscaling-example] + +To help you better understand the available autoscaling settings, this example describes a typical autoscaling workflow on sample Elasticsearch Add-On for Heroku deployment. + +1. Enable autoscaling: + + * On an **existing deployment**, open the deployment **Edit** page to find the option to turn on autoscaling. + * When you create a new deployment, you can find the autoscaling option under **Advanced settings**. + + Once you confirm your changes or create a new deployment, autoscaling is activated with system default settings that you can adjust as needed (though for most use cases the default settings will likely suffice). + +2. View and adjust autoscaling settings on data tiers: + + 1. Open the **Edit** page for your deployment to get the current and maximum size per zone of each Elasticsearch data tier. In this example, the hot data and content tier has the following settings: + + | | | | + | --- | --- | --- | + | **Current size per zone** | **Maximum size per zone** | | + | 45GB storage | 1.41TB storage | | + | 1GB RAM | 32GB RAM | | + | Up to 2.5 vCPU | 5 vCPU | | + + The fault tolerance for the data tier is set to 2 availability zones. + + :::{image} ../../images/cloud-heroku-ec-ce-autoscaling-data-summary2.png + :alt: A screenshot showing sizing information for the autoscaled data tier + ::: + + 2. Use the dropdown boxes to adjust the current and/or the maximum size of the data tier. Capacity will be added to the hot content and data tier when required, based on its past and present storage usage, until it reaches the maximum size per zone. Any scaling events are applied simultaneously across availability zones. In this example, the tier has plenty of room to scale relative to its current size, and it will not scale above the maximum size setting. There is no minimum size setting since downward scaling is currently not supported on data tiers. + +3. View and adjust autoscaling settings on a machine learning instance: + + 1. From the deployment **Edit** page you can check the minimum and maximum size of your deployment’s machine learning instances. In this example, the machine learning instance has the following settings: + + | | | | + | --- | --- | --- | + | **Minimum size per zone** | **Maximum size per zone** | | + | 1GB RAM | 64GB RAM | | + | 0.5 vCPU up to 8 vCPU | 32 vCPU | | + + The fault tolerance for the machine learning instance is set to 1 availability zone. + + :::{image} ../../images/cloud-heroku-ec-ce-autoscaling-ml-summary2.png + :alt: A screenshot showing sizing information for the autoscaled machine learning node + ::: + + 2. Use the dropdown boxes to adjust the minimum and/or the maximum size of the data tier. Capacity will be added to or removed from the machine learning instances as needed. The need for a scaling event is determined by the expected memory and vCPU requirements for the currently configured machine learning job. Any scaling events are applied simultaneously across availability zones. Note that unlike data tiers, machine learning nodes do not have a **Current size per zone** setting. That setting is not needed since machine learning nodes support both upward and downward scaling. + +4. Over time, the volume of data and the size of any machine learning jobs in your deployment are likely to grow. Let’s assume that to meet storage requirements your hot data tier has scaled up to its maximum allowed size of 64GB RAM and 32 vCPU. At this point, a notification appears on the deployment overview page letting you know that the tier has scaled to capacity. You’ll also receive an alert by email. +5. If you expect a continued increase in either storage, memory, or vCPU requirements, you can use the **Maximum size per zone** dropdown box to adjust the maximum capacity settings for your data tiers and machine learning instances, as appropriate. And, you can always re-adjust these levels downward if the requirements change. + +As you can see, autoscaling greatly reduces the manual work involved to manage a deployment. The deployment capacity adjusts automatically as demands change, within the boundaries that you define. Check our main [Deployment autoscaling](../autoscaling.md) page for more information. + diff --git a/deploy-manage/autoscaling/ech-autoscaling.md b/deploy-manage/autoscaling/ech-autoscaling.md new file mode 100644 index 000000000..35f6f140f --- /dev/null +++ b/deploy-manage/autoscaling/ech-autoscaling.md @@ -0,0 +1,123 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-autoscaling.html +--- + +# Deployment autoscaling [ech-autoscaling] + +Autoscaling helps you to more easily manage your deployments by adjusting their available resources automatically, and currently supports scaling for both data and machine learning nodes, or machine learning nodes only. Check the following sections to learn more: + +* [Overview](../autoscaling.md#ech-autoscaling-intro) +* [When does autoscaling occur?](../autoscaling.md#ech-autoscaling-factors) +* [Notifications](../autoscaling.md#ech-autoscaling-notifications) +* [Restrictions and limitations](../autoscaling.md#ech-autoscaling-restrictions) +* [Enable or disable autoscaling](../autoscaling.md#ech-autoscaling-enable) +* [Update your autoscaling settings](../autoscaling.md#ech-autoscaling-update) + +You can also have a look at our [autoscaling example](ech-autoscaling-example.md). + + +## Overview [ech-autoscaling-intro] + +When you first create a deployment it can be challenging to determine the amount of storage your data nodes will require. The same is relevant for the amount of memory and CPU that you want to allocate to your machine learning nodes. It can become even more challenging to predict these requirements for weeks or months into the future. In an ideal scenario, these resources should be sized to both ensure efficient performance and resiliency, and to avoid excess costs. Autoscaling can help with this balance by adjusting the resources available to a deployment automatically as loads change over time, reducing the need for monitoring and manual intervention. + +::::{note} +Autoscaling is enabled for the Machine Learning tier by default for new deployments. +:::: + + +Currently, autoscaling behavior is as follows: + +* **Data tiers** + + * Each Elasticsearch [data tier](../../manage-data/lifecycle/data-tiers.md) scales upward based on the amount of available storage. When we detect more storage is needed, autoscaling will scale up each data tier independently to ensure you can continue and ingest more data to your hot and content tier, or move data to the warm, cold, or frozen data tiers. + * In addition to scaling up existing data tiers, a new data tier will be automatically added when necessary, based on your index lifecycle management policies. + * To control the maximum size of each data tier and ensure it will not scale above a certain size, you can use the maximum size per zone field. + * Autoscaling based on memory or CPU, as well as autoscaling downward, is not currently supported. In case you want to adjust the size of your data tier to add more memory or CPU, or in case you deleted data and want to scale it down, you can set the current size per zone of each data tier manually. + +* **Machine learning nodes** + + * Machine learning nodes can scale upward and downward based on the configured machine learning jobs. + * When a machine learning job is opened, or a machine learning trained model is deployed, if there are no machine learning nodes in your deployment, the autoscaling mechanism will automatically add machine learning nodes. Similarly, after a period of no active machine learning jobs, any enabled machine learning nodes are disabled automatically. + * To control the maximum size of your machine learning nodes and ensure they will not scale above a certain size, you can use the maximum size per zone field. + * To control the minimum size of your machine learning nodes and ensure the autoscaling mechanism will not scale machine learning below a certain size, you can use the minimum size per zone field. + * The determination of when to scale is based on the expected memory and CPU requirements for the currently configured machine learning jobs and trained models. + + +::::{note} +For any Elasticsearch Add-On for Heroku Elasticsearch component the number of availability zones is not affected by autoscaling. You can always set the number of availability zones manually and the autoscaling mechanism will add or remove capacity per availability zone. +:::: + + + +## When does autoscaling occur? [ech-autoscaling-factors] + +Several factors determine when data tiers or machine learning nodes are scaled. + +For a data tier, an autoscaling event can be triggered in the following cases: + +* Based on an assessment of how shards are currently allocated, and the amount of storage and buffer space currently available. + +When past behavior on a hot tier indicates that the influx of data can increase significantly in the near future. Refer to [Reactive storage decider](autoscaling-deciders.md) and [Proactive storage decider](autoscaling-deciders.md) for more detail. + +* Through ILM policies. For example, if a deployment has only hot nodes and autoscaling is enabled, it automatically creates warm or cold nodes, if an ILM policy is trying to move data from hot to warm or cold nodes. + +On machine learning nodes, scaling is determined by an estimate of the memory and CPU requirements for the currently configured jobs and trained models. When a new machine learning job tries to start, it looks for a node with adequate native memory and CPU capacity. If one cannot be found, it stays in an `opening` state. If this waiting job exceeds the queueing limit set in the machine learning decider, a scale up is requested. Conversely, as machine learning jobs run, their memory and CPU usage might decrease or other running jobs might finish or close. In this case, if the duration of decreased resource usage exceeds the set value for `down_scale_delay`, a scale down is requested. Check [Machine learning decider](autoscaling-deciders.md) for more detail. To learn more about machine learning jobs in general, check [Create anomaly detection jobs](https://www.elastic.co/guide/en/machine-learning/current/create-jobs.html). + +On a highly available deployment, autoscaling events are always applied to instances in each availability zone simultaneously, to ensure consistency. + + +## Notifications [ech-autoscaling-notifications] + +In the event that a data tier or machine learning node scales up to its maximum possible size, you’ll receive an email, and a notice also appears on the deployment overview page prompting you to adjust your autoscaling settings to ensure optimal performance. + + +## Restrictions and limitations [ech-autoscaling-restrictions] + +The following are known limitations and restrictions with autoscaling: + +* Autoscaling will not run if the cluster is unhealthy or if the last Elasticsearch plan failed. + + +## Enable or disable autoscaling [ech-autoscaling-enable] + +To enable or disable autoscaling on a deployment: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the **Deployments** page, select your deployment. + + Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. In your deployment menu, select **Edit**. +4. Select desired autoscaling configuration for this deployment using **Enable Autoscaling for:** dropdown menu. +5. Select **Confirm** to have the autoscaling change and any other settings take effect. All plan changes are shown on the Deployment **Activity** page. + +When autoscaling has been enabled, the autoscaled nodes resize according to the [autoscaling settings](../autoscaling.md#ech-autoscaling-update). Current sizes are shown on the deployment overview page. + +When autoscaling has been disabled, you need to adjust the size of data tiers and machine learning nodes manually. + + +## Update your autoscaling settings [ech-autoscaling-update] + +Each autoscaling setting is configured with a default value. You can adjust these if necessary, as follows: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the **Deployments** page, select your deployment. + + Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. In your deployment menu, select **Edit**. +4. To update a data tier: + + 1. Use the dropdown box to set the **Maximum size per zone** to the largest amount of resources that should be allocated to the data tier automatically. The resources will not scale above this value. + 2. You can also update the **Current size per zone**. If you update this setting to match the **Maximum size per zone**, the data tier will remain fixed at that size. + 3. For a hot data tier you can also adjust the **Forecast window**. This is the duration of time, up to the present, for which past storage usage is assessed in order to predict when additional storage is needed. + 4. Select **Save** to apply the changes to your deployment. + +5. To update machine learning nodes: + + 1. Use the dropdown box to set the **Minimum size per zone** and **Maximum size per zone** to the smallest and largest amount of resources, respectively, that should be allocated to the nodes automatically. The resources allocated to machine learning will not exceed these values. If you set these two settings to the same value, the machine learning node will remain fixed at that size. + 2. Select **Save** to apply the changes to your deployment. + + +You can also view our [example](ech-autoscaling-example.md) of how the autoscaling settings work. diff --git a/deploy-manage/autoscaling/trained-model-autoscaling.md b/deploy-manage/autoscaling/trained-model-autoscaling.md new file mode 100644 index 000000000..c82e40f25 --- /dev/null +++ b/deploy-manage/autoscaling/trained-model-autoscaling.md @@ -0,0 +1,24 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/serverless/current/general-ml-nlp-auto-scale.html + - https://www.elastic.co/guide/en/serverless/current/general-ml-nlp-auto-scale.html +--- + +# Trained model autoscaling + +% What needs to be done: Align serverless/stateful + +% GitHub issue: https://github.com/elastic/docs-projects/issues/344 + +% Scope notes: Serverless and stateful pages are very similar, might need to merge them together or create subpages + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/docs-content/serverless/general-ml-nlp-auto-scale.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-ml-nlp-auto-scale.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$enabling-autoscaling-in-kibana-adaptive-resources$$$ + +$$$enabling-autoscaling-through-apis-adaptive-allocations$$$ \ No newline at end of file diff --git a/deploy-manage/cloud-organization.md b/deploy-manage/cloud-organization.md new file mode 100644 index 000000000..cb93e3f01 --- /dev/null +++ b/deploy-manage/cloud-organization.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-organizations.html +--- + +# Manage your Cloud organization [ec-organizations] + +When you sign up to Elastic Cloud, you create an organization. + +This organization is the umbrella for all of your Elastic Cloud resources, users, and account settings. Every organization has a unique identifier. Bills are invoiced according to the billing contact and details that you set for your organization. + +From the Organization page, you can: + +* [Manage members of your organization](users-roles/cloud-organization/manage-users.md) +* [Leave an organization](users-roles/cloud-organization/manage-users.md#ec-leave-organization) +* [Assign user roles and privileges](users-roles/cloud-organization/user-roles.md) +* [Create API keys for using the Elastic Cloud API](api-keys/elastic-cloud-api-keys.md#ec-api-keys) +* [Configure SAML single sign-on for your organization](users-roles/cloud-organization/configure-saml-authentication.md) + diff --git a/deploy-manage/cloud-organization/billing.md b/deploy-manage/cloud-organization/billing.md new file mode 100644 index 000000000..34c130ca7 --- /dev/null +++ b/deploy-manage/cloud-organization/billing.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-billing.html + - https://www.elastic.co/guide/en/serverless/current/general-manage-billing.html +--- + +# Billing + +% What needs to be done: Align serverless/stateful + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-billing.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-manage-billing.md \ No newline at end of file diff --git a/deploy-manage/cloud-organization/billing/add-billing-details.md b/deploy-manage/cloud-organization/billing/add-billing-details.md new file mode 100644 index 000000000..76d4303eb --- /dev/null +++ b/deploy-manage/cloud-organization/billing/add-billing-details.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-details.html +--- + +# Add your billing details [ec-billing-details] + +If you want to use Elasticsearch Service beyond the trial period or if you want to use features not included in the trial, you need to add a credit card to your account. Your credit card information is sent securely to our [billing provider](http://recurly.com/security) and stored with them. + +::::{tip} +Trials get converted to paid subscriptions and billing starts when you add a credit card. If you want to maximize your trial, make sure to add your credit card near the end of the trial period. +:::: + + +Just want a quick price estimate? Try our [Elasticsearch Service pricing calculator](https://www.elastic.co/cloud/elasticsearch-service/pricing). Monitor the cost of your deployments by checking [your account usage](monitor-analyze-usage.md). Monthly costs are shown for convenience only, as billing is done by the hour. You can also test with a bigger deployment or try out additional features and only pay for the hours used. + +We also offer [AWS Marketplace](../../deploy/elastic-cloud/aws-marketplace.md), [GCP Marketplace](../../deploy/elastic-cloud/google-cloud-platform-marketplace.md), and [Azure Marketplace](https://www.elastic.co/guide/en/cloud/current/ec-billing-azure.html) billing, if you prefer not to add a credit card directly. + +To add your billing details: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Select the user icon on the header bar and select **Billing** from the menu. +3. On the **Overview** page, select **Add billing information**. +4. If prompted, complete the multifactor authentication (MFA) required by your bank. + +If you want, you can [stop new charges](stop-charges-for-project-deployment.md) by deleting your deployment. + diff --git a/deploy-manage/cloud-organization/billing/billing-faq.md b/deploy-manage/cloud-organization/billing/billing-faq.md new file mode 100644 index 000000000..d196f4801 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/billing-faq.md @@ -0,0 +1,158 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-faq-billing.html +--- + +# Billing FAQ [ec-faq-billing] + +This frequently-asked-questions list answers some of your more common questions about Elasticsearch Service billing. + +**General billing questions** + +* [Is there a way for me to estimate how much Elasticsearch Service will cost?](#faq-cost) +* [Where can I find a detailed view of my consumption?](#faq-consumption) +* [How do I view previous receipts and billing history?](#faq-history) +* [How can I change who receives receipts and billing notifications?](#faq-notify) +* [What are the available payment methods on Elasticsearch Service?](#faq-payment) +* [Who can I contact for more information?](#faq-contact) +* [Why is my credit card charged?](#faq-charge) +* [When is my credit card charged?](#faq-when) +* [Why is my credit card charged if I canceled my trial?](#faq-whystillcharged) +* [What is the cancellation policy for monthly subscriptions?](#faq-cancelpolicy) +* [Why am I being charged if I don’t use any of my deployments?](#faq-chargednotusing) +* [How can I delete my Elastic Cloud account?](#faq-deleteaccount) +* [Can I get a refund?](#faq-refund) +* [What is included in my paid Elasticsearch Service deployment?](#faq-included) +* [What are the data transfer and storage charges and how can I control them?](#faq-dts) +* [What taxes will be applied on my invoice?](#faq-taxes) + +**Prepaid consumption questions** + +* [What purchasing channels can be used for prepaid consumption credits?](#faq-channels) +* [Can I migrate my monthly account to the prepaid consumption model?](#faq-migration) +* [What happens if my credits are depleted mid-year?](#faq-depletion) +* [If I have a multi-year contract and I run out of balance, can I draw against the next year’s credits?](#faq-draw-credits) +* [If my user login is invited to a different organization, what happens to the prepaid credits for the current organization?](#faq-organizations) +* [What kind of subscription level can a customer have on the prepaid consumption model?](#faq-level) +* [Where can I follow the remaining balance and usage?](#faq-usage) +* [How will I know that I am running out of credits?](#faq-notification) +* [How can I pay for on-demand usage?](#faq-on-demand) +* [What happens when a prepaid consumption contract expires and is not renewed?](#faq-lapse) +* [If credits are purchased through multiple orders, which ones get used first?](#faq-credits) +* [What do the prepaid credits cover?](#faq-prepaidcover) + + +## General billing FAQ [ec-faq-billing-general] + +$$$faq-cost$$$Is there a way for me to estimate how much Elasticsearch Service will cost? +: Yes, there is: Try our [Elasticsearch Service Pricing Calculator](https://www.elastic.co/cloud/elasticsearch-service/pricing?page=docs&placement=docs-body). You can also use the [Elasticsearch Service price list](https://ela.st/esspricelist). + +$$$faq-consumption$$$Where can I find a detailed view of my consumption? +: To make it easy to track the ongoing cost of Elasticsearch Service, we’ve added line items to the downloadable [invoices](https://cloud.elastic.co/billing/overview?page=docs&placement=docs-body). + + Example invoice + : :::{image} ../../../images/cloud-ec-bill-example-new.png + :alt: Example invoice + ::: + + Additionally, on the Elasticsearch Service [Usage analysis](https://cloud.elastic.co/billing/usage?page=docs&placement=docs-body) page, the **month-to-date usage** tile shows accrued costs and can help you to better estimate the next charge amount. + + +$$$faq-history$$$How do I view previous receipts and billing history? +: Check the [billing history](https://cloud.elastic.co/billing/history?page=docs&placement=docs-body), where you can view and download receipts for all previous charges. + +$$$faq-notify$$$How can I change who receives receipts and billing notifications? +: The account owner can change who receives receipts and billing notifications by changing the [email details](https://cloud.elastic.co/account/contacts?page=docs&placement=docs-body). + +$$$faq-payment$$$What are the available payment methods on Elasticsearch Service? +: For month-to-month payments only credit cards are accepted. We also allow payments by bank transfer for annual subscriptions. + +$$$faq-contact$$$Who can I contact for more information? +: If you have any further questions about your credit card statement, billing, or receipts, please send an email to `ar@elastic.co` or open a [Support case](../../../troubleshoot/troubleshoot/cloud.md) using the *Billing issue* category. + +$$$faq-charge$$$Why is my credit card charged? +: If you are on a monthly plan, the charge is a recurring fee for using our hosted Elasticsearch Service. The fee is normally charged at the start of each month, but it can also be charged at other times during the month. If a charge is unsuccessful, we will try to charge your card again at a later date. + +$$$faq-when$$$When is my credit card charged? +: You are billed on the first day of each month for usage in the prior month. + +$$$faq-whystillcharged$$$Why is my credit card charged if I canceled my trial? +: If you add a credit card to your Elastic Cloud account at any time during the trial period, the trial is converted to a paid subscription. You then have to pay for any expense incurred by your deployment beginning when the credit card was added. If you delete your deployment at a later date, you will still be invoiced for any usage that occurs between the conversion date and the deployment deletion date. + +$$$faq-cancelpolicy$$$What is the cancellation policy for monthly subscriptions? +: There are no cancellation or termination fees for monthly subscriptions. If the service is no longer needed, you can spin down all of your deployments. Usage for that month will be billed at the end of the month in your final bill. + +$$$faq-chargednotusing$$$Why am I being charged if I don’t use any of my deployments? +: Even if you have no activity on your account and you haven’t logged into the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), your active deployments still incur costs that we need to charge you for. To avoid being charged for active but unused deployments, you can simply delete them. Your account will stay active with no charges, and you can always spin up more capacity when you need it. + +$$$faq-deleteaccount$$$How can I delete my Elastic Cloud account? +: To have your account removed, you can contact support through the Elasticsearch Service [Support form](https://cloud.elastic.co/support?page=docs&placement=docs-body) or use one of these [alternative contact methods](../../../troubleshoot/troubleshoot/cloud.md). For details about our data erasure policy, check [Privacy Rights and Choices](https://www.elastic.co/legal/privacy-statement#privacy-rights-and-choices?page=docs&placement=docs-body) in our General Privacy Statement. + +$$$faq-refund$$$Can I get a refund? +: Charges are non-refundable, but once you delete a deployment we’ll stop charging you for that deployment immediately. You only pay for what you use and you can stop using the service at any time. For any special considerations warranting a potential refund, please use the Elasticsearch Service Console [Support form](https://cloud.elastic.co/support?page=docs&placement=docs-body) to open a support case and select *Billing issue* as the category. To ensure quick processing, be sure to provide detail about the reasons for the refund request as well as other matters pertaining to the issue. For other ways to open a Support case, check [Getting help](../../../troubleshoot/troubleshoot/cloud.md). + +$$$faq-included$$$What is included in my paid Elasticsearch Service deployment? +: All subscription tiers for the Elasticsearch Service include the following free allowance: + + * Free 1GB RAM Kibana instance + * Free 1GB RAM Machine Learning node + * Free 2GB RAM Enterprise Search instance + * Free 1GB RAM APM server + * A free allowance for [data transfer and snapshot storage costs](#faq-dts) + + Note that if you go above the free tier of Kibana/ML/APM (for example, a 2GB Kibana instance), you will be charged in full for the size of that instance. + + +$$$faq-dts$$$What are the data transfer and storage charges and how can I control them? +: Read about our [usage-based billing dimensions](cloud-hosted-deployment-billing-dimensions.md). + +$$$faq-taxes$$$What taxes will be applied on my invoice? +: Customers within the United States, and US territories, will be billed from Elasticsearch Inc., based out of the United States. The US Sales Tax rate will be based on the SaaS tax rates in the local jurisdiction (state/county/city) of the billing address of your subscription. + + Customers outside the United States, will be billed from Elasticsearch BV, based out of the Netherlands. Customers with a billing address in countries with applicable EU VAT will have VAT applied based on their country and status as a business or private customer. Elastic collects VAT Numbers associated with EU VAT to determine your status as a business (B2B) or private / non-business customer (B2C), as this is a key factor to determine Elastic’s liability to charge VAT on your subscription. To update your VAT Number follow the instructions provided in [Add your billing details](https://www.elastic.co/guide/en/cloud/current/ec-billing-details.html). Customers located in countries without EU VAT will not be applied VAT on their invoices. + + + +## Prepaid consumption FAQ [ec-faq-consumption] + +The following section applies to annual contracts that are billed on the prepaid consumption billing model. + +$$$faq-channels$$$What purchasing channels can be used for prepaid consumption credits? +: The prepaid consumption billing model is currently only available for Elastic Direct customers - customers who are purchasing directly from Elastic. This offering may expand to marketplace customers in the future. + +$$$faq-migration$$$Can I migrate my monthly account to the prepaid consumption model? +: Yes, if you have a monthly Elasticsearch Service account, you can [contact us](https://www.elastic.co/cloud/contact) to migrate to prepaid consumption. + +$$$faq-depletion$$$What happens if I run out of credits? +: If your credit balance is entirely consumed while you have an active contract, you can continue to use Elastic Cloud and will receive invoices for the additional on-demand usage. + + * By default, the on-demand usage is billed at the list price in ECU, and invoiced at the currency equivalent. + * If you have future credit line items that are not active yet, the on-demand usage is billed at the rate of the last active credit line item, using the same payment method. Any discounts that applied to that last active credit line item also apply to the on-demand usage until the next line item becomes active. + + +$$$faq-draw-credits$$$If I have a multi-year contract and I run out of balance, can I draw against the next year’s credits? +: No, this option is currently not available. + +$$$faq-organizations$$$If my user login is invited to a different organization, what happens to the prepaid credits for the current organization? +: Prepaid credits are always assigned to a given organization and NOT to a specific user account. If a user is invited to a different organization, they will not carry the prepaid credits to the new organization. + +$$$faq-level$$$What kind of subscription level can a customer have on the prepaid consumption model? +: When the credits are first provisioned, your Cloud account will be set to Enterprise. You can [change your subscription level](manage-subscription.md) at any time. We are offering only Gold, Platinum, and Enterprise support levels for prepaid consumption customers. Standard is not offered for prepaid consumption. + +$$$faq-usage$$$Where can I follow the remaining balance and usage? +: The current usage and remaining balance can be found in the [Usage](monitor-analyze-usage.md) page. You will also receive monthly usage statements that are published in the [Billing history](view-billing-history.md) page. + +$$$faq-notification$$$How will I know that I am running out of credits? +: Your account billing contacts and the members of your organization will receive email notifications when your credit balance falls below 33%, 25%, and 16% of credits remaining. + +$$$faq-on-demand$$$How can I pay for on-demand usage? +: We only support PO (invoicing) for on-demand usage, for prepaid consumption customers. The issued invoices include tax. + +$$$faq-lapse$$$What happens when a prepaid consumption contract expires and is not renewed? +: Your Elastic Cloud account will automatically change into a monthly account, paid through PO (invoicing). You will continue to incur costs, as we will not delete any of your deployments. You will not benefit from any discount because monthly customers are billed at list prices. To switch your account to credit card payment, you must first send an email to `CloudBillingOps@elastic.co` to indicate that this is your new preferred payment method. Once your email processed, Elastic will inform you that you can update your credit card information accordingly. + +$$$faq-credits$$$If credits are purchased through multiple orders, which ones get used first? +: Credits get consumed in the order of expiration (first expired - first used). If two or more order lines have the same expiration date, the one with the highest discount is consumed first. If there are two or more order lines with the same discount, then the one with the lower balance is consumed first. + +$$$faq-prepaidcover$$$What do the prepaid credits cover? +: If you have an annual contract, your prepaid credits are used to cover all usage, including capacity, data transfer, and snapshot storage. diff --git a/deploy-manage/cloud-organization/billing/billing-models.md b/deploy-manage/cloud-organization/billing/billing-models.md new file mode 100644 index 000000000..6262d30bf --- /dev/null +++ b/deploy-manage/cloud-organization/billing/billing-models.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-models.html + - https://www.elastic.co/guide/en/cloud/current/ec-billing-ecu.html +--- + +# Billing models + +% What needs to be done: Refine + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-billing-models.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-billing-ecu.md \ No newline at end of file diff --git a/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.md b/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.md new file mode 100644 index 000000000..df2eb4eb0 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.md @@ -0,0 +1,102 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-dimensions.html +--- + +# Cloud hosted deployment billing dimensions [ec-billing-dimensions] + +Elasticsearch Service Billing is based on your actual usage across a number of dimensions, as follows: + +1. [Deployment capacity](#ram-hours) +2. [Data Transfer](#data-transfer) +3. [Storage](#storage) +4. [Synthetics](#synthetics) +5. [Serverless](https://docs.elastic.co/serverless/general/manage-billing) + +Read on for detail about each of these billing dimensions. + + +## Deployment capacity [ram-hours] + +Deployment capacity refers to the cost of the nodes in your Elasticsearch deployment, plus additional node types such as Kibana, APM, and ML. Each node type is priced in terms of GB of RAM per hour (CPU and disk are scaled with RAM and included in this price). To calculate deployment capacity costs, we total up the cost of the nodes in your deployment(s) and multiply by GBs of RAM and how long they’ve been running. + +Deployment capacity typically constitutes the majority of your bill, and is the easiest to understand and control. + + +### How can I control the deployment capacity cost? [ec_how_can_i_control_the_deployment_capacity_cost] + +Deployment capacity is purely a function of your current deployment configuration and time. To reduce this cost, you must [configure your deployment](../../deploy/elastic-cloud/configure.md) to use fewer resources. To determine how much a particular deployment configuration will cost, try our [Elasticsearch Service Pricing Calculator](https://cloud.elastic.co/pricing). + + +## Data Transfer [data-transfer] + +Data Transfer accounts for the volume of data (payload) going into, out of, and between the nodes in a deployment, which is summed up to a cumulative amount within a billing cycle. + +We meter and bill data transfer using three dimensions: + +1. Data in (free) +: *Data in* accounts for all of the traffic going into the deployment. It includes index requests with data payload, as well as queries sent to the deployment (although the byte size of the latter is typically much smaller). + +2. Data out +: *Data out* accounts for all of the traffic coming out of the deployment. This includes search results, as well as monitoring data sent from the deployment. The same rate applies regardless of the destination of the data, whether to the internet, to another region, or to a cloud provider account in the same region. Data coming out of the deployment through AWS PrivateLink, GCP Private Service Connect, or Azure Private Link, is also considered *Data out*. + +3. Data inter-node +: *Data inter-node* accounts for all of the traffic sent between the components of the deployment. This includes the data sync between nodes of a cluster which is managed automatically by Elasticsearch cluster sharding. It also includes data related to search queries executed across multiple nodes of a cluster. Note that single-node Elasticsearch clusters typically have lower charges, but may still incur inter-node charges accounting for data exchanged with Kibana nodes or other nodes, such as machine learning or APM. + +We provide a free allowance of 100GB per month, which includes the sum of *data out* and *data inter-node*, across all deployments in the account. Once this threshold is passed, a charge is applied for any data transfer used in excess of the 100GB monthly free allowance. + +::::{note} +Data inter-node charges are currently waived for Azure deployments. +:::: + + + +### How can I control the Data Transfer cost? [ec_how_can_i_control_the_data_transfer_cost] + +Data transfer out of deployments and between nodes of the cluster is hard to control, as it is a function of the use case employed for the cluster and cannot always be tuned. Use cases such as batch queries executed at a frequent interval may be revisited to help lower transfer costs, if applicable. Watcher email alerts also count towards data transfer out of the deployment, so you may want to reduce their frequency and size. + +The largest contributor to inter-node data transfer is usually shard movement between nodes in a cluster. The only way to prevent shard movement is by having a single node in a single availability zone. This solution is only possible for clusters up to 64GB RAM and is not recommended as it creates a risk of data loss. [Oversharding](https://www.elastic.co/guide/en/elasticsearch/reference/current/avoid-oversharding.html) can cause excessive shard movement. Avoiding oversharding can also help control costs and improve performance. Note that creating snapshots generates inter-node data transfer. The *storage* cost of snapshots is detailed later in this document. + +The exact root cause of unusual data transfer is not always something we can identify as it can have many causes, some of which are out of our control and not associated with Cloud configuration changes. It may help to [enable monitoring](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) and examine index and shard activity on your cluster. + + +## Storage [storage] + +Storage costs are tied to the cost of storing the backup snapshots in the underlying IaaS object store, such as AWS S3, Google Cloud GCS or Azure Storage. These storage costs are *not* for the disk storage that persists the Elasticsearch indices, as that is already included in the [RAM Hours](#ram-hours). + +As is common with Cloud providers, we meter and bill snapshot storage using two dimensions: + +1. Storage size (GB/month) +: This is calculated by metering the storage space (GBs) occupied by all snapshots of all deployments tied to an account. The same unit price applies to all regions. To calculate the due charges, we meter the amount of storage on an hourly basis and produce an average size (in GB) for a given month. The average amount is then used to bill the account for the GB/month used within a billing cycle (a calendar month). + + For example, if the storage used in April 2019 was 100GB for 10 days, and then 130GB for the remaining 20 days of the month, the average storage would be 120 GB/month, calculated as (100*10 + 130*20)/30. + + We provide a free allowance of 100 GB/month to all accounts across all the account deployments. Any metered storage usage below that amount will not be billed. Whenever the 100 GB/month threshold is crossed, we bill for the storage used in excess of the 100GB/month free allowance. + + +2. Storage API requests (1K Requests/month) +: These costs are calculated by counting the total number of calls to backup or restore snapshots made by all deployments associated with an account. Unlike storage size, this dimension is cumulative, summed up across the billing cycle, and is billed at a price of 1,000 requests. + + We provide a free allowance of 100,000 API requests to all accounts each month across all the account deployments. Once this threshold is passed, we bill only for the use of API requests in excess of the free allowance. + + ::::{note} + A single snapshot operation does not equal a single API call. There could be thousands of API calls associated with a single snapshot operation, as different files are written, deleted, and modified. The price we list is per 1000 API calls, so a rate of $0.0018 for 1000 API calls would cost $1.80 for a million calls. + :::: + + + +### How can I control the storage cost? [ec_how_can_i_control_the_storage_cost] + +Snapshots in Elasticsearch Service save data incrementally at each snapshot event. This means that the effective snapshot size may be larger than the size of the current indices. The snapshot size increases as data is added or updated in the cluster, and deletions do not reduce the snapshot size until the snapshot containing that data is removed. + +API requests are executed every time a snapshot is taken or restored, affecting usage costs. In the event that you have any automated processes that use the Elasticsearch API to create or restore snapshots, these should be set so as to avoid unexpected charges. + +You can use Kibana to configure a snapshot lifecycle management (SLM) policy to automate when snapshots are created and deleted, along with other options. To learn more, refer to the [Snapshot and Restore](../../tools/snapshot-and-restore/create-snapshots.md) documentation. + +Note that reducing either the snapshot frequency or retention period limits the availability and the recency of available data to restore from. Your snapshot policy should be configured with both costs and data availability in mind in order to minimize the potential for loss of data. Note also that reducing snapshot frequency and retention will not necessarily decrease your storage costs significantly. For example, if your dataset is only growing over time, then the total amount of data stored across all of your snapshots will be equal to your cluster size, whether that’s split across 10 snapshots or 100. + + +## Synthetics [synthetics] + +Synthetic Monitoring browser tests are charged per test run (metered in 60 second increments). Lightweight tests are charged per location per month (per deployment) for up to 1k simultaneous test run capacity (~2.6 billion tests per month). Tests executed from private locations do not incur an execution charge. All test result data is stored in your deployment and billed for under existing dimensions. + diff --git a/deploy-manage/cloud-organization/billing/elastic-observability-billing-dimensions.md b/deploy-manage/cloud-organization/billing/elastic-observability-billing-dimensions.md new file mode 100644 index 000000000..f152302cc --- /dev/null +++ b/deploy-manage/cloud-organization/billing/elastic-observability-billing-dimensions.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/observability-billing.html +--- + +# Elastic Observability billing dimensions [observability-billing] + +{{obs-serverless}} projects provide you with all the capabilities of Elastic Observability to monitor critical applications. Projects are provided using a Software as a Service (SaaS) model, and pricing is entirely consumption-based. + +Your monthly bill is based on the capabilities you use. When you use {{obs-serverless}}, your bill is calculated based on data volume, which has these components: + +* **Ingest** — Measured by the number of GB of log/event/info data that you send to your Observability project over the course of a month. +* **Retention** — Measured by the total amount of ingested data stored in your Observability project. + +Ingest and retention metering is based on the uncompressed, normalized, fully enriched data volume you ingest into your Serverless project. This allows you flexibility and consistency when choosing your preferred ingest architecture for enrichment, whether through {{agent}}, {{ls}}, OpenTelemetry, or collectors—without the need to consider possible impacts on the cost. + +::::{note} +One consequence of this metering method is that the absolute volume of data reported in your usage statement can be much larger than the "raw" data size or the compressed data size "on the wire." Your monthly bill will transparently display exactly how much data has been ingested, including valuable metadata added by your data shipper, and contextual enrichment performed by your ingest processing. Please note that we took the cost of metadata and enrichment into consideration while determining our Serverless per GB prices to help make {{obs-serverless}} a cost-effective service. +:::: + + + +## Synthetics [synthetics-billing] + +[Synthetic monitoring](../../../solutions/observability/apps/synthetic-monitoring.md) is an optional add-on to Observability Serverless projects that allows you to periodically check the status of your services and applications. In addition to the core ingest and retention dimensions, there is a charge to execute synthetic monitors on our testing infrastructure. Browser (journey) based tests are charged per-test-run, and ping (lightweight) tests have an all-you-can-use model per location used. + +Refer to [Serverless billing dimensions](serverless-project-billing-dimensions.md) and the [Elastic Cloud pricing table](https://cloud.elastic.co/cloud-pricing-table?productType=serverless&project=observability) for more details about {{obs-serverless}} billing dimensions and rates. diff --git a/deploy-manage/cloud-organization/billing/elasticsearch-billing-dimensions.md b/deploy-manage/cloud-organization/billing/elasticsearch-billing-dimensions.md new file mode 100644 index 000000000..3a752c264 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/elasticsearch-billing-dimensions.md @@ -0,0 +1,44 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/elasticsearch-billing.html +--- + +# Elasticsearch billing dimensions [elasticsearch-billing] + +Elasticsearch is priced based on consumption of the underlying infrastructure that supports your use case, with the performance characteristics you need. Measurements are in Virtual Compute Units (VCUs). Each VCU represents a fraction of RAM, CPU, and local disk for caching. + +The number of VCUs you need is determined by: + +* Volume and ingestion rate of your data +* Data retention requirements +* Search query volume +* Search Power setting +* Machine learning usage + +For detailed {{es-serverless}} project rates, see the [{{es-serverless}} pricing page](https://www.elastic.co/pricing/serverless-search). + + +## VCU types: Search, Indexing, and ML [elasticsearch-billing-information-about-the-vcu-types-search-ingest-and-ml] + +Elasticsearch uses three VCU types: + +* **Indexing:** The VCUs used to index incoming documents. +* **Search:** The VCUs used to return search results, with the latency and queries per second (QPS) you require. +* **Machine learning:** The VCUs used to perform inference, NLP tasks, and other ML activities. + + +## Data storage and billing [elasticsearch-billing-information-about-the-search-ai-lake-dimension-gb] + +{{es-serverless}} projects store data in the [Search AI Lake](../../deploy/elastic-cloud/project-settings.md#elasticsearch-manage-project-search-ai-lake-settings). You are charged per GB of stored data at rest. Note that if you perform operations at ingest such as vectorization or enrichment, the size of your stored data will differ from the size of the original source data. + + +## Managing {{es}} costs [elasticsearch-billing-managing-elasticsearch-costs] + +You can control costs using the following strategies: + +* **Search Power setting:** [Search Power](../../deploy/elastic-cloud/project-settings.md#elasticsearch-manage-project-search-power-settings) controls the speed of searches against your data. With Search Power, you can improve search performance by adding more resources for querying, or you can reduce provisioned resources to cut costs. +* **Time series data retention:** By limiting the number of days of [time series data](../../../solutions/search/ingest-for-search.md#elasticsearch-ingest-time-series-data) that are available for caching, you can reduce the number of search VCUs required. +* **Machine learning trained model autoscaling:** Configure your trained model deployment to allow it to scale down to zero allocations when there are no active inference requests: + + * When starting or updating a trained model deployment, [Enable adaptive resources](../../autoscaling/trained-model-autoscaling.md#enabling-autoscaling-in-kibana-adaptive-resources) and set the VCU usage level to **Low**. + * When using the inference API for Elasticsearch or ELSER, [enable `adaptive_allocations`](../../autoscaling/trained-model-autoscaling.md#enabling-autoscaling-through-apis-adaptive-allocations). diff --git a/deploy-manage/cloud-organization/billing/manage-subscription.md b/deploy-manage/cloud-organization/billing/manage-subscription.md new file mode 100644 index 000000000..7023cde05 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/manage-subscription.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/serverless/current/general-check-subscription.html + - https://www.elastic.co/guide/en/cloud/current/ec-subscription-overview.html + - https://www.elastic.co/guide/en/cloud/current/ec-select-subscription-level.html +--- + +# Manage your subscription + +% What needs to be done: Align serverless/stateful + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/docs-content/serverless/general-check-subscription.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-subscription-overview.md +% Notes: fix billing dimensions link +% - [ ] ./raw-migrated-files/cloud/cloud/ec-select-subscription-level.md +% Notes: feature usage notifications are cloud only \ No newline at end of file diff --git a/deploy-manage/cloud-organization/billing/monitor-analyze-usage.md b/deploy-manage/cloud-organization/billing/monitor-analyze-usage.md new file mode 100644 index 000000000..059c37f08 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/monitor-analyze-usage.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-account-usage.html + - https://www.elastic.co/guide/en/serverless/current/general-monitor-usage.html +--- + +# Monitor and analyze usage + +% What needs to be done: Align serverless/stateful + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-account-usage.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-monitor-usage.md \ No newline at end of file diff --git a/deploy-manage/cloud-organization/billing/security-billing-dimensions.md b/deploy-manage/cloud-organization/billing/security-billing-dimensions.md new file mode 100644 index 000000000..3c425b4af --- /dev/null +++ b/deploy-manage/cloud-organization/billing/security-billing-dimensions.md @@ -0,0 +1,67 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/security-billing.html +--- + +# Security billing dimensions [security-billing] + +{{elastic-sec}} serverless projects provide you with all the capabilities of {{elastic-sec}} to perform SIEM, security analytics, endpoint security, and cloud security workflows. Projects are provided using a Software as a Service (SaaS) model, and pricing is entirely consumption based. Security Analytics/SIEM is available in two tiers of carefully selected features to enable common security operations: + +* **Security Analytics Essentials** — Includes everything you need to operationalize traditional SIEM in most organizations. +* **Security Analytics Complete** — Adds advanced security analytics and AI-driven features that many organizations will require when upgrading or replacing legacy SIEM systems. + +Your monthly bill is based on the capabilities you use. When you use Security Analytics/SIEM, your bill is calculated based on data volume, which has these components: + +* **Ingest** — Measured by the number of GB of log/event/info data that you send to your Security project over the course of a month. +* **Retention** — Measured by the total amount of ingested data stored in your Security project. + +Data volumes for ingest and retention are based on the fully enriched normalized data size at the end of the ingest pipeline, before {{es}} compression is performed, and will be higher than the volumes traditionally reported by {{es}} index size. In addition, these volumes might be larger than those reported by cloud provider proxy logs for data going into Elasticsearch. This allows you to have flexibility in choosing your preferred ingest architecture for enrichment, whether it’s through {{agent}}, {{ls}}, OpenTelemetry, or collectors — with no impact on the cost. + + +## Endpoint Protection [security-billing-endpoint-protection] + +Endpoint Protection is an *optional* add-on to Security Analytics that provides endpoint protection and threat prevention. Endpoint Protection is available in two tiers of selected features to enable common endpoint security operations: + +* **Endpoint Protection Essentials** — Includes robust protection against malware, ransomware, and other malicious behaviors. +* **Endpoint Protection Complete** — Adds endpoint response actions and advanced policy management. + +You pay based on the number of protected endpoints you configure with the {{elastic-defend}} integration. Note that logs, events, and alerts ingested into your Security project from endpoints running {{elastic-defend}} are billed using the **Ingest** and **Retention** pricing described above. + + +## Cloud Protection [security-billing-cloud-protection] + +Cloud Protection is an *optional* add-on to Security Analytics that provides value-added protection capabilities for cloud assets. Cloud Protection is available in two tiers of carefully selected features to enable common cloud security operations: + +* **Cloud Protection Essentials** — Protects your cloud workloads, continuously tracks posture of your cloud assets, and helps you manage risks by detecting configuration issues per CIS benchmarks. +* **Cloud Protection Complete** — Adds response capabilities. + +Your total cost depends on the number of protected cloud workloads and other billable cloud assets you configure for use with Elastic Cloud Security. + +For [CSPM](../../../solutions/security/cloud/cloud-security-posture-management.md), billing is based on how many billable resources (`resource.id` s) you monitor. The following types of assets are considered billable: + +* VMs: + + * **AWS:** EC2 instances + * **Azure:** Virtual machines + * **GCP:** Compute engine instances + +* Storage resources: + + * **AWS:** S3, S3 Glacier, EBS + * **Azure:** Archive, Blob, Managed disk + * **GCP:** Cloud storage, Persistent disk, Coldline storage + +* SQL databases and servers: + + * **AWS:** RDS, DynamoDB, Redshift + * **Azure:** SQL database, Cosmos DB, Synapse Analytics + * **GCP:** Cloud SQL, Firestore, BigQuery + + +For [KSPM](../../../solutions/security/cloud/kubernetes-security-posture-management.md), billing is based on how many Kubernetes nodes (`agent.id` s) you monitor. + +For [CNVM](../../../solutions/security/cloud/cloud-native-vulnerability-management.md), billing is based on how many cloud assets (`cloud.instance.id` s) you monitor. + +Logs, events, alerts, and configuration data ingested into your security project are billed using the **Ingest** and **Retention** pricing described above. + +For more details about {{elastic-sec}} serverless project rates and billable assets, refer to Cloud Protection in the [Elastic Cloud pricing table](https://cloud.elastic.co/cloud-pricing-table?productType=serverless&project=security). diff --git a/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions.md b/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions.md new file mode 100644 index 000000000..35b3ed3e9 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/general-serverless-billing.html +--- + +# Serverless project billing dimensions [general-serverless-billing] + +Elastic Cloud serverless billing is based on your usage across these dimensions: + +* [Offerings](#offerings) +* [Add-ons](#add-ons) + + +## Offerings [offerings] + +To learn about billing dimensions for specific offerings, refer to: + +* [{{es}} billing dimensions](elasticsearch-billing-dimensions.md) +* [{{obs-serverless}} billing dimensions](elastic-observability-billing-dimensions.md) +* [Security billing dimensions](security-billing-dimensions.md) + + +## Add-ons [add-ons] + + +### Data out [general-serverless-billing-data-out] + +*Data out* accounts for all of the traffic coming out of a serverless project. This includes search results, as well as monitoring data sent from the project. The same rate applies regardless of the destination of the data, whether to the internet, another region, or a cloud provider account in the same region. Data coming out of the project through AWS PrivateLink, GCP Private Service Connect, or Azure Private Link is also considered data out. + + +### Support [general-serverless-billing-support] + +If your subscription level is Standard, there is no separate charge for Support reflected on your bill. If your subscription level is Gold, Platinum, or Enterprise, a charge is made for Support as a percentage (%) of the ECUs. To find out more about our support levels, go to [https://www.elastic.co/support](https://www.elastic.co/support). + diff --git a/deploy-manage/cloud-organization/billing/stop-charges-for-project-deployment.md b/deploy-manage/cloud-organization/billing/stop-charges-for-project-deployment.md new file mode 100644 index 000000000..2515930d1 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/stop-charges-for-project-deployment.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-stop.html + - https://www.elastic.co/guide/en/serverless/current/general-billing-stop-project.html +--- + +# Stop charges for a project or deployment + +% What needs to be done: Align serverless/stateful + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-billing-stop.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-billing-stop-project.md \ No newline at end of file diff --git a/deploy-manage/cloud-organization/billing/update-billing-operational-contacts.md b/deploy-manage/cloud-organization/billing/update-billing-operational-contacts.md new file mode 100644 index 000000000..1a49f9312 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/update-billing-operational-contacts.md @@ -0,0 +1,22 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-contacts.html +--- + +# Update billing and operational contacts [ec-billing-contacts] + +If different persons from your organization are involved in billing and operations, you can specify their relevant contact details in addition to the members set up on the account. + +These additional contacts only receive billing or operational emails. You can also set a specific email address to receive monitoring alerts. Members of the account still receive both types of emails. + +::::{note} +Operational contacts can only receive operational notifications, such as out-of-memory alerts. Operational and billing contacts can’t log in to Elasticsearch Service. To log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), you must use the [primary email address for your account](../../deploy/elastic-cloud/ec-customize-deployment-components.md#ec-user-settings) or be [a member](../../users-roles/cloud-organization.md) of the account. +:::: + + +To update billing and operational contacts, or set an email address for monitoring alerts: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Select the user icon on the header bar and choose **Organization** from the menu. +3. On the **Contacts** page, you can specify multiple email addresses for each category. They become effective immediately and no further confirmation of the email addresses is required. + diff --git a/deploy-manage/cloud-organization/billing/view-billing-history.md b/deploy-manage/cloud-organization/billing/view-billing-history.md new file mode 100644 index 000000000..d64ba9f62 --- /dev/null +++ b/deploy-manage/cloud-organization/billing/view-billing-history.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-history.html + - https://www.elastic.co/guide/en/serverless/current/general-billing-history.html +--- + +# View billing history + +% What needs to be done: Align serverless/stateful + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-billing-history.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-billing-history.md \ No newline at end of file diff --git a/deploy-manage/cloud-organization/operational-emails.md b/deploy-manage/cloud-organization/operational-emails.md new file mode 100644 index 000000000..e02508f38 --- /dev/null +++ b/deploy-manage/cloud-organization/operational-emails.md @@ -0,0 +1,20 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-operational-emails.html +--- + +# Operational emails [ec-operational-emails] + +To help keep you aware of potential performance issues in your clusters, we send email alerts based on certain types of activity. These alerts let you know about: + +* High disk usage +* A node out-of-memory restart + +For high disk usage, an email alert is activated when the space consumed on one of your nodes is greater than or equal to 90% of capacity, over two consecutive 15-minute intervals. If the problem persists, a new alert is sent every 24 hours. Once the disk usage is no longer above the threshold, we send another note to let you know that the problem is resolved. + +We also send an email alert if one of the nodes in your cluster is restarted due to an out-of-memory condition. + +These alerts are sent to all users within an Elastic Cloud organization, as well as to the email addresses listed as operational email contacts. This means that an external distribution list or automated service can receive notifications without the need to be added to the organization directly. + +To configure recipients external to an Elastic Cloud organization for these notifications Elasticsearch Service, update the list of [operational email contacts](https://cloud.elastic.co/account/contacts?page=docs&placement=docs-body). + diff --git a/deploy-manage/cloud-organization/service-status.md b/deploy-manage/cloud-organization/service-status.md new file mode 100644 index 000000000..ca9bd320f --- /dev/null +++ b/deploy-manage/cloud-organization/service-status.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-service-status.html + - https://www.elastic.co/guide/en/cloud/current/ec_subscribe_to_individual_regionscomponents.html + - https://www.elastic.co/guide/en/cloud/current/ec_service_status_api.html + - https://www.elastic.co/guide/en/serverless/current/general-serverless-status.html +--- + +# Service status + +% What needs to be done: Align serverless/stateful + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-service-status.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec_subscribe_to_individual_regionscomponents.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec_service_status_api.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-serverless-status.md \ No newline at end of file diff --git a/deploy-manage/cloud-organization/tools-and-apis.md b/deploy-manage/cloud-organization/tools-and-apis.md new file mode 100644 index 000000000..55c27d8fd --- /dev/null +++ b/deploy-manage/cloud-organization/tools-and-apis.md @@ -0,0 +1,46 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-work-with-apis.html +--- + +# Tools and APIs [ec-work-with-apis] + +Most Elastic resources can be accessed and managed through RESTful APIs. While the Elasticsearch Service API is used to manage your deployments and their components, the Elasticsearch and Kibana APIs provide direct access to your data and your visualizations, respectively. + +Elasticsearch Service API +: You can use the Elasticsearch Service API to manage your deployments and all of the resources associated with them. This includes performing deployment CRUD operations, scaling or autoscaling resources, and managing traffic filters, deployment extensions, remote clusters, and Elastic Stack versions. You can also access cost data by deployment and by organization. + + To learn more about the Elasticsearch Service API, read through the [API overview](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html), try out some [getting started examples](https://www.elastic.co/guide/en/cloud/current/ec-api-examples.html), and check our [API reference documentation](https://www.elastic.co/guide/en/cloud/current/ec-api-swagger.html). + + Calls to the Elasticsearch Service API are subject to [Rate limiting](https://www.elastic.co/guide/en/cloud/current/ec-api-rate-limiting.html). + + +Elasticsearch APIs +: This set of APIs allows you to interact directly with the Elasticsearch nodes in your deployment. You can ingest data, run search queries, check the health of your clusters, manage snapshots, and more. + + To use these APIs in Elasticsearch Service read our topic [Access the Elasticsearch API console](https://www.elastic.co/guide/en/cloud/current/ec-api-console.html), and to learn about all of the available endpoints check the [Elasticsearch API reference documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html). + + Some [restrictions](../deploy/elastic-cloud/restrictions-known-problems.md#ec-restrictions-apis-elasticsearch) apply when using the Elasticsearch APIs in Elasticsearch Service. + + +Kibana APIs +: Many Kibana features can be accessed through these APIs, including Kibana objects, patterns, and dashboards, as well as user roles and user sessions. You can use these APIs to configure alerts and actions, and to access health details for the Kibana Task Manager. + + The Kibana APIs cannot be accessed directly from the Elasticsearch Service console; you need to use `curl` or another HTTP tool to connect. Check the [Kibana API reference documentation](https://www.elastic.co/guide/en/kibana/current/api.html) to learn about using the APIs and for details about all available endpoints. + + Some [restrictions](../deploy/elastic-cloud/restrictions-known-problems.md#ec-restrictions-apis-kibana) apply when using these APIs with an Elasticsearch Service Kibana instance as compared to an on-prem installation. + + +Other Products +: Most other Elastic products have APIs to support machine-to-machine operations. You can find the documentation for these at the following links: + + * [APM event intake API Reference](https://www.elastic.co/guide/en/apm/guide/current/api-events.html) + * [App Search API Reference](https://www.elastic.co/guide/en/app-search/current/api-reference.html) + * [Elastic Security APIs](https://www.elastic.co/guide/en/security/current/security-apis.html) + * [Enterprise Search management APIs](https://www.elastic.co/guide/en/enterprise-search/current/management-apis.html) + * [Fleet APIs](https://www.elastic.co/guide/en/fleet/current/fleet-api-docs.html) + * [Logstash APIs](https://www.elastic.co/guide/en/logstash/current/monitoring-logstash.html) + * [Workplace Search API Reference](https://www.elastic.co/guide/en/workplace-search/current/workplace-search-api-overview.html) + + + diff --git a/deploy-manage/deploy.md b/deploy-manage/deploy.md new file mode 100644 index 000000000..c600a815b --- /dev/null +++ b/deploy-manage/deploy.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/serverless/current/intro.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro-deploy.html +--- + +# Deploy + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/334 + +% Scope notes: does plan for production content go here? With orchestrator layer - explain relationship between orchestrator and clusters how to help people to be aware of the other products that might need to be deployed? "these are the core products, you might add others on" describe relationship between orchestrators and ES Explain that when using orchestrators a lot of the reference configuration of the orchestrated applications is still applicable. The user needs to learn how to configure the applications when using an orchestrator, then afterwards, the documentation of the application will be valid and applicable to their use case. When a certain feature or configuration is not applicable in some deployment types, the document will specify it. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/docs-content/serverless/intro.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/elasticsearch-intro-deploy.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise.md b/deploy-manage/deploy/cloud-enterprise.md new file mode 100644 index 000000000..18419a885 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise.md @@ -0,0 +1,20 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/Elastic-Cloud-Enterprise-overview.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-ece.html +--- + +# Elastic Cloud Enterprise + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/339 + +% Scope notes: Ensure the landing page makes sense and its aligned with the section overview and the overview about orchestators. What content should be in deployment types overview or in the main overview and what in the ECE landing page... + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/Elastic-Cloud-Enterprise-overview.md +% Notes: 2 child docs +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-administering-ece.md +% Notes: redirect only \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md b/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md new file mode 100644 index 000000000..9f873a1d0 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-advanced-configuration.html +--- + +# Advanced cluster configuration [ece-advanced-configuration] + +Most configuration changes can be made safely from other parts of the Cloud UI. You should use the **Advanced cluster configuration** page to make changes only if the functionality is not available elsewhere and if you know what you are doing or are being directed by someone from Elastic. + +To edit the cluster configuration directly: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From your deployment menu, go to the **Edit** page then go to the bottom of the page and select **advanced Elasticsearch configuration**. +4. Edit the configuration: + + * The contents of the **Deployment configuration** section describe your current configuration, such as the current capacity, the node count, the installed Elasticsearch version, and so forth. You can manually edit the configuration. + * The **Elasticsearch cluster data** section describes additional parts of your cluster, such as its name, whether snapshots are enabled, security information, and whether Kibana is enabled. + +5. Select **Save** for the sections that you modified to apply the new configuration. You should receive a message that your new configuration is successful. + +::::{warning} +You can break things when editing the cluster deployment configuration. Use this functionality only if you know what you are doing or if you are being directed by someone from Elastic. +:::: diff --git a/deploy-manage/deploy/cloud-enterprise/air-gapped-install.md b/deploy-manage/deploy/cloud-enterprise/air-gapped-install.md new file mode 100644 index 000000000..3c6544dc0 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/air-gapped-install.md @@ -0,0 +1,19 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elastic-stack/current/air-gapped-install.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-offline.html +--- + +# Air gapped install + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/309 + +% Scope notes: In the issue + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/air-gapped-install.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-install-offline.md +% Notes: 3 child docs \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/alternative-install-ece-with-ansible.md b/deploy-manage/deploy/cloud-enterprise/alternative-install-ece-with-ansible.md new file mode 100644 index 000000000..f8e95b1a2 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/alternative-install-ece-with-ansible.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-ansible.html +--- + +# Alternative: Install ECE with Ansible [ece-configure-ansible] + +If you already use Ansible in your business for provisioning, configuration management, and application deployment, you can use the ECE Ansible playbook to get up and running with Elastic Cloud Enterprise faster, on any cloud provider. + +Please note that the ECE Ansible playbook is a community project, supported by Elastic, available on GitHub: [elastic/ansible-elastic-cloud-enterprise](https://github.com/elastic/ansible-elastic-cloud-enterprise). Elastic welcomes all community contributions to the repository and will validate any changes on a best-effort basis. + diff --git a/deploy-manage/deploy/cloud-enterprise/assign-roles-to-hosts.md b/deploy-manage/deploy/cloud-enterprise/assign-roles-to-hosts.md new file mode 100644 index 000000000..654c2f080 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/assign-roles-to-hosts.md @@ -0,0 +1,48 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-change-roles.html +--- + +# Assign roles to hosts [ece-change-roles] + +Assigning roles might be required after you [install Elastic Cloud Enterprise on hosts](install.md) to make sure the new hosts can be used for their intended purpose and to remove roles from the initial host to implement a recommended ECE installation. Similarly, if you need more processing capacity for Elasticsearch nodes in your deployment, change the role of a new runner to `allocator` to add its capacity to your installation. + +These steps describe how to assign roles from the Cloud UI. For automation purposes, assigning roles with a [token you generate](generate-roles-tokens.md) is preferred. + +Each Elastic Cloud Enterprise runner can take on several roles: + +`allocator` +: Allocates the available computing resources to Elasticsearch nodes or Kibana instances. In larger installations, a majority of the machines will be allocators. + +`coordinator` +: Serves as a distributed coordination system and resource scheduler. + +`proxy` +: Manages communication between a user and an Elasticsearch or Kibana instance. + +`director` +: Manages the ZooKeeper datastore. This role is typically shared with the coordinator role. In production deployments it can be separated from a coordinator. + +::::{important} +Once the `director` role is assigned to a runner, the Zookeeper service starts on that host. The Zookeeper service continues even after the director role is removed from the runner. Therefore, if you remove the `director` role from any host that has ever had it, we highly recommend also [deleting the runner](../../maintenance/ece/delete-ece-hosts.md) and re-installing it. +:::: + + +Each role is associated with a set of Docker containers that provide the specific functionality. + +There are some additional roles shown in the Cloud UI, such as the [beats-runner](https://www.elastic.co/guide/en/elastic-stack-glossary/current/terms.html#glossary-beats-runner) and [services-forwarder](https://www.elastic.co/guide/en/elastic-stack-glossary/current/terms.html#glossary-services-forwarder) roles, that are required by Elastic Cloud Enterprise and that you cannot modify. + +To assign roles to hosts: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Hosts**. + + The roles for each host are shown. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. To update the roles, select the host IP address and then choose **Manage roles** from the **Manage host** menu. +4. Select the role assignments for the host and choose **Update roles**. + +Elastic Cloud Enterprise automatically starts managing the node in its new role and makes it available for use. + diff --git a/deploy-manage/deploy/cloud-enterprise/ce-add-support-for-node-roles-autoscaling.md b/deploy-manage/deploy/cloud-enterprise/ce-add-support-for-node-roles-autoscaling.md new file mode 100644 index 000000000..01ca59130 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ce-add-support-for-node-roles-autoscaling.md @@ -0,0 +1,2059 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ce-add-support-for-node-roles-and-autoscaling.html +--- + +# Updating custom templates to support node_roles and autoscaling [ce-add-support-for-node-roles-and-autoscaling] + +Custom deployment templates should be updated in order to take advantage of new Elastic Cloud Enterprise features, such as [Data tiers](../../../manage-data/lifecycle/data-tiers.md) (that is, the new cold and frozen data tiers) and [Deployment autoscaling](../../autoscaling.md). By updating these templates we also ensure forward compatibility with future Elastic Cloud Enterprise versions that will require certain fields such as `node_roles` and `id` to be present in the deployment configuration. + +System owned deployment templates have already been updated to support both data tiers with `node_roles` and autoscaling. However, the custom templates that you created need to be manually updated by following the steps in this guide. + + +## Adding support for node_roles [ece_adding_support_for_node_roles] + +The `node_roles` field defines the roles that an Elasticsearch topology element can have, which is used in place of `node_type` when a new feature such as autoscaling is enabled, or when a new data tier is added. This field is supported on [Elastic stack versions 7.10 and above](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-node-types.html). + +There are a number of fields that need to be added to each Elasticsearch node in order to support `node_roles`: + +* **id**: Unique identifier of the topology element. This field, along with the `node_roles`, identifies an Elasticsearch topology element. +* **node_roles**: The list of node roles. Allowable roles are: `master`, `ingest`, `ml`, `data_hot`, `data_content`, `data_warm`, `data_cold`, `data_frozen`, `remote_cluster_client`, and `transform`. For details, check [Node roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles). +* **topology_element_control**: Controls for the topology element. + + * **min**: The absolute minimum size limit for a topology element. If the value is `0`, that means the topology element can be disabled. + + +The following example is based on the `default` system owned deployment template that already supports `node_roles`. This template will be used as a reference for the next sections: + +::::{dropdown} Reference example with support for `node_roles` +:name: ece-node-roles-support-example + +```json +{ + ... + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "data.default", + "zone_count": 1, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 4096, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "cold", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "frozen", + "instance_configuration_id": "data.frozen", + "zone_count": 1, + "node_roles": [ + "data_frozen" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + } + ], + "elasticsearch": {} + }, + ... + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ], + "apm": [ + { + "ref_id": "apm-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": {} + } + } + ], + "enterprise_search": [ + { + "ref_id": "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "appserver": true, + "connector": true, + "worker": true + }, + "instance_configuration_id": "enterprise.search", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 2 + } + ], + "enterprise_search": {} + } + } + ] + } + } +} +``` + +:::: + + +In the reference example there are seven different *Elasticsearch topology elements*: `hot_content`, `warm`, `cold`, `frozen`, `coordinating`, `master`, and `ml`. These names map to the `id` field of each topology element. In addition, this template contains four different *resources*: `elasticsearch`, `kibana`, `apm`, and `enterprise_search`. + + +### Requirements [ece_requirements] + +To add support for `node_roles`, the deployment template has to meet the following requirements: + +* Contains all four `resources`: `elasticsearch`, `kibana`, `apm`, and `enterprise_search`. +* The `elasticsearch` resource contains all seven topology elements: `hot_content`, `warm`, `cold`, `frozen`, `coordinating`, `master`, and `ml`. + + ::::{note} + :name: ece-ce-valid-topology-element-ids + + The IDs `hot_content`, `warm`, `cold`, `frozen`, `coordinating`, `master`, and `ml` are the **only** ones supported in an Elasticsearch topology element. In addition, there may not be topology elements with duplicate IDs inside the `elasticsearch` resource. + :::: + +* Each topology element contains the `id`, `node_roles`, and `topology_element_control` fields. + +It is also recommended that all Elasticsearch topology elements have the `node_attributes` field. This field can be useful in ILM policies, when creating a deployment using a version below 7.10, that does not support `node_roles`. + +Except for the `id` and `node_roles`, all fields can be configured by the user. Also, the topology elements must contain the exact same `id` and `node_roles` that are present in the reference example. + +::::{note} +Although it is required for the template to contain all resources and topology elements, it is possible to disable certain components by setting their `size.value` (and `topology_element_control.size` in the case of the Elasticsearch topology elements) to `0`. +:::: + + + +### Updating an ECE custom template to support `node_roles` [ece_updating_an_ece_custom_template_to_support_node_roles] + +To update a custom deployment template: + +1. Add the `id`, `node_roles`, `node_attributes`, and `topology_element_control` fields to the existing Elasticsearch topology elements. Keep in mind that these fields must match the Elasticsearch topology element in question: + + * If the `id` of the topology elements in the existing templates already match any of the seven mentioned in the requirements, then simply add the `node_roles` and `topology_element_control` to those elements, based on the reference example. + * Otherwise, map each of the existing topology elements to one of the seven Elasticsearch topology elements, based on their `node_type`, and add the fields accordingly. + +2. Add the `elasticsearch` topology elements that are missing. +3. Add the `resources` that are missing. + +::::{note} +It is recommended to add the `id` field to each Elasticsearch topology element in the deployment plan, before updating the template. This can be performed either through a deployment update API request or using the deployment **Advanced edit** page. Refer to the [note above](#ece-ce-valid-topology-element-ids) to understand which values are available for the `id` field. +:::: + + + +### Example [ece-ce-add-support-to-node-roles-example] + +The existing template contains three Elasticsearch topology elements and two resources (`elasticsearch` and `kibana`). + +::::{dropdown} Custom example without support for `node_roles` +```json +{ + ... + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "custom.data", + "zone_count": 2, + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "size": { + "value": 8192, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + } + }, + { + "zone_count": 1, + "instance_configuration_id": "custom.master", + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "zone_count": 1, + "instance_configuration_id": "custom.ml", + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + } + ], + "elasticsearch": {} + }, + ... + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ] + } + } +} +``` + +:::: + + +In this case we can match the three existing Elasticsearch topology elements to `hot_content`, `master`, and `ml`, respectively, based on their `node_type` field. Therefore, we can simply add the `id`, `node_roles`, `topology_element_control`, and `node_attributes` that are already associated with these topology elements in the reference example. + +Then, it is only necessary to add the four Elasticsearch topology elements (`warm`, `cold`, `frozen`, and `coordinating`) and two resources (`apm` and `enterprise_search`) that are missing. These fields can also be added based on the reference example. + +After adding support for `node_roles`, the resulting deployment template should look similar to the following: + +::::{dropdown} Custom example with support for `node_roles` +:name: example-with-support-for-node-roles + +```json +{ + ... + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "custom.data", + "zone_count": 2, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 8192, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "cold", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "frozen", + "instance_configuration_id": "data.frozen", + "zone_count": 1, + "node_roles": [ + "data_frozen" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "custom.master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "custom.ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + } + ], + "elasticsearch": {} + }, + ... + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ], + "apm": [ + { + "ref_id": "apm-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": {} + } + } + ], + "enterprise_search": [ + { + "ref_id": "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "appserver": true, + "connector": true, + "worker": true + }, + "instance_configuration_id": "enterprise.search", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 2 + } + ], + "enterprise_search": {} + } + } + ] + } + } +} +``` + +:::: + + + +## Adding support for autoscaling [ece_adding_support_for_autoscaling] + +After adding support for `node_roles` we can then update the template to support autoscaling. Autoscaling is used to automatically adjust the available resources in the deployments. Currently, this feature is available for Elasticsearch data tiers and machine learning node in [Elastic stack versions 7.11 and above](../../autoscaling.md). + +There are a number of autoscaling fields that need to be added in order to support autoscaling: + +* **autoscaling_min**: The default minimum size of an Elasticsearch topology element when autoscaling is enabled. This setting is currently available only for machine learning nodes, since these are the only nodes that support scaling down. +* **autoscaling_max**: The default maximum size of an Elasticsearch topology element when autoscaling is enabled. This setting is currently available only for data tiers and machine learning nodes, since these are the only nodes that support scaling up. +* **autoscaling_enabled**: When set to `true`, autoscaling is enabled by default on an Elasticsearch cluster. + +::::{note} +These fields represent the default settings for the deployment. However, autoscaling can be enabled/disabled and the maximum and minimum autoscaling sizes can be adjusted in the deployment settings. +:::: + + +Similar to the `node_roles` example, the following one is also based on the `default` deployment template that already supports `node_roles` and autoscaling. This template will be used as a reference for the next sections: + +::::{dropdown} Reference example with support for `node_roles` and autoscaling +```json +{ + ... + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "data.default", + "zone_count": 1, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 4096, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "cold", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "frozen", + "instance_configuration_id": "data.frozen", + "zone_count": 1, + "node_roles": [ + "data_frozen" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_min": { + "resource": "memory", + "value": 0 + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + } + ], + "elasticsearch": {}, + "autoscaling_enabled": true + }, + ... + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ], + "apm": [ + { + "ref_id": "apm-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": {} + } + } + ], + "enterprise_search": [ + { + "ref_id": "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "appserver": true, + "connector": true, + "worker": true + }, + "instance_configuration_id": "enterprise.search", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 2 + } + ], + "enterprise_search": {} + } + } + ] + } + } +} +``` + +:::: + + + +### Requirements [ece_requirements_2] + +To add support for autoscaling, the deployment template has to meet the following requirements: + +1. Already has support for `node_roles`. +2. Contains the `size`, `autoscaling_min`, and `autoscaling_max` fields, according to the rules specified in the [autoscaling requirements table](../../autoscaling/ece-autoscaling-api-example.md#ece-autoscaling-api-example-requirements-table). +3. Contains the `autoscaling_enabled` fields on the `elasticsearch` resource. + +If necessary, the values chosen for each field can be based on the reference example. + + +### Updating an ECE custom template to support autoscaling [ece_updating_an_ece_custom_template_to_support_autoscaling] + +To update a custom deployment template: + +1. Add the `autoscaling_min` and `autoscaling_max` fields to the Elasticsearch topology elements (check [Autoscaling through the API](../../autoscaling/ece-autoscaling-api-example.md)). +2. Add the `autoscaling_enabled` fields to the `elasticsearch` resource. Set this field to `true` in case you want autoscaling enabled by default, and to `false` otherwise. + + +### Example [ece_example] + +After adding support for autoscaling to the [example](#ece-node-roles-support-example) presented in the previous section, the resulting deployment template should look similar to the following: + +::::{dropdown} Custom example with support for `node_roles` and autoscaling +```json +{ + ... + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "custom.data", + "zone_count": 2, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 8192, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "cold", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "frozen", + "instance_configuration_id": "data.frozen", + "zone_count": 1, + "node_roles": [ + "data_frozen" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "custom.master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "custom.ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_min": { + "resource": "memory", + "value": 0 + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + } + ], + "elasticsearch": {}, + "autoscaling_enabled": true + }, + ... + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ], + "apm": [ + { + "ref_id": "apm-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": {} + } + } + ], + "enterprise_search": [ + { + "ref_id": "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "appserver": true, + "connector": true, + "worker": true + }, + "instance_configuration_id": "enterprise.search", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 2 + } + ], + "enterprise_search": {} + } + } + ] + } + } +} +``` + +:::: + + + +## Updating a custom template through the RESTful API [ece_updating_a_custom_template_through_the_restful_api] + +Having added support for `node_roles` and autoscaling to your custom template, it is possible to perform the update through the RESTful API, by following these steps: + +1. Obtain the existing deployment templates by sending the following `GET` request, and take note of the `id` of the template you wish to update. + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/templates?region=ece-region + ``` + +2. Send a `PUT` request with the updated template on the payload, in order to effectively replace the outdated template with the new one. Note that the following request is just an example, you have to replace `{{template_id}}` with the `id` you collected on step 1. and set the payload to the updated template JSON. Check [set deployment template API](https://www.elastic.co/guide/en/cloud-enterprise/current/set-deployment-template-v2.html) for more details. + + ::::{dropdown} Update template API request example + ```sh + curl -k -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://$COORDINATOR_HOST:12443/api/v1/deployments/templates/{template_id}?region=ece-region -H 'content-type: application/json' -d ' + { + "name": "ECE Custom Template", + "description": "ECE custom template with support for node_roles and autoscaling", + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "custom.data", + "zone_count": 2, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 8192, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "cold", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "frozen", + "instance_configuration_id": "data.frozen", + "zone_count": 1, + "node_roles": [ + "data_frozen" + ], + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "size": { + "resource": "memory", + "value": 0 + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "custom.master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "custom.ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_min": { + "resource": "memory", + "value": 0 + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + } + ], + "elasticsearch": {}, + "autoscaling_enabled": true + }, + "settings": { + "dedicated_masters_threshold": 6 + } + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ], + "apm": [ + { + "ref_id": "apm-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": {} + } + } + ], + "enterprise_search": [ + { + "ref_id": "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "appserver": true, + "worker": true, + "connector": true + }, + "instance_configuration_id": "enterprise.search", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 2 + } + ], + "enterprise_search": {} + } + } + ] + } + }, + "system_owned": false + }' + ``` + + :::: + + +After the template is updated, you can start [creating new deployments](create-deployment.md) or [migrating existing ones to `node_roles`](#ece-migrating-a-deployment-to-node-roles). + +Although `node_roles` and autoscaling are only available in more recent Elastic stack versions, an updated template can still be used with deployments that have versions below 7.10. In these cases, the data tiers and autoscaling features will only take effect once the deployment is upgraded to versions 7.10 and 7.11, respectively. + + +## Migrating a deployment to `node_roles` [ece-migrating-a-deployment-to-node-roles] + +Once a custom template is updated with `node_roles`, the existing deployments associated with this template can be migrated to `node_roles`. This migration can be done automatically by performing one of the following actions through the UI: + +* Enable a warm, cold, or frozen tier. +* Upgrade the deployment. +* Enable autoscaling (only possible if the custom template has support for autoscaling). + +If you do not intend to perform any of these actions, the migration can only be done by manually updating the necessary fields in the deployment plan. This can be performed either through the API or using the deployment **Advanced edit** page. + +**Using the API:** + +1. Go to the deployment **Edit** page. +2. Get the deployment update payload by clicking **Equivalent API request** at the bottom of the page. +3. Update the payload by replacing `node_type` with `node_roles` in each Elasticsearch topology element. To know which `node_roles` to add to each topology element, refer to the [custom template example](#ece-ce-add-support-to-node-roles-example) where support for `node_roles` is added. +4. Send a `PUT` request with the updated deployment payload to conclude the migration. Check the [Update Deployment](https://www.elastic.co/guide/en/cloud-enterprise/current/update-deployment.html) API documentation for more details. + +**Using the Advanced edit:** + +::::{note} +To follow this approach you need to have administrator privileges. +:::: + + +1. Go to the deployment **Edit** page. +2. Click **Advanced edit** at the bottom of the page. +3. Update the **Deployment configuration** by replacing `node_type` with `node_roles` in each Elasticsearch topology element. To know which `node_roles` to add to each topology element, refer to the [custom template example](#ece-ce-add-support-to-node-roles-example) where support for `node_roles` is added. +4. Click **Save** to conclude the migration. + +::::{warning} +Once a deployment is migrated to node roles, it is not possible to roll back. +:::: + + +After the migration plan has finished, we recommend following the [Migrate index allocation filters to node roles](../../../manage-data/lifecycle/index-lifecycle-management/migrate-index-allocation-filters-to-node-roles.md) guide. Step 1 of this guide was already accomplished by adding support for `node_roles`. However, performing steps 2, 3, and 4, which involves updating index settings, index templates, and ILM policies, can prevent shard allocation issues caused by conflicting ILM policies. + + +### Example [ece_example_2] + +The following is an example of a deployment plan that does not contain `node_roles`: + +::::{dropdown} Example deployment plan with `node_type` +```json +{ + "name": "Example deployment", + "prune_orphans": true, + "metadata": { + "system_owned": false, + "hidden": false + }, + "resources": { + "elasticsearch": [ + { + "ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "tiebreaker_topology": { + "memory_per_node": 1024 + }, + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "custom.data", + "zone_count": 2, + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 8192, + "resource": "memory" + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "custom.master", + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "custom.ml", + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "size": { + "value": 0, + "resource": "memory" + } + } + ], + "elasticsearch": { + "version": "7.17.0" + }, + "deployment_template": { + "id": "custom-template" + } + } + } + ], + "kibana": [ + { + "region": "ece-region", + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + }, + "zone_count": 1, + "kibana": {} + } + ], + "kibana": { + "version": "7.17.0" + } + } + } + ], + "apm": [], + "enterprise_search": [] + } +} +``` + +:::: + + +After adding support for `node_roles` to the example deployment plan, the resulting plan should look similar to the following: + +::::{dropdown} Example deployment plan with `node_roles` +```json +{ + "name": "Example deployment", + "prune_orphans": true, + "metadata": { + "system_owned": false, + "hidden": false + }, + "resources": { + "elasticsearch": [ + { + "ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "tiebreaker_topology": { + "memory_per_node": 1024 + }, + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "custom.data", + "zone_count": 2, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "size": { + "value": 8192, + "resource": "memory" + } + }, + { + "id": "warm", + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "id": "coordinating", + "zone_count": 1, + "instance_configuration_id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "master", + "zone_count": 1, + "instance_configuration_id": "custom.master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "ml", + "zone_count": 1, + "instance_configuration_id": "custom.ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "size": { + "value": 0, + "resource": "memory" + } + } + ], + "elasticsearch": { + "version": "7.17.0" + }, + "deployment_template": { + "id": "custom-template" + } + } + } + ], + "kibana": [ + { + "region": "ece-region", + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + }, + "zone_count": 1, + "kibana": {} + } + ], + "kibana": { + "version": "7.17.0" + } + } + } + ], + "apm": [], + "enterprise_search": [] + } +} +``` + +:::: diff --git a/deploy-manage/deploy/cloud-enterprise/change-allocator-disconnect-timeout.md b/deploy-manage/deploy/cloud-enterprise/change-allocator-disconnect-timeout.md new file mode 100644 index 000000000..92b66c191 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/change-allocator-disconnect-timeout.md @@ -0,0 +1,63 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-change-allocator-disconnect-timeout.html +--- + +# Change allocator disconnect timeout [ece-change-allocator-disconnect-timeout] + +One of the responsibilities of the allocator is to monitor the health of the clusters running on it. It periodically healthcheck the instances and report their health to other components. The platform uses this information to route traffic to healthy instances and to avoid unhealthy ones. The healthstatus is stored in zookeeper. + +By default, the platform will wait 10 minutes before considering a particular instance unhealthy. + +While the 10 minutes timeout is long, this is based on the assumption that a short-lived zookeeper disconnect it more likely than a disconnected allocator, and that the allocator will reconnect shortly. In the meantime the workloads running on the allocator are healthy and can be accessed. This assumption may not hold for your use case, e.g., your allocators are frequently restarted. + +The timeout can be changed by running the following script. Use the `TIMEOUT_MINUTES` to set a different timeout. At least 2 minutes is recommended, to avoid false positives in case of allocator container restarts. + +::::{note} +The new timeout will apply only to new instances that are added to the allocator. The existing instances will continue running on the old timeout until they are disconnected for longer that the old timeout, or migrated. +:::: + + +To change the timeout value: + +1. On a host that holds the director role: + + ```sh + docker run \ + -v ~/.found-shell:/elastic_cloud_apps/shell/.found-shell \ + --env SHELL_ZK_AUTH=$(docker exec -it frc-directors-director bash -c 'echo -n $FOUND_ZK_READWRITE') $(docker inspect -f '{{ range .HostConfig.ExtraHosts }} --add-host {{.}} {{ end }}' frc-directors-director) \ + --env FOUND_SCRIPT=setAllocatorTTL.sc \ + --env TIMEOUT_MINUTES=2 \ + --rm -it \ + $(docker inspect -f '{{ .Config.Image }}' frc-directors-director) \ + /elastic_cloud_apps/shell/run-shell.sh + ``` + +2. On all the allocator hosts: + + ```sh + docker rm -f frc-allocators-allocator + ``` + + +To reset back to the default. + +1. On a host that holds the director role: + + ```sh + docker run \ + -v ~/.found-shell:/elastic_cloud_apps/shell/.found-shell \ + --env SHELL_ZK_AUTH=$(docker exec -it frc-directors-director bash -c 'echo -n $FOUND_ZK_READWRITE') $(docker inspect -f '{{ range .HostConfig.ExtraHosts }} --add-host {{.}} {{ end }}' frc-directors-director) \ + --env FOUND_SCRIPT=resetAllocatorTTL.sc \ + --rm -it \ + $(docker inspect -f '{{ .Config.Image }}' frc-directors-director) \ + /elastic_cloud_apps/shell/run-shell.sh + ``` + +2. On all the allocator hosts: + + ```sh + docker rm -f frc-allocators-allocator + ``` + + diff --git a/deploy-manage/deploy/cloud-enterprise/change-ece-api-url.md b/deploy-manage/deploy/cloud-enterprise/change-ece-api-url.md new file mode 100644 index 000000000..0d019e987 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/change-ece-api-url.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-config-api-base-url.html +--- + +# Change the ECE API URL [ece-config-api-base-url] + +You can configure the HTTPS URL used to access the ECE API. You can specify either a DNS host name or an IP address. The primary use for this is to enable [single sign-on](../../users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md) on your deployments, so you can log into Kibana and Enterprise Search automatically once logged in to ECE. + +To change the ECE API URL in the Cloud UI: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Select **Edit** and update the API URL setting. +4. Select **Update** and then **Save** to confirm the change. + +To set the API base URL during installation or upgrade you can supply the `--api-base-url` command line argument: + +```sh +bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --api-base-url $ECE_HTTPS_URL + +bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) upgrade --user admin --pass $PASSWORD --api-base-url $ECE_HTTPS_URL +``` + +For existing deployments, the new ECE API URL will take effect whenever the deployment configuration plan is next updated. + diff --git a/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls.md b/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls.md new file mode 100644 index 000000000..8054b7e38 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls.md @@ -0,0 +1,54 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html +--- + +# Change endpoint URLs [ece-administering-endpoints] + +For applications without SSL or HTTPS protocol support, you can use a local endpoint with the HTTP protocol, which in turn connects to your Elasticsearch cluster or to Kibana either using the HTTP or the HTTPS protocol. + +By default, cluster and Kibana endpoint URLs are constructed according to the following pattern, where `CLUSTER_ID` and `LOCAL_HOST_IP` are values that depend on your specific installation: + +::::{admonition} +```text +http://CLUSTER_ID.LOCAL_HOST_IP.ip.es.io:9200 +https://CLUSTER_ID.LOCAL_HOST_IP.ip.es.io:9243 +``` + +:::: + + +For example: + +```sh +http://2882c82e54d4361.us-west-5.aws.found.io:9200 +https://2882c82e54d4361.us-west-5.aws.found.io:9243 +``` + +::::{tip} +To find your endpoints, select a deployment review the information on the **Elasticsearch** and **Kibana** pages. +:::: + + +To change endpoints in the Cloud UI: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Specify the deployment domain name value for your cluster and Kibana endpoints. +4. Select **Update Deployment endpoints**. The new endpoint becomes effective immediately. + +::::{tip} +If you install Elastic Cloud Enterprise on AWS, you likely need to modify the cluster endpoint. To learn more, check [Endpoint URLs Inaccessible on AWS](../../../troubleshoot/deployments/cloud-enterprise/common-issues.md#ece-aws-private-ip). +:::: + + +::::{tip} +If you have an App Search instance, after specifying a new deployment domain name value you need to reapply the App Search [cluster configuration](advanced-cluster-configuration.md), either with or without any changes. +:::: + + +::::{note} +The built-in Proxy Certificate only validates against the default endpoint format described on this page. Once you change it, it is necessary to upload a new Proxy Certificate as described in [Manage security certificates](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-certificates.html). For test only, clients can be configured with hostname verification disabled until the new certificate is uploaded. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-allocator-affinity.md b/deploy-manage/deploy/cloud-enterprise/configure-allocator-affinity.md new file mode 100644 index 000000000..076970f65 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-allocator-affinity.md @@ -0,0 +1,81 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-allocator-affinity.html +--- + +# Configure allocator affinity [ece-configuring-allocator-affinity] + +One of the benefits of the ECE platform is its robust deployment instance distribution logic that maximizes the utilization of the underlying resources you deploy the Elastic Stack on. In ECE 2.4 and later, you can customize how Elastic Stack deployments get distributed across the available set of allocators in your ECE installation, which is known as *allocator affinity*. + + +## Before you begin [ece_before_you_begin_6] + +Configuring allocator affinity is an optional post-installation task that changes the behavior of Elastic Cloud Enterprise. If you do not explicitly set an affinity strategy, all instances use the [`fill-anti-affinity`](#fill-anti-affinity) strategy by default. + +To follow these steps, you must be familiar with using the ECE RESTful API. The API examples in this topic use HTTPS, which requires that you have a [TLS certificate already installed](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md). For testing purposes only, you can specify the `-k` option to turn off certificate verification, as shown in our examples, or use HTTP over port 12400 until you get your TLS certificate sorted out. + + +## Affinity strategies [ece_affinity_strategies] + +The following distribution strategies to configure allocator affinity are available: + +$$$fill-anti-affinity$$$`fill-anti-affinity` (default) +: Prefers to create instances of the same deployment on separate allocators, if available. This strategy tries to fill an already used allocator in a given zone before moving on to the next one, but it will prioritize separating instances of the same deployment onto different allocators. The strategy strikes a good balance between utilization and fault tolerance, as it minimizes the impact on any given deployment in case of a host failure. This strategy is the default for ECE 2.3 and later. + +`fill` +: Similar to the previous strategy, optimizes for maximum utilization of already used allocators before expanding to new, unused ones. Because this strategy makes sure that existing resources are fully utilized before requiring new ones to be provisioned, it is especially useful when running ECE on cloud environments where you typically pay only for provisioned capacity. With this strategy, new Elasticsearch nodes and Kibana instances for a deployment are created on the least empty allocator in a given zone, even if multiple instances end up on the same allocator, making sure to fill it first before moving on to the next allocator in that zone. The trade-off is that you potentially give up host-level high availability (HA) if an allocator gets filled with multiple instances from the same deployment. This strategy was the default for ECE 2.2 and earlier. + +`distribute` +: This strategy optimizes for distributing the deployment instances as evenly as possible across all available resources in a given availability zone, creating new deployment instances on the least used allocators. This stategy is useful in scenarios where the hardware resources are already provisioned, typically in on-premise datacenters, and you want to use as much of them as possible. Available in ECE 2.4 and later. + +`distribute-anti-affinity` +: Similar to the previous strategy, with one change: this strategy prefers to create instances of the same deployment on separate allocators in a specific zone, if available, in order to minimize the impact of an allocator failure on any given deployment. Available in ECE 2.4 and later. + + +## Steps [ece_steps_3] + +To check how allocator affinity is currently configured: + +```sh +curl -X GET -u admin:PASSWORD -k https://COORDINATOR_HOST:12443/api/v1/platform/configuration/store/constructor +{ + "errors": [{ + "code": "platform.config.store.not_found", + "message": "Config option [constructor] could not be found" + }] +} +``` + +If a configuration option cannot be found, the default `fill-anti-affinity` strategy is being used. + +To set allocator affinity to the `distribute-anti-affinity` strategy: + +```sh +curl -X POST -u admin:PASSWORD -k https://COORDINATOR_HOST:12443/api/v1/platform/configuration/store/constructor -H 'Content-Type: application/json' -d '{ "value": "{ \"allocator_prioritization\": \"distribute-anti-affinity\" }" }' +{ + "changed": false, + "name": "constructor", + "value": "{ \"allocator_prioritization\": \"distribute-anti-affinity\" }" +} +``` + +To update allocator affinity to the `distribute` strategy: + +```sh +curl -X PUT -u admin:PASSWORD -k https://COORDINATOR_HOST:12443/api/v1/platform/configuration/store/constructor -H 'Content-Type: application/json' -d '{ "value": "{ \"allocator_prioritization\": \"distribute\" }" }' +{ + "changed": true, + "name": "constructor", + "value": "{ \"allocator_prioritization\": \"distribute\" }" +} +``` + +To change allocator affinity back to the default behavior: + +```sh +curl -X DELETE -u admin:PASSWORD -k https://COORDINATOR_HOST:12443/api/v1/platform/configuration/store/constructor +{ + +} +``` + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md b/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md new file mode 100644 index 000000000..f93aee41a --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md @@ -0,0 +1,45 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-templates.html +--- + +# Configure deployment templates [ece-configuring-ece-templates] + +Deployment templates combine components of the Elastic Stack, such as Elasticsearch nodes and Kibana instances, for different use cases. Compared to a one-size-fits-all approach to deploying the Elastic Stack, templates provide much greater flexibility and ensure that your deployments have the resources they need to support your use cases. To make the most of deployment templates, you must configure ECE for them. + +After installing or upgrading to ECE version 2.0 or later: + +1. [Tag your allocators](ece-configuring-ece-tag-allocators.md) to tell ECE what kind of hardware you have available for Elastic Stack deployments. +2. [Edit the default instance configurations](ece-configuring-ece-instance-configurations-edit.md) to match components of the Elastic Stack to your tagged allocators. + +If you do not perform these steps, Elastic Cloud Enterprise will behave just as it did in versions before 2.0 and deploy the Elastic Stack wherever there is space on allocators. + +Have a use case that isn’t addressed by the ECE default templates? You can also: + +* [Create your own instance configurations](ece-configuring-ece-instance-configurations-create.md) to match components of the Elastic Stack to allocators, tailoring what resources they get and what sizes they support. +* [Create your own deployment templates](ece-configuring-ece-create-templates.md) to solve your own use cases better. + + +## Basic concepts [ece_basic_concepts] + +With ECE version 2.0, a number of new concepts got introduced. Here’s how allocator tags, instance configurations, and deployment templates relate to each other: + +Allocator tag +: Indicates what kind of hardware resources you have available. Used by instance configurations to find suitable allocators. + +Instance configuration +: Matches components of the Elastic Stack to allocators for deployment and tailors how memory and storage resources get sized relative to each other, and what sizes are available. Used as a building block for deployment templates. + +Deployment template +: Solves a specific use case with the Elastic Stack, such as a search or a logging use case. ECE provides some deployment templates out of the box to get you started, or you can create your own. + + + + + + + + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-host-rhel-cloud.md b/deploy-manage/deploy/cloud-enterprise/configure-host-rhel-cloud.md new file mode 100644 index 000000000..e21ca0703 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-host-rhel-cloud.md @@ -0,0 +1,345 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-hosts-rhel-centos-cloud.html +--- + +# Configure host RHEL cloud [ece-configure-hosts-rhel-centos-cloud] + + +## Red Hat Enterprise Linux 8 (RHEL 8), 9 (RHEL 9), and Rocky Linux 8 and 9 [ece-setup-rhel8-podman-cloud] + +The following instructions show you how to prepare your hosts on Red Hat Enterprise Linux 8 (RHEL 8), 9 (RHEL 9), and Rocky Linux 8 and 9. + +* [Prerequisites](#ece-prerequisites-rhel8-cloud) +* [Configure the host](#ece-configure-hosts-rhel8-podman-cloud) + + +### Prerequisites [ece-prerequisites-rhel8-cloud] + +Create a RHEL 8 (the version must be >= 8.5, but <9), RHEL 9, Rocky Linux 8, or Rocky Linux 9 VM. + +* For RHEL 8, follow your internal guidelines to add a vanilla RHEL 8 VM to your environment. Note that the version must be >= 8.5, but <9. + +Verify that required traffic is allowed. Check the [Networking prerequisites](ece-networking-prereq.md) and [Google Cloud Platform (GCP)](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-gcp.html) guidelines for a list of ports that need to be open. The technical configuration highly depends on the underlying infrastructure. + +**Example:** For AWS, allowing traffic between hosts is implemented using security groups. + + +### Configure the host [ece-configure-hosts-rhel8-podman-cloud] + +1. Install the OS packages `lvm2`, `iptables`, `sysstat`, and `net-tools` by executing: + + ```sh + sudo dnf install lvm2 iptables sysstat net-tools <1> + ``` + + 1. The ECE diagnostic script requires `net-tools`.
+ + + ::::{note} + For RHEL 9 and Rocky Linux 9, also install the `containernetworking-plugins` package using:
+ + ```sh + sudo dnf -y install containernetworking-plugins + ``` + + :::: + +2. Remove Docker and previously installed podman packages (if previously installed). + + ```sh + sudo dnf remove docker docker-ce podman podman-remote containerd.io + ``` + +3. As a sudoers user, edit the `/etc/selinux/config` file: + + 1. If you are not using SELinux, set it to permissive mode: + + ```text + SELINUX=permissive + ``` + + 2. If you are using SELinux, set it to enforcing mode: + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```text + SELINUX=enforcing + ``` + +4. Install podman: + + * For RHEL 8 and Rocky Linux, install version `4.*`. + + ```sh + sudo dnf install podman-4.* podman-remote-4.* + ``` + + * For RHEL 9, install the latest available version `4.*` using dnf. + + ```sh + sudo dnf install podman-4.* podman-remote-4.* + ``` + +5. [This step is for RHEL 9 and Rocky Linux 9 only] Switch the network stack from Netavark to CNI: + + 1. If the */etc/containers/containers.conf* file does not exist, copy the */usr/share/containers/containers.conf* file to the */etc/containers/* directory (for example, using `cp /usr/share/containers/containers.conf /etc/containers/`). + 2. Open the */etc/containers/containers.conf* file. Navigate to the **network** section and make sure that the **network_backend** setting is set to `cni`. + 3. Reboot the system (`reboot`). + 4. Check that the network stack has changed to `cni`:
+ + ```sh + cat /etc/containers/containers.conf + [...] + [network] + network_backend="cni" + [...] + ``` + +6. If podman requires a proxy in your infrastructure setup, modify the `/usr/share/containers/containers.conf` file and add the `HTTP_PROXY` and `HTTPS_PROXY` environment variables in the [engine] section. Please note that multiple env variables in that configuration file exists — use the one in the [engine] section. + + Example: + + ```text + [engine] + env = ["HTTP_PROXY=http://{proxy-ip}:{proxy-port}", "HTTPS_PROXY=http://{proxy-ip}:{proxy-port}"] + ``` + +7. Reload systemd configuration + + ```sh + sudo systemctl daemon-reload + ``` + +8. Create OS groups, if they do not exist yet + + Reference: [Users and permissions](ece-users-permissions.md) + + ```sh + sudo groupadd elastic + sudo groupadd podman + ``` + +9. Add user `elastic` to the `podman` group + + Reference: [Users and permissions](ece-users-permissions.md) + + ```sh + sudo useradd -g "elastic" -G "podman" elastic + ``` + +10. As a sudoers user, add the following line to /etc/sudoers.d/99-ece-users + + Reference: [Users and permissions](ece-users-permissions.md) + + ```text + elastic ALL=(ALL) NOPASSWD:ALL + ``` + +11. Add the required options to the kernel boot arguments + + ```sh + sudo /sbin/grubby --update-kernel=ALL --args='cgroup_enable=memory cgroup.memory=nokmem swapaccount=1' + ``` + +12. Create the directory + + ```sh + sudo mkdir -p /etc/systemd/system/podman.socket.d + ``` + +13. As a sudoers user, create the file `/etc/systemd/system/podman.socket.d/podman.conf` with the following content. Set the correct ownership and permission. + + ::::{important} + Both `ListenStream=` and `ListenStream=/var/run/docker.sock` parameters are required! + :::: + + + File content: + + ```text + [Socket] + ListenStream= + ListenStream=/var/run/docker.sock + SocketMode=770 + SocketUser=elastic + SocketGroup=podman + ``` + + File ownership and permission: + + ```sh + sudo chown root:root /etc/systemd/system/podman.socket.d/podman.conf + sudo chmod 0644 /etc/systemd/system/podman.socket.d/podman.conf + ``` + +14. As a sudoers user, create the (text) file `/usr/bin/docker` with the following content. Verify that the regular double quotes in the text file are used (ASCII code Hex 22) + + ```text + #!/bin/bash + podman-remote --url unix:///var/run/docker.sock "$@" + ``` + +15. Set the file permissions on `/usr/bin/docker` + + ```sh + sudo chmod 0755 /usr/bin/docker + ``` + +16. As a sudoers user, add the following two lines to section `[storage]` in the file `/etc/containers/storage.conf`. Verify that those parameters are only defined once. Either remove or comment out potentially existing parameters. + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```text + runroot = "/mnt/data/docker/runroot/" + graphroot = "/mnt/data/docker" + ``` + +17. Enable podman so that itself and running containers start automatically after a reboot + + ```sh + sudo systemctl enable podman.service + sudo systemctl enable podman-restart.service + ``` + +18. Enable the `overlay` kernel module (check [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)) that the Podman `overlay` storage driver uses (check [Working with the Container Storage library and tools in Red Hat Enterprise Linux](https://www.redhat.com/en/blog/working-container-storage-library-and-tools-red-hat-enterprise-linux#:~:text=Storage%20Configuration)). + + In the Docker world there are two overlay drivers, overlay and overlay2. Today most users use the overlay2 driver, so we just use that one, and called it overlay. Refer also to [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/). + + ```sh + echo "overlay" | sudo tee -a /etc/modules-load.d/overlay.conf + ``` + +19. Format the additional data partition + + ```sh + sudo mkfs.xfs /dev/nvme1n1 + ``` + +20. Create the `/mnt/data/` directory used as a mount point + + ```sh + sudo install -o elastic -g elastic -d -m 700 /mnt/data + ``` + +21. As a sudoers user, modify the entry for the XFS volume in the `/etc/fstab` file to add `pquota,prjquota`. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ::::{note} + Replace `/dev/nvme1n1` in the following example with the corresponding device on your host, and add this example configuration as a single line to `/etc/fstab`. + :::: + + + ```text + /dev/nvme1n1 /mnt/data xfs defaults,nofail,x-systemd.automount,prjquota,pquota 0 2 + ``` + +22. Restart the local-fs target + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart local-fs.target + ``` + +23. Set the permissions on the newly mounted device + + ```sh + ls /mnt/data + sudo chown elastic:elastic /mnt/data + ``` + +24. Create the `/mnt/data/docker` directory for the Docker service storage + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```sh + sudo install -o elastic -g elastic -d -m 700 /mnt/data/docker + ``` + +25. If you want to use FirewallD, please ensure you meet the [networking prerequisites](ece-networking-prereq.md). Otherwise, you can disable it with: + + ```sh + sudo systemctl disable firewalld + ``` + + ::::{note} + If FirewallD does not exist on your VM, you can skip this step. + :::: + +26. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +30. Restart the podman service by running this command: + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart podman + ``` + +31. Reboot the RHEL host + + ```sh + sudo reboot + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/configure-host-rhel-onprem.md b/deploy-manage/deploy/cloud-enterprise/configure-host-rhel-onprem.md new file mode 100644 index 000000000..9272d2dc5 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-host-rhel-onprem.md @@ -0,0 +1,343 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-hosts-rhel-centos-onprem.html +--- + +# Configure host RHEL onprem [ece-configure-hosts-rhel-centos-onprem] + + +## Red Hat Enterprise Linux 8 (RHEL 8), 9 (RHEL 9), and Rocky Linux 8 and 9 [ece-setup-rhel8-podman-onprem] + +The following instructions show you how to prepare your hosts on Red Hat Enterprise Linux 8 (RHEL 8), 9 (RHEL 9), and Rocky Linux 8 and 9. + +* [Prerequisites](#ece-prerequisites-rhel8-onprem) +* [Configure the host](#ece-configure-hosts-rhel8-podman-onprem) + + +### Prerequisites [ece-prerequisites-rhel8-onprem] + +Create a RHEL 8 (the version must be >= 8.5, but <9), RHEL 9, Rocky Linux 8, or Rocky Linux 9 instance. + +* For RHEL 8, follow your internal guidelines to add a vanilla RHEL 8 instance to your environment. Note that the version must be >= 8.5, but <9. + +Verify that required traffic is allowed. + + +### Configure the host [ece-configure-hosts-rhel8-podman-onprem] + +1. Install the OS packages `lvm2`, `iptables`, `sysstat`, and `net-tools` by executing: + + ```sh + sudo dnf install lvm2 iptables sysstat net-tools <1> + ``` + + 1. The ECE diagnostic script requires `net-tools`.
+ + + ::::{note} + For RHEL 9 and Rocky Linux 9, also install the `containernetworking-plugins` package using:
+ + ```sh + sudo dnf -y install containernetworking-plugins + ``` + + :::: + +2. Remove Docker and previously installed podman packages (if previously installed). + + ```sh + sudo dnf remove docker docker-ce podman podman-remote containerd.io + ``` + +3. As a sudoers user, edit the `/etc/selinux/config` file: + + 1. If you are not using SELinux, set it to permissive mode: + + ```text + SELINUX=permissive + ``` + + 2. If you are using SELinux, set it to enforcing mode: + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```text + SELINUX=enforcing + ``` + +4. Install podman: + + * For RHEL 8 and Rocky Linux, install version `4.*`. + + ```sh + sudo dnf install podman-4.* podman-remote-4.* + ``` + + * For RHEL 9, install the latest available version `4.*` using dnf. + + ```sh + sudo dnf install podman-4.* podman-remote-4.* + ``` + +5. [This step is for RHEL 9 and Rocky Linux 9 only] Switch the network stack from Netavark to CNI: + + 1. If the */etc/containers/containers.conf* file does not exist, copy the */usr/share/containers/containers.conf* file to the */etc/containers/* directory (for example, using `cp /usr/share/containers/containers.conf /etc/containers/`). + 2. Open the */etc/containers/containers.conf* file. Navigate to the **network** section and make sure that the **network_backend** setting is set to `cni`. + 3. Reboot the system (`reboot`). + 4. Check that the network stack has changed to `cni`:
+ + ```sh + cat /etc/containers/containers.conf + [...] + [network] + network_backend="cni" + [...] + ``` + +6. If podman requires a proxy in your infrastructure setup, modify the `/usr/share/containers/containers.conf` file and add the `HTTP_PROXY` and `HTTPS_PROXY` environment variables in the [engine] section. Please note that multiple env variables in that configuration file exists — use the one in the [engine] section. + + Example: + + ```text + [engine] + env = ["HTTP_PROXY=http://{proxy-ip}:{proxy-port}", "HTTPS_PROXY=http://{proxy-ip}:{proxy-port}"] + ``` + +7. Reload systemd configuration + + ```sh + sudo systemctl daemon-reload + ``` + +8. Create OS groups, if they do not exist yet + + Reference: [Users and permissions](ece-users-permissions.md) + + ```sh + sudo groupadd elastic + sudo groupadd podman + ``` + +9. Add user `elastic` to the `podman` group + + Reference: [Users and permissions](ece-users-permissions.md) + + ```sh + sudo useradd -g "elastic" -G "podman" elastic + ``` + +10. As a sudoers user, add the following line to /etc/sudoers.d/99-ece-users + + Reference: [Users and permissions](ece-users-permissions.md) + + ```text + elastic ALL=(ALL) NOPASSWD:ALL + ``` + +11. Add the required options to the kernel boot arguments + + ```sh + sudo /sbin/grubby --update-kernel=ALL --args='cgroup_enable=memory cgroup.memory=nokmem swapaccount=1' + ``` + +12. Create the directory + + ```sh + sudo mkdir -p /etc/systemd/system/podman.socket.d + ``` + +13. As a sudoers user, create the file `/etc/systemd/system/podman.socket.d/podman.conf` with the following content. Set the correct ownership and permission. + + ::::{important} + Both `ListenStream=` and `ListenStream=/var/run/docker.sock` parameters are required! + :::: + + + File content: + + ```text + [Socket] + ListenStream= + ListenStream=/var/run/docker.sock + SocketMode=770 + SocketUser=elastic + SocketGroup=podman + ``` + + File ownership and permission: + + ```sh + sudo chown root:root /etc/systemd/system/podman.socket.d/podman.conf + sudo chmod 0644 /etc/systemd/system/podman.socket.d/podman.conf + ``` + +14. As a sudoers user, create the (text) file `/usr/bin/docker` with the following content. Verify that the regular double quotes in the text file are used (ASCII code Hex 22) + + ```text + #!/bin/bash + podman-remote --url unix:///var/run/docker.sock "$@" + ``` + +15. Set the file permissions on `/usr/bin/docker` + + ```sh + sudo chmod 0755 /usr/bin/docker + ``` + +16. As a sudoers user, add the following two lines to section `[storage]` in the file `/etc/containers/storage.conf`. Verify that those parameters are only defined once. Either remove or comment out potentially existing parameters. + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```text + runroot = "/mnt/data/docker/runroot/" + graphroot = "/mnt/data/docker" + ``` + +17. Enable podman so that itself and running containers start automatically after a reboot + + ```sh + sudo systemctl enable podman.service + sudo systemctl enable podman-restart.service + ``` + +18. Enable the `overlay` kernel module (check [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)) that the Podman `overlay` storage driver uses (check [Working with the Container Storage library and tools in Red Hat Enterprise Linux](https://www.redhat.com/en/blog/working-container-storage-library-and-tools-red-hat-enterprise-linux#:~:text=Storage%20Configuration)). + + In the Docker world there are two overlay drivers, overlay and overlay2. Today most users use the overlay2 driver, so we just use that one, and called it overlay. Refer also to [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/). + + ```sh + echo "overlay" | sudo tee -a /etc/modules-load.d/overlay.conf + ``` + +19. Format the additional data partition + + ```sh + sudo mkfs.xfs /dev/nvme1n1 + ``` + +20. Create the `/mnt/data/` directory used as a mount point + + ```sh + sudo install -o elastic -g elastic -d -m 700 /mnt/data + ``` + +21. As a sudoers user, modify the entry for the XFS volume in the `/etc/fstab` file to add `pquota,prjquota`. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ::::{note} + Replace `/dev/nvme1n1` in the following example with the corresponding device on your host, and add this example configuration as a single line to `/etc/fstab`. + :::: + + + ```text + /dev/nvme1n1 /mnt/data xfs defaults,nofail,x-systemd.automount,prjquota,pquota 0 2 + ``` + +22. Restart the local-fs target + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart local-fs.target + ``` + +23. Set the permissions on the newly mounted device + + ```sh + ls /mnt/data + sudo chown elastic:elastic /mnt/data + ``` + +24. Create the `/mnt/data/docker` directory for the Docker service storage + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```sh + sudo install -o elastic -g elastic -d -m 700 /mnt/data/docker + ``` + +25. If you want to use FirewallD, please ensure you meet the [networking prerequisites](ece-networking-prereq.md). Otherwise, you can disable it with: + + ```sh + sudo systemctl disable firewalld + ``` + + ::::{note} + If FirewallD does not exist on your VM, you can skip this step. + :::: + +26. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +30. Restart the podman service by running this command: + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart podman + ``` + +31. Reboot the RHEL host + + ```sh + sudo reboot + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/configure-host-suse-cloud.md b/deploy-manage/deploy/cloud-enterprise/configure-host-suse-cloud.md new file mode 100644 index 000000000..e3f6d2651 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-host-suse-cloud.md @@ -0,0 +1,345 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-hosts-sles12-cloud.html +--- + +# Configure host SUSE cloud [ece-configure-hosts-sles12-cloud] + +The following instructions show you how to prepare your hosts on SLES 12 SP5 or 15. + +* [Install Docker](#ece-install-docker-sles12-cloud) +* [Set up XFS on SLES](#ece-xfs-setup-sles12-cloud) +* [Update the configurations settings](#ece-update-config-sles-cloud) +* [Configure the Docker daemon options](#ece-configure-docker-daemon-sles12-cloud) + +If you want to install Elastic Cloud Enterprise on your own hosts, the steps for preparing your hosts can take a bit of time. There are two ways you can approach this: + +* **Think like a minimalist**: [Install the correct version of Docker](#ece-install-docker-sles12-cloud) on hosts that meet the [prerequisites](prepare-environment.md) for Elastic Cloud Enterprise, then skip ahead and [install Elastic Cloud Enterprise](install.md). Be aware that some checks during the installation can fail with this approach, which will mean doing further host preparation work before retrying the installation. +* **Cover your bases**: If you want to make absolutely sure that your installation of Elastic Cloud Enterprise can succeed on hosts that meet the [prerequisites](prepare-environment.md), or if any of the checks during the installation failed previously, run through the full preparation steps in this section and then and [install Elastic Cloud Enterprise](install.md). You’ll do a bit more work now, but life will be simpler later on. + +Regardless of which approach you take, the steps in this section need to be performed on every host that you want to use with Elastic Cloud Enterprise. + + +## Install Docker [ece-install-docker-sles12-cloud] + +::::{important} +Make sure to use a combination of Linux distribution and Docker version that is supported, following our official [Support matrix](https://www.elastic.co/support/matrix#elastic-cloud-enterprise). Using unsupported combinations can cause multiple issues with you ECE environment, such as failures to create system deployments, to upgrade workload deployments, proxy timeouts, and more. +:::: + + +1. Remove Docker and previously installed podman packages (if previously installed). + + ```sh + sudo zypper remove -y docker docker-ce podman podman-remote + ``` + +2. Update packages to the latest available versions + + ```sh + sudo zypper refresh + sudo zypper update -y + ``` + +3. Install Docker and other required packages: + + * For SLES 12: + + ```sh + sudo zypper install -y docker=24.0.7_ce-98.109.3 + ``` + + * For SLES 15: + + ```sh + sudo zypper install -y curl device-mapper lvm2 net-tools docker=24.0.7_ce-150000.198.2 net-tools + ``` + +4. Disable nscd, as it interferes with Elastic’s services: + + ```sh + sudo systemctl stop nscd + sudo systemctl disable nscd + ``` + + + +## Set up OS groups and user [ece_set_up_os_groups_and_user] + +1. If they don’t already exist, create the following OS groups: + + ```sh + sudo groupadd elastic + sudo groupadd docker + ``` + +2. Add the user to these groups: + + ```sh + sudo usermod -aG elastic,docker $USER + ``` + + + +## Set up XFS on SLES [ece-xfs-setup-sles12-cloud] + +XFS is required to support disk space quotas for Elasticsearch data directories. Some Linux distributions such as RHEL and Rocky Linux already provide XFS as the default file system. On SLES 12 and 15, you need to set up an XFS file system and have quotas enabled. + +Disk space quotas set a limit on the amount of disk space an Elasticsearch cluster node can use. Currently, quotas are calculated by a static ratio of 1:32, which means that for every 1 GB of RAM a cluster is given, a cluster node is allowed to consume 32 GB of disk space. + +::::{note} +Using LVM, `mdadm`, or a combination of the two for block device management is possible, but the configuration is not covered here, nor is it provided as part of supporting Elastic Cloud Enterprise. +:::: + + +::::{important} +You must use XFS and have quotas enabled on all allocators, otherwise disk usage won’t display correctly. +:::: + + +**Example:** Set up XFS on a single, pre-partitioned block device named `/dev/xvdg1`. Replace `/dev/xvdg1` in the following example with the corresponding device on your host. + +1. Format the partition: + + ```sh + sudo mkfs.xfs /dev/xvdg1 + ``` + +2. Create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g elastic -d -m 700 /mnt/data + ``` + +3. Add an entry to the `/etc/fstab` file for the new XFS volume. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ```sh + /dev/xvdg1 /mnt/data xfs defaults,pquota,prjquota,x-systemd.automount 0 0 + ``` + +4. Regenerate the mount files: + + ```sh + sudo mount -a + ``` + + + +## Update the configurations settings [ece-update-config-sles-cloud] + +1. Stop the Docker service: + + ```sh + sudo systemctl stop docker + ``` + +2. Enable cgroup accounting for memory and swap space. + + 1. In the `/etc/default/grub` file, ensure that the `GRUB_CMDLINE_LINUX=` variable includes these values: + + ```sh + cgroup_enable=memory swapaccount=1 cgroup.memory=nokmem + ``` + + 2. Update your Grub configuration: + + ```sh + sudo update-bootloader + ``` + +3. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +6. If you did not create the mount point earlier (if you did not set up XFS), create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g elastic -d -m 700 /mnt/data + ``` + +7. If you [set up a new device with XFS](#ece-xfs-setup-sles12-cloud) earlier: + + 1. Mount the block device (change the device name if you use a different device than `/dev/xvdg1`): + + ```sh + sudo mount /dev/xvdg1 + ``` + + 2. Set the permissions on the newly mounted device: + + ```sh + sudo chown $USER:elastic /mnt/data + ``` + +8. Create the `/mnt/data/docker` directory for the Docker service storage: + + ```sh + sudo install -o $USER -g elastic -d -m 700 /mnt/data/docker + ``` + + + +## Configure the Docker daemon [ece-configure-docker-daemon-sles12-cloud] + +1. Edit `/etc/docker/daemon.json`, and make sure that the following configuration values are present:
+ + ```json + { + "storage-driver": "overlay2", + "bip":"172.17.42.1/16", + "icc": false, + "log-driver": "json-file", + "log-opts": { + "max-size": "500m", + "max-file": "10" + }, + "data-root": "/mnt/data/docker" + } + ``` + +2. The user installing {{ece}} must have a User ID (UID) and Group ID (GID) of 1000 or higher. Make sure that the GID matches the ID of the `elastic`` group created earlier (likely to be 1000). You can set this using the following command: + + ```sh + sudo usermod -g $USER + ``` + +3. Apply the updated Docker daemon configuration: + + Reload the Docker daemon configuration: + + ```sh + sudo systemctl daemon-reload + ``` + + Restart the Docker service: + + ```sh + sudo systemctl restart docker + ``` + + Enable Docker to start on boot: + + ```sh + sudo systemctl enable docker + ``` + +4. Recommended: Tune your network settings. + + Create a `70-cloudenterprise.conf` file in the `/etc/sysctl.d/` file path that includes these network settings: + + ```sh + cat << SETTINGS | sudo tee /etc/sysctl.d/70-cloudenterprise.conf + net.ipv4.tcp_max_syn_backlog=65536 + net.core.somaxconn=32768 + net.core.netdev_max_backlog=32768 + net.ipv4.tcp_keepalive_time=1800 + net.netfilter.nf_conntrack_tcp_timeout_established=7200 + net.netfilter.nf_conntrack_max=262140 + SETTINGS + ``` + + 1. Ensure settings in /etc/sysctl.d/*.conf are applied on boot + + ```sh + SCRIPT_LOCATION="/var/lib/cloud/scripts/per-boot/00-load-sysctl-settings" + sudo sh -c "cat << EOF > ${SCRIPT_LOCATION} + #!/bin/bash + + set -x + + lsmod | grep ip_conntrack || modprobe ip_conntrack + + sysctl --system + EOF + " + sudo chmod +x ${SCRIPT_LOCATION} + ``` + +5. Reboot your system to ensure that all configuration changes take effect: + + ```literal + sudo reboot + ``` + +6. If the Docker daemon is not already running, start it: + + ```sh + sudo systemctl start docker + ``` + +7. After rebooting, verify that your Docker settings persist as expected: + + ```literal + sudo docker info | grep Root + ``` + + If the command returns `Docker Root Dir: /mnt/data/docker`, then your changes were applied successfully and persist as expected. + + If the command returns `Docker Root Dir: /var/lib/docker`, then you need to troubleshoot the previous configuration steps until the Docker settings are applied successfully before continuing with the installation process. For more information, check [Custom Docker daemon options](https://docs.docker.com/engine/admin/systemd/#/custom-docker-daemon-options) in the Docker documentation. + +8. Repeat these steps on other hosts that you want to use with Elastic Cloud Enterprise or follow the steps in the next section to start installing Elastic Cloud Enterprise. + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-host-suse-onprem.md b/deploy-manage/deploy/cloud-enterprise/configure-host-suse-onprem.md new file mode 100644 index 000000000..632b9a011 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-host-suse-onprem.md @@ -0,0 +1,345 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-hosts-sles12-onprem.html +--- + +# Configure host SUSE onprem [ece-configure-hosts-sles12-onprem] + +The following instructions show you how to prepare your hosts on SLES 12 SP5 or 15. + +* [Install Docker](#ece-install-docker-sles12-onprem) +* [Set up XFS on SLES](#ece-xfs-setup-sles12-onprem) +* [Update the configurations settings](#ece-update-config-sles-onprem) +* [Configure the Docker daemon options](#ece-configure-docker-daemon-sles12-onprem) + +If you want to install Elastic Cloud Enterprise on your own hosts, the steps for preparing your hosts can take a bit of time. There are two ways you can approach this: + +* **Think like a minimalist**: [Install the correct version of Docker](#ece-install-docker-sles12-onprem) on hosts that meet the [prerequisites](prepare-environment.md) for Elastic Cloud Enterprise, then skip ahead and [install Elastic Cloud Enterprise](install.md). Be aware that some checks during the installation can fail with this approach, which will mean doing further host preparation work before retrying the installation. +* **Cover your bases**: If you want to make absolutely sure that your installation of Elastic Cloud Enterprise can succeed on hosts that meet the [prerequisites](prepare-environment.md), or if any of the checks during the installation failed previously, run through the full preparation steps in this section and then and [install Elastic Cloud Enterprise](install.md). You’ll do a bit more work now, but life will be simpler later on. + +Regardless of which approach you take, the steps in this section need to be performed on every host that you want to use with Elastic Cloud Enterprise. + + +## Install Docker [ece-install-docker-sles12-onprem] + +::::{important} +Make sure to use a combination of Linux distribution and Docker version that is supported, following our official [Support matrix](https://www.elastic.co/support/matrix#elastic-cloud-enterprise). Using unsupported combinations can cause multiple issues with you ECE environment, such as failures to create system deployments, to upgrade workload deployments, proxy timeouts, and more. +:::: + + +1. Remove Docker and previously installed podman packages (if previously installed). + + ```sh + sudo zypper remove -y docker docker-ce podman podman-remote + ``` + +2. Update packages to the latest available versions + + ```sh + sudo zypper refresh + sudo zypper update -y + ``` + +3. Install Docker and other required packages: + + * For SLES 12: + + ```sh + sudo zypper install -y docker=24.0.7_ce-98.109.3 + ``` + + * For SLES 15: + + ```sh + sudo zypper install -y curl device-mapper lvm2 net-tools docker=24.0.7_ce-150000.198.2 net-tools + ``` + +4. Disable nscd, as it interferes with Elastic’s services: + + ```sh + sudo systemctl stop nscd + sudo systemctl disable nscd + ``` + + + +## Set up OS groups and user [ece_set_up_os_groups_and_user_2] + +1. If they don’t already exist, create the following OS groups: + + ```sh + sudo groupadd elastic + sudo groupadd docker + ``` + +2. Add the user to these groups: + + ```sh + sudo usermod -aG elastic,docker $USER + ``` + + + +## Set up XFS on SLES [ece-xfs-setup-sles12-onprem] + +XFS is required to support disk space quotas for Elasticsearch data directories. Some Linux distributions such as RHEL and Rocky Linux already provide XFS as the default file system. On SLES 12 and 15, you need to set up an XFS file system and have quotas enabled. + +Disk space quotas set a limit on the amount of disk space an Elasticsearch cluster node can use. Currently, quotas are calculated by a static ratio of 1:32, which means that for every 1 GB of RAM a cluster is given, a cluster node is allowed to consume 32 GB of disk space. + +::::{note} +Using LVM, `mdadm`, or a combination of the two for block device management is possible, but the configuration is not covered here, nor is it provided as part of supporting Elastic Cloud Enterprise. +:::: + + +::::{important} +You must use XFS and have quotas enabled on all allocators, otherwise disk usage won’t display correctly. +:::: + + +**Example:** Set up XFS on a single, pre-partitioned block device named `/dev/xvdg1`. Replace `/dev/xvdg1` in the following example with the corresponding device on your host. + +1. Format the partition: + + ```sh + sudo mkfs.xfs /dev/xvdg1 + ``` + +2. Create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g elastic -d -m 700 /mnt/data + ``` + +3. Add an entry to the `/etc/fstab` file for the new XFS volume. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ```sh + /dev/xvdg1 /mnt/data xfs defaults,pquota,prjquota,x-systemd.automount 0 0 + ``` + +4. Regenerate the mount files: + + ```sh + sudo mount -a + ``` + + + +## Update the configurations settings [ece-update-config-sles-onprem] + +1. Stop the Docker service: + + ```sh + sudo systemctl stop docker + ``` + +2. Enable cgroup accounting for memory and swap space. + + 1. In the `/etc/default/grub` file, ensure that the `GRUB_CMDLINE_LINUX=` variable includes these values: + + ```sh + cgroup_enable=memory swapaccount=1 cgroup.memory=nokmem + ``` + + 2. Update your Grub configuration: + + ```sh + sudo update-bootloader + ``` + +3. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +6. If you did not create the mount point earlier (if you did not set up XFS), create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g elastic -d -m 700 /mnt/data + ``` + +7. If you [set up a new device with XFS](#ece-xfs-setup-sles12-onprem) earlier: + + 1. Mount the block device (change the device name if you use a different device than `/dev/xvdg1`): + + ```sh + sudo mount /dev/xvdg1 + ``` + + 2. Set the permissions on the newly mounted device: + + ```sh + sudo chown $USER:elastic /mnt/data + ``` + +8. Create the `/mnt/data/docker` directory for the Docker service storage: + + ```sh + sudo install -o $USER -g elastic -d -m 700 /mnt/data/docker + ``` + + + +## Configure the Docker daemon [ece-configure-docker-daemon-sles12-onprem] + +1. Edit `/etc/docker/daemon.json`, and make sure that the following configuration values are present:
+ + ```json + { + "storage-driver": "overlay2", + "bip":"172.17.42.1/16", + "icc": false, + "log-driver": "json-file", + "log-opts": { + "max-size": "500m", + "max-file": "10" + }, + "data-root": "/mnt/data/docker" + } + ``` + +2. The user installing {{ece}} must have a User ID (UID) and Group ID (GID) of 1000 or higher. Make sure that the GID matches the ID of the `elastic`` group created earlier (likely to be 1000). You can set this using the following command: + + ```sh + sudo usermod -g $USER + ``` + +3. Apply the updated Docker daemon configuration: + + Reload the Docker daemon configuration: + + ```sh + sudo systemctl daemon-reload + ``` + + Restart the Docker service: + + ```sh + sudo systemctl restart docker + ``` + + Enable Docker to start on boot: + + ```sh + sudo systemctl enable docker + ``` + +4. Recommended: Tune your network settings. + + Create a `70-cloudenterprise.conf` file in the `/etc/sysctl.d/` file path that includes these network settings: + + ```sh + cat << SETTINGS | sudo tee /etc/sysctl.d/70-cloudenterprise.conf + net.ipv4.tcp_max_syn_backlog=65536 + net.core.somaxconn=32768 + net.core.netdev_max_backlog=32768 + net.ipv4.tcp_keepalive_time=1800 + net.netfilter.nf_conntrack_tcp_timeout_established=7200 + net.netfilter.nf_conntrack_max=262140 + SETTINGS + ``` + + 1. Ensure settings in /etc/sysctl.d/*.conf are applied on boot + + ```sh + SCRIPT_LOCATION="/var/lib/cloud/scripts/per-boot/00-load-sysctl-settings" + sudo sh -c "cat << EOF > ${SCRIPT_LOCATION} + #!/bin/bash + + set -x + + lsmod | grep ip_conntrack || modprobe ip_conntrack + + sysctl --system + EOF + " + sudo chmod +x ${SCRIPT_LOCATION} + ``` + +5. Reboot your system to ensure that all configuration changes take effect: + + ```literal + sudo reboot + ``` + +6. If the Docker daemon is not already running, start it: + + ```sh + sudo systemctl start docker + ``` + +7. After rebooting, verify that your Docker settings persist as expected: + + ```literal + sudo docker info | grep Root + ``` + + If the command returns `Docker Root Dir: /mnt/data/docker`, then your changes were applied successfully and persist as expected. + + If the command returns `Docker Root Dir: /var/lib/docker`, then you need to troubleshoot the previous configuration steps until the Docker settings are applied successfully before continuing with the installation process. For more information, check [Custom Docker daemon options](https://docs.docker.com/engine/admin/systemd/#/custom-docker-daemon-options) in the Docker documentation. + +8. Repeat these steps on other hosts that you want to use with Elastic Cloud Enterprise or follow the steps in the next section to start installing Elastic Cloud Enterprise. + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-host-ubuntu-cloud.md b/deploy-manage/deploy/cloud-enterprise/configure-host-ubuntu-cloud.md new file mode 100644 index 000000000..28203ca46 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-host-ubuntu-cloud.md @@ -0,0 +1,310 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-hosts-ubuntu-cloud.html +--- + +# Configure host Ubuntu cloud [ece-configure-hosts-ubuntu-cloud] + +The following instructions show you how to prepare your hosts on 20.04 LTS (Focal Fossa) and Ubuntu 22.04 LTS (Jammy Jellyfish). + +* [Install Docker 24.0](#ece-install-docker-ubuntu-cloud) +* [Set up XFS quotas](#ece-xfs-setup-ubuntu-cloud) +* [Update the configurations settings](#ece-update-config-ubuntu-cloud) +* [Configure the Docker daemon options](#ece-configure-docker-daemon-ubuntu-cloud) + + +## Install Docker [ece-install-docker-ubuntu-cloud] + +Install Docker LTS version 24.0 for Ubuntu 20.04 or 22.04. + +::::{important} +Make sure to use a combination of Linux distribution and Docker version that is supported, following our official [Support matrix](https://www.elastic.co/support/matrix#elastic-cloud-enterprise). Using unsupported combinations can cause multiple issues with you ECE environment, such as failures to create system deployments, to upgrade workload deployments, proxy timeouts, and more. +:::: + + +::::{note} +Docker 25 and higher are not compatible with ECE 3.7. +:::: + + +1. Install the Docker repository dependencies: + + ```sh + sudo apt-get install ca-certificates curl gnupg lsb-release + ``` + +2. Add Docker’s official GPG key: + + ```sh + sudo mkdir -m 0755 -p /etc/apt/keyrings + curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg + ``` + +3. Add the stable Docker repository: + + ```sh + echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + ``` + +4. Install the correct version of the `docker-ce` package, for Ubuntu 20.04 LTS (Focal Fossa) or Ubuntu 22.04 LTS (Jammy Jellyfish): + + ```sh + sudo apt install -y docker-ce=5:24.0.* docker-ce-cli=5:24.0.* containerd.io + ``` + + + +## Set up XFS quotas [ece-xfs-setup-ubuntu-cloud] + +XFS is required to support disk space quotas for Elasticsearch data directories. Some Linux distributions such as RHEL and Rocky Linux already provide XFS as the default file system. On Ubuntu, you need to set up an XFS file system and have quotas enabled. + +Disk space quotas set a limit on the amount of disk space an Elasticsearch cluster node can use. Currently, quotas are calculated by a static ratio of 1:32, which means that for every 1 GB of RAM a cluster is given, a cluster node is allowed to consume 32 GB of disk space. + +::::{note} +Using LVM, `mdadm`, or a combination of the two for block device management is possible, but the configuration is not covered here, and it is not supported by Elastic Cloud Enterprise. +:::: + + +::::{important} +You must use XFS and have quotas enabled on all allocators, otherwise disk usage won’t display correctly. +:::: + + +**Example:** Set up XFS on a single, pre-partitioned block device named `/dev/xvdg1`. + +1. Format the partition: + + ```sh + sudo mkfs.xfs /dev/xvdg1 + ``` + +2. Create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g $USER -d -m 700 /mnt/data + ``` + +3. Add an entry to the `/etc/fstab` file for the new XFS volume. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ```sh + /dev/xvdg1 /mnt/data xfs defaults,nofail,x-systemd.automount,prjquota,pquota 0 2 + ``` + +4. Regenerate the mount files: + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart local-fs.target + ``` + + + +## Update the configurations settings [ece-update-config-ubuntu-cloud] + +1. Stop the Docker service: + + ```sh + sudo systemctl stop docker + ``` + +2. Enable cgroup accounting for memory and swap space. + + 1. In the `/etc/default/grub` file, ensure that the `GRUB_CMDLINE_LINUX=` variable includes these values: + + ```sh + cgroup_enable=memory swapaccount=1 cgroup.memory=nokmem + ``` + + 2. Update your Grub configuration: + + ```sh + sudo update-grub + ``` + +3. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +6. If you did not create the mount point earlier (if you did not set up XFS), create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g $USER -d -m 700 /mnt/data + ``` + +7. If you [set up a new device with XFS](#ece-xfs-setup-ubuntu-cloud) earlier: + + 1. Mount the block device (change the device name if you use a different device than `/dev/xvdg1`): + + ```sh + sudo mount /dev/xvdg1 /mnt/data + ``` + + 2. Set the permissions on the newly mounted device: + + ```sh + sudo chown $USER:$USER /mnt/data + ``` + +8. Create the `/mnt/data/docker` directory for the Docker service storage: + + ```sh + sudo install -o $USER -g $USER -d -m 700 /mnt/data/docker + ``` + + + +## Configure the Docker daemon options [ece-configure-docker-daemon-ubuntu-cloud] + +::::{tip} +Docker creates a bridge IP address that can conflict with IP addresses on your internal network. To avoid an IP address conflict, change the `--bip=172.17.42.1/16` parameter in our examples to something that you know will work. If there is no conflict, you can omit the `--bip` parameter. The `--bip` parameter is internal to the host and can be set to the same IP for each host in the cluster. More information on Docker daemon options can be found in the [dockerd command line reference](https://docs.docker.com/engine/reference/commandline/dockerd/). +:::: + + +::::{tip} +You can specify `--log-opt max-size` and `--log-opt max-file` to define the Docker daemon containers log rotation. +:::: + + +1. Update `/etc/systemd/system/docker.service.d/docker.conf`. If the file path and file do not exist, create them first. + + ```sh + [Unit] + Description=Docker Service + After=multi-user.target + + [Service] + Environment="DOCKER_OPTS=-H unix:///run/docker.sock --data-root /mnt/data/docker --storage-driver=overlay2 --bip=172.17.42.1/16 --raw-logs --log-opt max-size=500m --log-opt max-file=10 --icc=false" + ExecStart= + ExecStart=/usr/bin/dockerd $DOCKER_OPTS + ``` + +2. Apply the updated Docker daemon configuration: + + Reload the Docker daemon configuration: + + ```sh + sudo systemctl daemon-reload + ``` + + Restart the Docker service: + + ```sh + sudo systemctl restart docker + ``` + + Enable Docker to start on boot: + + ```sh + sudo systemctl enable docker + ``` + +3. Enable your user to communicate with the Docker subsystem by adding it to the `docker` group: + + ```sh + sudo usermod -aG docker $USER + ``` + +4. Recommended: Tune your network settings. + + Create a `70-cloudenterprise.conf` file in the `/etc/sysctl.d/` file path that includes these network settings: + + ```sh + cat << SETTINGS | sudo tee /etc/sysctl.d/70-cloudenterprise.conf + net.ipv4.tcp_max_syn_backlog=65536 + net.core.somaxconn=32768 + net.core.netdev_max_backlog=32768 + SETTINGS + ``` + +5. Pin the Docker version to ensure that the package does not get upgraded: + + ```sh + echo "docker-ce hold" | sudo dpkg --set-selections + echo "docker-ce-cli hold" | sudo dpkg --set-selections + echo "containerd.io hold" | sudo dpkg --set-selections + ``` + +6. Reboot your system to ensure that all configuration changes take effect: + + ```literal + sudo reboot + ``` + +7. After rebooting, verify that your Docker settings persist as expected: + + ```literal + sudo docker info | grep Root + ``` + + If the command returns `Docker Root Dir: /mnt/data/docker`, then your changes were applied successfully and persist as expected. + + If the command returns `Docker Root Dir: /var/lib/docker`, then you need to troubleshoot the previous configuration steps until the Docker settings are applied successfully before continuing with the installation process. For more information, check [Custom Docker daemon options](https://docs.docker.com/engine/admin/systemd/#/custom-docker-daemon-options) in the Docker documentation. + +8. Repeat these steps on other hosts that you want to use with Elastic Cloud Enterprise or follow the steps in the next section to start installing Elastic Cloud Enterprise. + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-host-ubuntu-onprem.md b/deploy-manage/deploy/cloud-enterprise/configure-host-ubuntu-onprem.md new file mode 100644 index 000000000..302651ef8 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-host-ubuntu-onprem.md @@ -0,0 +1,310 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-hosts-ubuntu-onprem.html +--- + +# Configure host Ubuntu onprem [ece-configure-hosts-ubuntu-onprem] + +The following instructions show you how to prepare your hosts on 20.04 LTS (Focal Fossa) and Ubuntu 22.04 LTS (Jammy Jellyfish). + +* [Install Docker 24.0](#ece-install-docker-ubuntu-onprem) +* [Set up XFS quotas](#ece-xfs-setup-ubuntu-onprem) +* [Update the configurations settings](#ece-update-config-ubuntu-onprem) +* [Configure the Docker daemon options](#ece-configure-docker-daemon-ubuntu-onprem) + + +## Install Docker [ece-install-docker-ubuntu-onprem] + +Install Docker LTS version 24.0 for Ubuntu 20.04 or 22.04. + +::::{important} +Make sure to use a combination of Linux distribution and Docker version that is supported, following our official [Support matrix](https://www.elastic.co/support/matrix#elastic-cloud-enterprise). Using unsupported combinations can cause multiple issues with you ECE environment, such as failures to create system deployments, to upgrade workload deployments, proxy timeouts, and more. +:::: + + +::::{note} +Docker 25 and higher are not compatible with ECE 3.7. +:::: + + +1. Install the Docker repository dependencies: + + ```sh + sudo apt-get install ca-certificates curl gnupg lsb-release + ``` + +2. Add Docker’s official GPG key: + + ```sh + sudo mkdir -m 0755 -p /etc/apt/keyrings + curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg + ``` + +3. Add the stable Docker repository: + + ```sh + echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + ``` + +4. Install the correct version of the `docker-ce` package, for Ubuntu 20.04 LTS (Focal Fossa) or Ubuntu 22.04 LTS (Jammy Jellyfish): + + ```sh + sudo apt install -y docker-ce=5:24.0.* docker-ce-cli=5:24.0.* containerd.io + ``` + + + +## Set up XFS quotas [ece-xfs-setup-ubuntu-onprem] + +XFS is required to support disk space quotas for Elasticsearch data directories. Some Linux distributions such as RHEL and Rocky Linux already provide XFS as the default file system. On Ubuntu, you need to set up an XFS file system and have quotas enabled. + +Disk space quotas set a limit on the amount of disk space an Elasticsearch cluster node can use. Currently, quotas are calculated by a static ratio of 1:32, which means that for every 1 GB of RAM a cluster is given, a cluster node is allowed to consume 32 GB of disk space. + +::::{note} +Using LVM, `mdadm`, or a combination of the two for block device management is possible, but the configuration is not covered here, and it is not supported by Elastic Cloud Enterprise. +:::: + + +::::{important} +You must use XFS and have quotas enabled on all allocators, otherwise disk usage won’t display correctly. +:::: + + +**Example:** Set up XFS on a single, pre-partitioned block device named `/dev/xvdg1`. + +1. Format the partition: + + ```sh + sudo mkfs.xfs /dev/xvdg1 + ``` + +2. Create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g $USER -d -m 700 /mnt/data + ``` + +3. Add an entry to the `/etc/fstab` file for the new XFS volume. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ```sh + /dev/xvdg1 /mnt/data xfs defaults,nofail,x-systemd.automount,prjquota,pquota 0 2 + ``` + +4. Regenerate the mount files: + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart local-fs.target + ``` + + + +## Update the configurations settings [ece-update-config-ubuntu-onprem] + +1. Stop the Docker service: + + ```sh + sudo systemctl stop docker + ``` + +2. Enable cgroup accounting for memory and swap space. + + 1. In the `/etc/default/grub` file, ensure that the `GRUB_CMDLINE_LINUX=` variable includes these values: + + ```sh + cgroup_enable=memory swapaccount=1 cgroup.memory=nokmem + ``` + + 2. Update your Grub configuration: + + ```sh + sudo update-grub + ``` + +3. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +6. If you did not create the mount point earlier (if you did not set up XFS), create the `/mnt/data/` directory as a mount point: + + ```sh + sudo install -o $USER -g $USER -d -m 700 /mnt/data + ``` + +7. If you [set up a new device with XFS](#ece-xfs-setup-ubuntu-onprem) earlier: + + 1. Mount the block device (change the device name if you use a different device than `/dev/xvdg1`): + + ```sh + sudo mount /dev/xvdg1 /mnt/data + ``` + + 2. Set the permissions on the newly mounted device: + + ```sh + sudo chown $USER:$USER /mnt/data + ``` + +8. Create the `/mnt/data/docker` directory for the Docker service storage: + + ```sh + sudo install -o $USER -g $USER -d -m 700 /mnt/data/docker + ``` + + + +## Configure the Docker daemon options [ece-configure-docker-daemon-ubuntu-onprem] + +::::{tip} +Docker creates a bridge IP address that can conflict with IP addresses on your internal network. To avoid an IP address conflict, change the `--bip=172.17.42.1/16` parameter in our examples to something that you know will work. If there is no conflict, you can omit the `--bip` parameter. The `--bip` parameter is internal to the host and can be set to the same IP for each host in the cluster. More information on Docker daemon options can be found in the [dockerd command line reference](https://docs.docker.com/engine/reference/commandline/dockerd/). +:::: + + +::::{tip} +You can specify `--log-opt max-size` and `--log-opt max-file` to define the Docker daemon containers log rotation. +:::: + + +1. Update `/etc/systemd/system/docker.service.d/docker.conf`. If the file path and file do not exist, create them first. + + ```sh + [Unit] + Description=Docker Service + After=multi-user.target + + [Service] + Environment="DOCKER_OPTS=-H unix:///run/docker.sock --data-root /mnt/data/docker --storage-driver=overlay2 --bip=172.17.42.1/16 --raw-logs --log-opt max-size=500m --log-opt max-file=10 --icc=false" + ExecStart= + ExecStart=/usr/bin/dockerd $DOCKER_OPTS + ``` + +2. Apply the updated Docker daemon configuration: + + Reload the Docker daemon configuration: + + ```sh + sudo systemctl daemon-reload + ``` + + Restart the Docker service: + + ```sh + sudo systemctl restart docker + ``` + + Enable Docker to start on boot: + + ```sh + sudo systemctl enable docker + ``` + +3. Enable your user to communicate with the Docker subsystem by adding it to the `docker` group: + + ```sh + sudo usermod -aG docker $USER + ``` + +4. Recommended: Tune your network settings. + + Create a `70-cloudenterprise.conf` file in the `/etc/sysctl.d/` file path that includes these network settings: + + ```sh + cat << SETTINGS | sudo tee /etc/sysctl.d/70-cloudenterprise.conf + net.ipv4.tcp_max_syn_backlog=65536 + net.core.somaxconn=32768 + net.core.netdev_max_backlog=32768 + SETTINGS + ``` + +5. Pin the Docker version to ensure that the package does not get upgraded: + + ```sh + echo "docker-ce hold" | sudo dpkg --set-selections + echo "docker-ce-cli hold" | sudo dpkg --set-selections + echo "containerd.io hold" | sudo dpkg --set-selections + ``` + +6. Reboot your system to ensure that all configuration changes take effect: + + ```literal + sudo reboot + ``` + +7. After rebooting, verify that your Docker settings persist as expected: + + ```literal + sudo docker info | grep Root + ``` + + If the command returns `Docker Root Dir: /mnt/data/docker`, then your changes were applied successfully and persist as expected. + + If the command returns `Docker Root Dir: /var/lib/docker`, then you need to troubleshoot the previous configuration steps until the Docker settings are applied successfully before continuing with the installation process. For more information, check [Custom Docker daemon options](https://docs.docker.com/engine/admin/systemd/#/custom-docker-daemon-options) in the Docker documentation. + +8. Repeat these steps on other hosts that you want to use with Elastic Cloud Enterprise or follow the steps in the next section to start installing Elastic Cloud Enterprise. + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-operating-system-cloud.md b/deploy-manage/deploy/cloud-enterprise/configure-operating-system-cloud.md new file mode 100644 index 000000000..17ae9b46c --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-operating-system-cloud.md @@ -0,0 +1,17 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-os-cloud.html +--- + +# Configure your operating system cloud [ece-configure-os-cloud] + +Before installing Elastic Cloud Enterprise, you have to prepare your hosts with one of the following Linux distributions: + +* [Ubuntu 20.04 LTS (Focal Fossa) and Ubuntu 22.04 LTS (Jammy Jellyfish)](configure-host-ubuntu-cloud.md) +* [Red Hat Enterprise Linux (RHEL) 8 and 9](configure-host-rhel-cloud.md) +* [Rocky Linux 8 and 9](configure-host-rhel-cloud.md) +* [SUSE Linux Enterprise Server (SLES) 12 SP5 and 15](configure-host-suse-cloud.md) + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/configure-operating-system-onprem.md b/deploy-manage/deploy/cloud-enterprise/configure-operating-system-onprem.md new file mode 100644 index 000000000..599d6e225 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure-operating-system-onprem.md @@ -0,0 +1,17 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-os-onprem.html +--- + +# Configure your operating system onprem [ece-configure-os-onprem] + +Before installing Elastic Cloud Enterprise, you have to prepare your hosts with one of the following Linux distributions: + +* [Ubuntu 20.04 LTS (Focal Fossa) and Ubuntu 22.04 LTS (Jammy Jellyfish)](configure-host-ubuntu-onprem.md) +* [Red Hat Enterprise Linux (RHEL) 8 and 9](configure-host-rhel-onprem.md) +* [Rocky Linux 8 and 9](configure-host-rhel-onprem.md) +* [SUSE Linux Enterprise Server (SLES) 12 SP5 and 15](configure-host-suse-onprem.md) + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/configure.md b/deploy-manage/deploy/cloud-enterprise/configure.md new file mode 100644 index 000000000..2ad081b96 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/configure.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece.html +--- + +# Configure [ece-configuring-ece] + +Now that you have Elastic Cloud Enterprise up and running, take a look at some of the additional features that you can configure: + +* [System deployment configuration](system-deployments-configuration.md) - Best practices for ECE system deployments to ensure a highly available and resilient setup. +* [Configure deployment templates](configure-deployment-templates.md) - Make the most out of deployment templates by configuring ECE for your hardware and creating custom deployment templates. +* [Manage snapshot repositories](../../tools/snapshot-and-restore/cloud-enterprise.md) - To back up your Elasticsearch clusters automatically, you need to configure a snapshot repository. +* [Manage licenses](../../license/manage-your-license-in-ece.md) - Keep Elastic Cloud Enterprise current with a valid license. +* [Change endpoint URLs](change-endpoint-urls.md) - Set where Elasticsearch and Kibana can be accessed from. +* [Configure allocator affinity](configure-allocator-affinity.md) - Determine how ECE distributes your Elastic Stack deployments across allocators. +* [Change allocator disconnect timeout](change-allocator-disconnect-timeout.md) - Configure how long ECE waits before considering allocators to be disconnected. +* [Migrate ECE on Podman hosts to SELinux in enforcing mode](migrate-ece-on-podman-hosts-to-selinux-enforce.md) - Migrate ECE to SELinux in `enforcing` mode using Podman. + diff --git a/deploy-manage/deploy/cloud-enterprise/create-deployment.md b/deploy-manage/deploy/cloud-enterprise/create-deployment.md new file mode 100644 index 000000000..912923c97 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/create-deployment.md @@ -0,0 +1,20 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-create-deployment.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-access-kibana.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-kibana.html +--- + +# Create a deployment + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/339 + +% Scope notes: create then access. and then link to add data + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-create-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-access-kibana.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-manage-kibana.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/customize-deployment.md b/deploy-manage/deploy/cloud-enterprise/customize-deployment.md new file mode 100644 index 000000000..db8c411bd --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/customize-deployment.md @@ -0,0 +1,37 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-customize-deployment.html +--- + +# Customize your deployment [ece-customize-deployment] + +You can either customize a new deployment, or customize an existing one. On the **Create a deployment** page, select **Edit settings** to change the cloud provider, region, hardware profile, and stack version; or select **Advanced settings** for more complex configuration settings. + +On the **Advanced settings** page, you can change the following settings: + +* Enable [autoscaling](../../autoscaling.md) so that the available resources adjust automatically as demands on the deployment change. +* If you don’t want to autoscale your deployment, you can manually increase or decrease capacity by adjusting the size of hot, warm, cold, and frozen [data tiers](../../../manage-data/lifecycle/data-tiers.md) nodes. For example, you might want to add warm tier nodes if you have time series data that is accessed less-frequently and rarely needs to be updated. Alternatively, you might need cold tier nodes if you have time series data that is accessed occasionally and not normally updated. + + * From the **Size per zone** drop-down menu, select what best fits your requirements. + + :::{image} ../../../images/cloud-enterprise-ec-customize-deployment2.png + :alt: Customize hot data and content tier nodes + ::: + + Tiers increase in size before they increase the number of nodes. Based on the size that you select, the number of nodes is calculated for you automatically. Each node can be scaled up to 58GB RAM for Azure or 64GB RAM for GCP and AWS. The **Architecture** summary displays the total number of nodes per zone, where each circle color represents a different node type. + + :::{image} ../../../images/cloud-enterprise-ec-number-of-nodes.png + :alt: Number of nodes per deployment size + ::: + + * Adjust the number of **Availability zones** to increase fault tolerance for the deployment. + +* Open **Edit user settings** to change the YML configuration file to further customize how you run {{es}}. + +For more information, refer to [Editing your user settings](edit-stack-settings.md). + +* Enable specific {{es}} plugins which are not enabled by default. +* Enable additional features, such as Machine Learning or coordinating nodes. +* Set specific configuration parameters for your {{es}} nodes or {{kib}} instances. + +That’s it! Now that you are up and running, [start exploring with {{kib}}](create-deployment.md), our open-source visualization tool. If you’re not familiar with adding data, yet, {{kib}} can show you how to index your data into {{es}}. diff --git a/deploy-manage/deploy/cloud-enterprise/default-system-deployment-versions.md b/deploy-manage/deploy/cloud-enterprise/default-system-deployment-versions.md new file mode 100644 index 000000000..a2df2dd8f --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/default-system-deployment-versions.md @@ -0,0 +1,33 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-system-deployment-versions.html +--- + +# Default system deployment versions [ece-system-deployment-versions] + +When installing or upgrading {{ece}}, its associated system deployments run by default on the Elastic Stack versions listed in the following table. + +Note that since version 2.7.0, system deployments are automatically upgraded when upgrading {{ece}}. Don’t attempt to upgrade system deployments manually. Instead, follow the [ECE upgrade instructions](../../upgrade/orchestrator/upgrade-cloud-enterprise.md). + +| {{ece}} version | Admin cluster | Logging & Metrics cluster | Security cluster | +| --- | --- | --- | --- | +| 3.7.1 | 7.17.20 | 7.17.20 | 8.13.2 | +| 3.6.2 | 7.17.15 | 7.17.15 | 8.11.1 | +| 3.6.1 | 7.17.13 | 7.17.13 | 8.9.2 | +| 3.6.0 | 7.17.10 | 7.17.10 | 8.7.1 | +| 3.5.1 | 7.17.6 | 7.17.6 | 7.17.6 | +| 3.5.0 | 7.17.6 | 7.17.6 | 7.17.6 | +| 3.4.1 | 7.17.6 | 7.17.6 | 7.17.6 | +| 3.4.0 | 7.17.6 | 7.17.6 | 7.17.6 | +| 3.3.0 | 7.17.5 | 7.17.5 | 7.17.5 | +| 3.2.1 | 7.17.3 | 7.17.3 | 7.17.3 | +| 3.2.0 | 7.17.3 | 7.17.3 | 7.17.3 | +| 3.1.1 | 7.17.1 | 7.17.1 | 7.17.1 | +| 3.1.0 | 7.17.1 | 7.17.1 | 7.17.1 | +| 3.0.0 | 7.17.0 | 7.17.0 | 7.17.0 | +| 2.13.4 | 7.17.13 | 7.17.13 | 7.17.13 | +| 2.13.3 | 7.17.11 | 7.17.11 | 7.17.11 | +| 2.13.2 | 7.17.3 | 7.17.3 | 7.17.3 | +| 2.13.1 | 7.16.3 | 7.16.3 | 7.16.3 | +| 2.13.0 | 7.16.2 | 7.16.2 | 7.16.2 | + diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-an-orchestrator.md b/deploy-manage/deploy/cloud-enterprise/deploy-an-orchestrator.md new file mode 100644 index 000000000..3fc28c128 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-an-orchestrator.md @@ -0,0 +1,7 @@ +# Deploy an orchestrator + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/339 + +% Scope notes: Introduction about the content of this big section (which covers install and configuration possibilities of the orchestrator) \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-large-installation-cloud.md b/deploy-manage/deploy/cloud-enterprise/deploy-large-installation-cloud.md new file mode 100644 index 000000000..20e7e75a6 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-large-installation-cloud.md @@ -0,0 +1,93 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-large-cloud.html +--- + +# Deploy a large installation cloud [ece-install-large-cloud] + +This type of installation is recommended for deployments with significant overall search and indexing throughput. You need: + +* 3 hosts with at least 64 GB RAM each for directors and coordinators (ECE management services) +* 3 hosts for allocators, each with one of the following RAM configurations: + + * 1 x 256 GB RAM + * 2 x 128 GB RAM + * 4 x 64 GB RAM + +* 3 hosts with 16 GB RAM each for proxies +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-9.png +:alt: A large installation with nine to twelve hosts across three availability zones +::: + + +## Before you start [ece_before_you_start_3] + +Note that the large-sized Elastic Cloud Enterprise installation separates the allocator and proxy roles from the director and coordinator roles (ECE management services). + +**Check the recommended JVM Heap sizes** + +| Service | JVM Heap Size (Xms and Xmx) | +| --- | --- | +| `runner` | 1 GB | +| `allocator` | 4 GB | +| `zookeeper` | 24 GB | +| `director` | 1 GB | +| `constructor` | 4 GB | +| `admin-console` | 24 GB | + +::::{warning} +For production environments, you must define the memory settings for each role, except for the `proxy` role, as starting from ECE 2.4 the JVM proxy was replaced with a Golang-based proxy. If you don’t set any memory setting, the default values are used, which are inadequate for production environments and can lead to performance or stability issues. +:::: + + + +## Installation steps [ece_installation_steps_3] + +1. Install Elastic Cloud Enterprise on the first host to start a new installation with your first availability zone. This first host holds all roles to help bootstrap the rest of the installation, but you will remove some of its roles in a later step. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"24G","xmx":"24G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"24G","xmx":"24G"}}' + ``` + + After the installation completes, copy down the coordinator host IP address, user credentials, and roles token information. Keep this information safe. + +2. Generate a new roles token that persists for one hour on the first host, so that other hosts can join your installation with the right role permissions in subsequent steps (referred to as `MY_TOKEN`). The new token needs to enable the director, coordinator, and proxy roles. + + ```sh + curl -k -H 'Content-Type: application/json' -u admin:PASSWORD https://localhost:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": false, "roles": ["director", "coordinator", "proxy"] }' + ``` + +3. Install Elastic Cloud Enterprise on a second and third host, placing them into a second and a third availability zone, and assign them the `director` and `coordinator` roles. Do not assign the `allocator` or the `proxy` role, as these hosts should not handle or route any user requests. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"24G","xmx":"24G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"24G","xmx":"24G"}}' + ``` + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"24G","xmx":"24G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"24G","xmx":"24G"}}' + ``` + +4. To handle the Elasticsearch and Kibana workload, install Elastic Cloud Enterprise on three or more hosts, distributing them evenly across the existing three availability zones, or on however many hosts you think you need initially, and assign them the `allocator` role. Make sure you include the coordinator host IP information and allocator roles token from step 1. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + ``` + +5. To handle the routing of user requests to Elasticsearch, install Elastic Cloud Enterprise on a three additional hosts, distributing them evenly across the existing three availability zones, and assign them the `proxy` role. Do not assign any other roles, as these hosts should only route user requests. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "proxy" --availability-zone MY_ZONE-1 --memory-settings + '{"runner":{"xms":"1G","xmx":"1G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "proxy" --availability-zone MY_ZONE-2 --memory-settings + '{"runner":{"xms":"1G","xmx":"1G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "proxy" --availability-zone MY_ZONE-3 --memory-settings + '{"runner":{"xms":"1G","xmx":"1G"}}' + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-large-installation-onprem.md b/deploy-manage/deploy/cloud-enterprise/deploy-large-installation-onprem.md new file mode 100644 index 000000000..4de56154a --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-large-installation-onprem.md @@ -0,0 +1,93 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-large-onprem.html +--- + +# Deploy a large installation onprem [ece-install-large-onprem] + +This type of installation is recommended for deployments with significant overall search and indexing throughput. You need: + +* 3 hosts with at least 64 GB RAM each for directors and coordinators (ECE management services) +* 3 hosts for allocators, each with one of the following RAM configurations: + + * 1 x 256 GB RAM + * 2 x 128 GB RAM + * 4 x 64 GB RAM + +* 3 hosts with 16 GB RAM each for proxies +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-9.png +:alt: A large installation with nine to twelve hosts across three availability zones +::: + + +## Before you start [ece_before_you_start_6] + +Note that the large-sized Elastic Cloud Enterprise installation separates the allocator and proxy roles from the director and coordinator roles (ECE management services). + +**Check the recommended JVM Heap sizes** + +| Service | JVM Heap Size (Xms and Xmx) | +| --- | --- | +| `runner` | 1 GB | +| `allocator` | 4 GB | +| `zookeeper` | 24 GB | +| `director` | 1 GB | +| `constructor` | 4 GB | +| `admin-console` | 24 GB | + +::::{warning} +For production environments, you must define the memory settings for each role, except for the `proxy` role, as starting from ECE 2.4 the JVM proxy was replaced with a Golang-based proxy. If you don’t set any memory setting, the default values are used, which are inadequate for production environments and can lead to performance or stability issues. +:::: + + + +## Installation steps [ece_installation_steps_6] + +1. Install Elastic Cloud Enterprise on the first host to start a new installation with your first availability zone. This first host holds all roles to help bootstrap the rest of the installation, but you will remove some of its roles in a later step. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"24G","xmx":"24G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"24G","xmx":"24G"}}' + ``` + + After the installation completes, copy down the coordinator host IP address, user credentials, and roles token information. Keep this information safe. + +2. Generate a new roles token that persists for one hour on the first host, so that other hosts can join your installation with the right role permissions in subsequent steps (referred to as `MY_TOKEN`). The new token needs to enable the director, coordinator, and proxy roles. + + ```sh + curl -k -H 'Content-Type: application/json' -u admin:PASSWORD https://localhost:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": false, "roles": ["director", "coordinator", "proxy"] }' + ``` + +3. Install Elastic Cloud Enterprise on a second and third host, placing them into a second and a third availability zone, and assign them the `director` and `coordinator` roles. Do not assign the `allocator` or the `proxy` role, as these hosts should not handle or route any user requests. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"24G","xmx":"24G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"24G","xmx":"24G"}}' + ``` + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"24G","xmx":"24G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"24G","xmx":"24G"}}' + ``` + +4. To handle the Elasticsearch and Kibana workload, install Elastic Cloud Enterprise on three or more hosts, distributing them evenly across the existing three availability zones, or on however many hosts you think you need initially, and assign them the `allocator` role. Make sure you include the coordinator host IP information and allocator roles token from step 1. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + ``` + +5. To handle the routing of user requests to Elasticsearch, install Elastic Cloud Enterprise on a three additional hosts, distributing them evenly across the existing three availability zones, and assign them the `proxy` role. Do not assign any other roles, as these hosts should only route user requests. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "proxy" --availability-zone MY_ZONE-1 --memory-settings + '{"runner":{"xms":"1G","xmx":"1G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "proxy" --availability-zone MY_ZONE-2 --memory-settings + '{"runner":{"xms":"1G","xmx":"1G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "proxy" --availability-zone MY_ZONE-3 --memory-settings + '{"runner":{"xms":"1G","xmx":"1G"}}' + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-medium-installation-cloud.md b/deploy-manage/deploy/cloud-enterprise/deploy-medium-installation-cloud.md new file mode 100644 index 000000000..990fd96f7 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-medium-installation-cloud.md @@ -0,0 +1,75 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-medium-cloud.html +--- + +# Deploy a medium installation cloud [ece-install-medium-cloud] + +This type of installation is recommended for many production setups. You need: + +* 3 hosts with at least 32 GB RAM each for directors and coordinators (ECE management services), and proxies +* 3 hosts with 256 GB RAM each for allocators +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-6.png +:alt: A medium installation with nine to twelve hosts across three availability zones +::: + + +## Before you start [ece_before_you_start_2] + +* Monitor the load on proxies and make sure the volume of user requests routed by the proxies does not affect the resources available to the ECE management services. +* Note that the medium-sized Elastic Cloud Enterprise installation separates the allocator from the director and coordinator roles (ECE management services) and the proxy roles. + +**Check the recommended JVM Heap sizes** + +| Service | JVM Heap Size (Xms and Xmx) | +| --- | --- | +| `runner` | 1 GB | +| `allocator` | 4 GB | +| `zookeeper` | 8 GB | +| `director` | 1 GB | +| `constructor` | 4 GB | +| `admin-console` | 8 GB | + +::::{warning} +For production environments, you must define the memory settings for each role, except for the `proxy` role, as starting from ECE 2.4 the JVM proxy was replaced with a Golang-based proxy. If you don’t set any memory setting, the default values are used, which are inadequate for production environments and can lead to performance or stability issues. +:::: + + + +## Installation steps [ece_installation_steps_2] + +1. Install Elastic Cloud Enterprise on the first host to start a new installation with your first availability zone. This first host holds all roles to help bootstrap the rest of the installation, but you will remove some of its roles in a later step. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"8G","xmx":"8G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"8G","xmx":"8G"}}' + ``` + + After the installation completes, copy down the coordinator host IP address, user credentials, and roles token information. Keep this information safe. + +2. Generate a new roles token that persists for one hour on the first host, so that other hosts can join your installation with the right role permissions in the next step (referred to as `MY_TOKEN`). The new token needs to enable the director, coordinator and proxy roles. + + ```sh + curl -k -H 'Content-Type: application/json' -u admin:PASSWORD https://localhost:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": false, "roles": ["director", "coordinator", "proxy"] }' + ``` + +3. Install Elastic Cloud Enterprise on a second and third host, placing them into a second and a third availability zone, and assign them the `director`, `coordinator`, and `proxy` roles. Do not assign the `allocator` role, as these hosts should not handle any user requests. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"8G","xmx":"8G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"8G","xmx":"8G"}}' + ``` + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"8G","xmx":"8G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"8G","xmx":"8G"}}' + ``` + +4. To handle the Elasticsearch and Kibana workload, install Elastic Cloud Enterprise on a fourth, fifth, and sixth host, distributing them evenly across the existing three availability zones and assign them the `allocator` role. Make sure you include the coordinator host IP information and allocator roles token from step 1. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-medium-installation-onprem.md b/deploy-manage/deploy/cloud-enterprise/deploy-medium-installation-onprem.md new file mode 100644 index 000000000..93997d08c --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-medium-installation-onprem.md @@ -0,0 +1,75 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-medium-onprem.html +--- + +# Deploy a medium installation onprem [ece-install-medium-onprem] + +This type of installation is recommended for many production setups. You need: + +* 3 hosts with at least 32 GB RAM each for directors and coordinators (ECE management services), and proxies +* 3 hosts with 256 GB RAM each for allocators +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-6.png +:alt: A medium installation with nine to twelve hosts across three availability zones +::: + + +## Before you start [ece_before_you_start_5] + +* Monitor the load on proxies and make sure the volume of user requests routed by the proxies does not affect the resources available to the ECE management services. +* Note that the medium-sized Elastic Cloud Enterprise installation separates the allocator from the director and coordinator roles (ECE management services) and the proxy roles. + +**Check the recommended JVM Heap sizes** + +| Service | JVM Heap Size (Xms and Xmx) | +| --- | --- | +| `runner` | 1 GB | +| `allocator` | 4 GB | +| `zookeeper` | 8 GB | +| `director` | 1 GB | +| `constructor` | 4 GB | +| `admin-console` | 8 GB | + +::::{warning} +For production environments, you must define the memory settings for each role, except for the `proxy` role, as starting from ECE 2.4 the JVM proxy was replaced with a Golang-based proxy. If you don’t set any memory setting, the default values are used, which are inadequate for production environments and can lead to performance or stability issues. +:::: + + + +## Installation steps [ece_installation_steps_5] + +1. Install Elastic Cloud Enterprise on the first host to start a new installation with your first availability zone. This first host holds all roles to help bootstrap the rest of the installation, but you will remove some of its roles in a later step. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"8G","xmx":"8G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"8G","xmx":"8G"}}' + ``` + + After the installation completes, copy down the coordinator host IP address, user credentials, and roles token information. Keep this information safe. + +2. Generate a new roles token that persists for one hour on the first host, so that other hosts can join your installation with the right role permissions in the next step (referred to as `MY_TOKEN`). The new token needs to enable the director, coordinator and proxy roles. + + ```sh + curl -k -H 'Content-Type: application/json' -u admin:PASSWORD https://localhost:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": false, "roles": ["director", "coordinator", "proxy"] }' + ``` + +3. Install Elastic Cloud Enterprise on a second and third host, placing them into a second and a third availability zone, and assign them the `director`, `coordinator`, and `proxy` roles. Do not assign the `allocator` role, as these hosts should not handle any user requests. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"8G","xmx":"8G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"8G","xmx":"8G"}}' + ``` + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"zookeeper":{"xms":"8G","xmx":"8G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"8G","xmx":"8G"}}' + ``` + +4. To handle the Elasticsearch and Kibana workload, install Elastic Cloud Enterprise on a fourth, fifth, and sixth host, distributing them evenly across the existing three availability zones and assign them the `allocator` role. Make sure you include the coordinator host IP information and allocator roles token from step 1. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'ALLOCATOR_TOKEN' --roles "allocator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"}}' + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-small-installation-cloud.md b/deploy-manage/deploy/cloud-enterprise/deploy-small-installation-cloud.md new file mode 100644 index 000000000..16541a1d4 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-small-installation-cloud.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-small-cloud.html +--- + +# Deploy a small installation cloud [ece-install-small-cloud] + +The type of installation is recommended for development, test, and small-scale use cases. You need: + +* 3 hosts with 128 GB RAM +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-3.png +:alt: A small baseline installation with three hosts across three availability zones +::: + + +## Before you start [ece_before_you_start] + +* This type of installation is **not recommended for high-traffic workloads**. +* You must not use **spinning disks** with small ECE installations, as these are not supported when you run allocators and ECE management services on the same server. +* Note that the small-size ECE installation keeps the directors and coordinators roles (ECE management services) on the same hosts as your allocators and proxies. + +**Check the recommended JVM Heap sizes** + +| Service | JVM Heap Size (Xms and Xmx) | +| --- | --- | +| `runner` | 1 GB | +| `allocator` | 4 GB | +| `zookeeper` | 4 GB | +| `director` | 1 GB | +| `constructor` | 4 GB | +| `admin-console` | 4 GB | + +::::{warning} +For production environments, you must define the memory settings for each role, except for the `proxy` role, as starting from ECE 2.4 the JVM proxy was replaced with a Golang-based proxy. If you don’t set any memory setting, the default values are used, which are inadequate for production environments and can lead to performance or stability issues. +:::: + + + +## Installation steps [ece_installation_steps] + +1. Install Elastic Cloud Enterprise on the first host to start a new installation with your first availability zone. This first host holds all roles to help bootstrap the rest of the installation. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"4G","xmx":"4G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"4G","xmx":"4G"}}' + ``` + + After the installation completes, copy down the coordinator host IP address, user credentials, and roles token information. Keep this information safe. + +2. Generate a new roles token that persists for one hour on the first host, so that other hosts can join your installation with the right role permissions in the next step (referred to as `MY_TOKEN`). The new token needs to enable all host roles, which none of the tokens automatically generated by the installation on the first host provide. + + ```sh + curl -k -H 'Content-Type: application/json' -u admin:PASSWORD https://localhost:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": false, "roles": ["director", "coordinator", "proxy", "allocator"] }' + ``` + +3. Install Elastic Cloud Enterprise on a second and third host, placing them into a second and a third availability zone, and assign them the same roles and memory settings as the first host. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy,allocator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"4G","xmx":"4G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"4G","xmx":"4G"}}' + ``` + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy,allocator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"4G","xmx":"4G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"4G","xmx":"4G"}}' + ``` + +4. [Change the deployment configuration for the `admin-console-elasticsearch`, `logging-and-metrics`, and `security` clusters](working-with-deployments.md) to use three availability zones and resize the nodes to use at least 4 GB of RAM. This change makes sure that the clusters used by the administration console are highly available and provisioned sufficiently. +5. [Log into the Cloud UI](log-into-cloud-ui.md) to provision your deployment. + +If necessary, you can scale and deploy a [medium installation](deploy-medium-installation-cloud.md). diff --git a/deploy-manage/deploy/cloud-enterprise/deploy-small-installation-onprem.md b/deploy-manage/deploy/cloud-enterprise/deploy-small-installation-onprem.md new file mode 100644 index 000000000..2c511663a --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deploy-small-installation-onprem.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-small-onprem.html +--- + +# Deploy a small installation onprem [ece-install-small-onprem] + +The type of installation is recommended for development, test, and small-scale use cases. You need: + +* 3 hosts with 128 GB RAM +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-3.png +:alt: A small baseline installation with three hosts across three availability zones +::: + + +## Before you start [ece_before_you_start_4] + +* This type of installation is **not recommended for high-traffic workloads**. +* You must not use **spinning disks** with small ECE installations, as these are not supported when you run allocators and ECE management services on the same server. +* Note that the small-size ECE installation keeps the directors and coordinators roles (ECE management services) on the same hosts as your allocators and proxies. + +**Check the recommended JVM Heap sizes** + +| Service | JVM Heap Size (Xms and Xmx) | +| --- | --- | +| `runner` | 1 GB | +| `allocator` | 4 GB | +| `zookeeper` | 4 GB | +| `director` | 1 GB | +| `constructor` | 4 GB | +| `admin-console` | 4 GB | + +::::{warning} +For production environments, you must define the memory settings for each role, except for the `proxy` role, as starting from ECE 2.4 the JVM proxy was replaced with a Golang-based proxy. If you don’t set any memory setting, the default values are used, which are inadequate for production environments and can lead to performance or stability issues. +:::: + + + +## Installation steps [ece_installation_steps_4] + +1. Install Elastic Cloud Enterprise on the first host to start a new installation with your first availability zone. This first host holds all roles to help bootstrap the rest of the installation. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --availability-zone MY_ZONE-1 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"4G","xmx":"4G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"4G","xmx":"4G"}}' + ``` + + After the installation completes, copy down the coordinator host IP address, user credentials, and roles token information. Keep this information safe. + +2. Generate a new roles token that persists for one hour on the first host, so that other hosts can join your installation with the right role permissions in the next step (referred to as `MY_TOKEN`). The new token needs to enable all host roles, which none of the tokens automatically generated by the installation on the first host provide. + + ```sh + curl -k -H 'Content-Type: application/json' -u admin:PASSWORD https://localhost:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": false, "roles": ["director", "coordinator", "proxy", "allocator"] }' + ``` + +3. Install Elastic Cloud Enterprise on a second and third host, placing them into a second and a third availability zone, and assign them the same roles and memory settings as the first host. Make sure you include the coordinator host IP information from step 1 and the new roles token from step 2. + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy,allocator" --availability-zone MY_ZONE-2 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"4G","xmx":"4G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"4G","xmx":"4G"}}' + ``` + + ```sh + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'MY_TOKEN' --roles "director,coordinator,proxy,allocator" --availability-zone MY_ZONE-3 --memory-settings '{"runner":{"xms":"1G","xmx":"1G"},"allocator":{"xms":"4G","xmx":"4G"},"zookeeper":{"xms":"4G","xmx":"4G"},"director":{"xms":"1G","xmx":"1G"},"constructor":{"xms":"4G","xmx":"4G"},"admin-console":{"xms":"4G","xmx":"4G"}}' + ``` + +4. [Change the deployment configuration for the `admin-console-elasticsearch`, `logging-and-metrics`, and `security` clusters](working-with-deployments.md) to use three availability zones and resize the nodes to use at least 4 GB of RAM. This change makes sure that the clusters used by the administration console are highly available and provisioned sufficiently. +5. [Log into the Cloud UI](log-into-cloud-ui.md) to provision your deployment. + +If necessary, you can scale and deploy a [medium installation](deploy-medium-installation-cloud.md). diff --git a/deploy-manage/deploy/cloud-enterprise/deployment-templates.md b/deploy-manage/deploy/cloud-enterprise/deployment-templates.md new file mode 100644 index 000000000..741402d04 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/deployment-templates.md @@ -0,0 +1,59 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-deployment-templates.html +--- + +# Deployment templates [ece-deployment-templates] + +Deployment templates deploy the Elastic Stack on virtual hardware. Each template has a different blend of RAM, storage, and vCPU. This allows you to configure the Elastic Stack for different use cases, giving your deployments the resources they need. + +The components of the Elastic Stack that we support as part of a deployment are called *instances* and include: + +* Elasticsearch data tiers and master nodes +* Machine Learning (ML) nodes +* Kibana instances +* APM and Fleet instances +* Enterprise Search instances + +Elastic Cloud Enterprise comes with some deployment templates already built in, but you can [create new deployment templates](ece-configuring-ece-create-templates.md) to address a particular use case you might have. To make the most out of your hardware, we also recommend that you [configure deployment templates](configure-deployment-templates.md), so that ECE knows where to deploy components of the Elastic Stack. + +The deployment templates available are: + +* **Default template** + + A template to get you started and for backwards compatibility with existing deployments. + + The default template is suitable for search and general all-purpose workloads that don’t require more specialized resources. + + Existing deployments that were created in an ECE version before 2.0 are switched to this template automatically, if you edit their deployment configuration. The template is fully backwards compatible and enables you to add Elastic Stack features such as machine learning and dedicated master nodes to existing deployments. + + ::::{tip} + To use this template effectively, you must [tag your allocators](ece-configuring-ece-tag-allocators.md) and [edit the default instance configurations](ece-configuring-ece-instance-configurations-edit.md), so that ECE knows where to host the Elastic Stack products that are part of your deployment. + :::: + +* **Cross-cluster search template** + + This template manages remote connections for running Elasticsearch queries across multiple deployments and indices. These federated searches make it possible to break up large deployments into smaller, more resilient Elasticsearch clusters. You can organize deployments by departments or projects for example, but still have the ability to aggregate query results and get visibility into your Elastic Cloud Enterprise infrastructure. You can add remote connections either when you create your deployment or when you customize it. To know more about cross-cluster search, check [Enable cross-cluster search](https://www.elastic.co/guide/en/cloud/current/ec-enable-ccs.html). + +* **Elastic Security template** + + Use this template to prevent, collect, detect, and respond to threats for unified protection across your infrastructure. Check the [**Elastic Security**](../../../solutions/security.md) documentation for more information. + +* **Elastic Enterprise Search template** + + Default deployment template for Elastic Enterprise Search. Check the [**Enterprise Search**](https://www.elastic.co/guide/en/enterprise-search/current/index.html) documentation for more information. + +* **Elastic Observability template** + + This template allows you to consolidate your logs, metrics, application traces, and system availability with purpose-built UIs. Check the [**Elastic Observability**](../../../solutions/observability/get-started/what-is-elastic-observability.md) documentation for more information. + + + +## Instance configurations [ece-getting-started-instance-configurations] + +For instances to run well when they are used in your Elastic Cloud Enterprise deployment, they need the right hardware that supports their intended purpose. For that, Elastic Cloud Enterprise uses *instance configurations*. Instance configurations match the Elastic Stack components to allocators for deployment, and indicate how memory and storage resources get sized relative to each other, and what sizes are available. For example: If you have a logging use case that needs lots of storage space, you probably want your instance configuration to use at least some storage with large spindle drives rather than fast but more expensive SSD storage. + +To determine where ECE should place specific components of the Elastic Stack for deployment, instance configurations match suitable allocators by filtering for tags with queries. You can edit instance configurations to change what allocators get matched by the queries, which in turn changes what components of the Elastic Stack get hosted on matching allocators when creating or changing a deployment. + +Elastic Cloud Enterprise comes with a number of [default instance configurations](ece-configuring-ece-instance-configurations-default.md) built in, but just like new templates, you can [create instance configurations](ece-configuring-ece-instance-configurations-create.md) if you need additional ones. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-architecture.md b/deploy-manage/deploy/cloud-enterprise/ece-architecture.md new file mode 100644 index 000000000..6aa1d3256 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-architecture.md @@ -0,0 +1,67 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-architecture.html +--- + +# Service-oriented architecture [ece-architecture] + +Elastic Cloud Enterprise has a service-oriented architecture that lets you: + +* Scale each service separately, with different reliability and performance requirements. +* Access services through the API. +* Deploy each service independently in its own Docker container. + +:::{image} ../../../images/cloud-enterprise-ece-architecture.png +:alt: Elastic Cloud Enterprise high level architecture +::: + + +## Control plane [ece_control_plane] + +The *control plane* of ECE include the following management services: + +**ZooKeeper** + +* [ZooKeeper](http://zookeeper.apache.org/) is a distributed, strongly consistent data store. +* Holds essential information for ECE components: Proxy routing tables, memory capacity advertised by the allocators, changes committed through Admin Console, and so on. +* Acts as a message bus for communication between the services. +* Talks to ECE components using STunnel. +* Stores the state of the ECE installation and the state of all deployments running in ECE. + +**Director** + +* Manages the ZK data store and signs the CSRs (certificate signing requests) for internal clients that want to communicate with ZooKeeper. +* Maintains the stunnels used by ZooKeeper for communication and establishes quorum when new ZooKeeper nodes are created. + +**Constructor** + +* Works like a scheduler that monitors requests from the Admin console. +* Determines what needs to be changed, and writes the changes to ZooKeeper nodes monitored by the allocators. +* Assigns cluster nodes to allocators. +* Maximizes the utilization of underlying allocators to reduce the need to spin up extra hardware for new deployments. +* Places cluster nodes and instances within different availability zones to ensure that the deployment can survive any downtime of a whole zone. You can designate these availability zones when you install ECE. + +**Cloud UI and API** + +Provide web and API access for administrators to manage and monitor the ECE installation. + + +## Proxies [ece_proxies] + +* Handle user requests, mapping deployment IDs that are passed in request URLs for the container to the actual Elasticsearch cluster nodes and other instances. The association of deployment IDs to a container is stored in ZooKeeper, cached by the proxies. In the event of ZooKeeper downtime, the platform can still service the requests to existing deployments by using the cache. +* Keep track of the state and availability of zones, if you have a highly available Elasticsearch cluster. If one of the zones goes down, the proxy will not route any requests there. +* Help with no-downtime scaling and upgrades. Before performing an upgrade, a snapshot is taken, and data is migrated to the new nodes. When the migration is complete, a proxy switches the traffic to the new nodes and disconnects the old ones. +* Multiple proxies are usually configured behind a load balancer to ensure that the system remains available. + + +## Allocators [ece-architecture-allocators] + +* Run on all the machines that host Elasticsearch nodes and Kibana instances. +* Control the lifecycle of cluster nodes by: + + * Creating new containers and starting Elasticsearch nodes when requested + * Restarting a node if it becomes unresponsive + * Removing a node if it is no longer needed + +* Advertise the memory capacity of the underlying host machine to ZooKeeper so that the Constructor can make an informed decision on where to deploy. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-ce-add-support-for-integrations-server.md b/deploy-manage/deploy/cloud-enterprise/ece-ce-add-support-for-integrations-server.md new file mode 100644 index 000000000..a58d20acd --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-ce-add-support-for-integrations-server.md @@ -0,0 +1,94 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-ce-add-support-for-integrations-server.html +--- + +# Updating custom templates to support Integrations Server [ece-ce-add-support-for-integrations-server] + +Custom deployment templates should be updated in order to support Integrations Server. While system-owned deployment templates are updated automatically during the ECE upgrade process, user-created deployment templates require a manual update. + +To manually update your custom deployment templates to support Integrations Server: + +1. Obtain a list of all existing deployment templates by sending the following `GET` request, and take note of the `id` of the template you wish to update. + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://${COORDINATOR_HOST}:12443/api/v1/deployments/templates?region=ece-region + ``` + +2. Copy the template you’d like to update and add an `integrations_server` entry under the `deployment_template.resources` section of the JSON. The result should look like the following: + + ```sh + "integrations_server" : [ + { + "ref_id" : "integrations_server-ref-id", + "elasticsearch_cluster_ref_id" : "main-elasticsearch", + "region" : "ece-region", + "plan" : { + "cluster_topology" : [ + { + "instance_configuration_id" : "integrations.server", + "size" : { + "value" : 512, + "resource" : "memory" + }, + "zone_count" : 1 + } + ], + "integrations_server" : { + + } + } + } + ] + ``` + + +Send a `PUT` request with the updated template in the payload to replace the original template with the new one. Remember that: + +* The following request is just an example; other resources in the request payload should remain unchanged (they have been truncated in the example). +* You need to replace `{{template_id}}` in the URL with the `id` that you collected in Step 1. + +Refer to [set deployment template API](https://www.elastic.co/guide/en/cloud-enterprise/current/set-deployment-template-v2.html) for more details. + +::::{dropdown} Update template API request example +```sh +curl -k -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://$COORDINATOR_HOST:12443/api/v1/deployments/templates/{template_id}?region=ece-region -H 'content-type: application/json' -d ' +{ + "name": "ECE Custom Template", + "description": "ECE custom template with added Integrations Server", + "deployment_template": { + "resources": { + "elasticsearch": [...], + "kibana": [...], + "apm": [...], + "enterprise_search": [...], + "integrations_server": [ + { + "ref_id": "integrations_server-ref-id", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "integrations.server", + "size": { + "value": 512, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "integrations_server": {} + } + ] + } + }, + "system_owned": false +}' +``` + +:::: + + +After the template is updated, you can start [creating new deployments](create-deployment.md). + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configure-templates-index-management.md b/deploy-manage/deploy/cloud-enterprise/ece-configure-templates-index-management.md new file mode 100644 index 000000000..74563c918 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configure-templates-index-management.md @@ -0,0 +1,57 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-templates-index-management.html +--- + +# Configure index management for templates [ece-configure-templates-index-management] + +If you create a deployment template that includes more than one data configuration, you must also specify how Elastic Cloud Enterprise should manage indices for your users when they create their deployments. For time-series use cases such as logging, metrics, and APM, providing a template that enables index management ensures that data is being stored in the most cost-effective way possible as it ages. + +In a template that creates a hot-warm architecture, you can use index curation to specify where new indices are created initially and where they are moved to later on. However, index curation has been deprecated in favor of index lifecycle management, which offers additional features and more fine-grained control over indices. For instance, using ILM you can enable automatic roll-over of index aliases to new indices when existing indices become too large or too old, and you can set indices to be deleted when they are no longer useful. + + +## Before you begin [ece_before_you_begin_4] + +Configuring index management is part of the larger task of [creating deployment templates](ece-configuring-ece-create-templates.md) or editing them. The choices you make here determine which index management methods are available to your users when they create deployments. + +You should configure all index management methods that you want your users to be able to choose from when they create their deployments from your template. You can configure index curation, index lifecycle management, or both. If you are not sure which index management methods to configure, take a look at how your users are asked to [configure index management](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-index-management.html) when they customize their deployments. + + +## Steps [ece_steps_2] + +To configure index management when you create a deployment template: + +1. On the **Index Management** page, configure the index curation methods that you want to be available when your users create deployments: + + Index lifecycle management + : Uses the ILM feature of the Elastic Stack that provides an integrated and streamlined way to manage time-based data, making it easier to follow best practices for managing your indices. Compared to index curation, ILM gives you more fine-grained control over the lifecycle of each index. + + To configure index lifecycle management: + + 1. Specify the node attributes for your data configurations. + + Node attributes are simple key-value pairs, such as `node_type: hot`, `node_type: warm`, and `node_type: cold`. These node attributes add defining metadata attributes to each data configuration in your template that tell your users what they can be used for. What you define here should help guide your users when they set up their index lifecycle management policy in Kibana, such as a hot-warm policy. + + 1. Specify an attribute key-value pair in the **Node attributes** field, with the key and value separated by a colon. + 2. Repeat the previous step until you have added all the node attributes that you want to be available to your users when they create an index lifecycle policy later on. + + + Index curation + : Creates new indices on hot nodes first and moves them to warm nodes later on, based on the data views (formerly *index patterns*) you specify. Also manages replica counts for you, so that all shards of an index can fit on the right data nodes. Compared to index lifecycle management, index curation for time-based indices supports only one action, to move indices from nodes on one data configuration to another, but it is more straightforward to set up initially and all setup can be done directly from the Cloud UI. + + If your user need to delete indices once they are no longer useful to them, they can run [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/current/index.html) on-premise to manage indices for Elasticsearch clusters hosted on Elastic Cloud Enterprise. + + To configure index curation: + + 1. Select the hot data configuration where new indices get created initially. + 2. Select the warm nodes where older indices get moved to later on when they get curated. + 3. Specify which indices get curated by including at least one data view. + + By default, the pattern is `*`, which means that all indices get curated. For logging use cases, you could specify to curate only the `logstash-*`, `metricbeat-*`, or `filebeat-*` data views, for example. + + 4. Specify the time interval after which indices get curated. + +2. Select **Next**. + +After you have completed these steps, continue with [creating your deployment template](ece-configuring-ece-create-templates.md#ece-configuring-ece-create-templates-ui). + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-configure-system-templates.md b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-configure-system-templates.md new file mode 100644 index 000000000..1cc439b81 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-configure-system-templates.md @@ -0,0 +1,328 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-configure-system-templates.html +--- + +# Configure system deployment templates [ece-configuring-ece-configure-system-templates] + +While you can create new deployment templates for some use cases, if the system templates generally suit your needs but just require minor changes, you may choose to configure or modify the system templates. + +For example, you want to use autoscaling with the system templates, but want to modify some of the default values for autoscaling in those templates. You might want to enable autoscaling by default for new deployments, or adjust the default value of the autoscaling maximum for the hot tier. + +Note that you cannot edit system templates through the UI; they may only be configured through the API. + + +## Configure system deployment templates through the RESTful API [ece_configure_system_deployment_templates_through_the_restful_api] + +::::{note} +The API user must have the `Platform admin` role in order to configure system templates. +:::: + + +1. Obtain the existing system deployment template you wish to modify. Note the `id` of the system deployment template as you will include this value in the API call to edit the template. + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/templates?region=ece-region + ``` + +2. Edit the JSON of the system deployment template you wish to modify. +3. Make the API call to modify the deployment template. Note that the last path segment in the URL is the `id` of the system template you wish to modify. Check [set deployment template API](https://www.elastic.co/guide/en/cloud-enterprise/current/set-deployment-template-v2.html) for more detail. + + The following example modifies the Default system deployment template (that, is the system template with `id` value of `default`), setting the default value of `autoscaling_enabled` to `true` and the default autoscaling maximum size of the hot tier to 4,194,304MB (64GB * 64 nodes). + + ```sh + curl -k -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://$COORDINATOR_HOST:12443/api/v1/deployments/templates/default?region=ece-region -H 'content-type: application/json' -d '{ + { + "name" : "Default", + "description" : "Default deployment template for clusters", + "deployment_template" : { + "resources" : { + "elasticsearch" : [ + { + "ref_id" : "es-ref-id", + "region" : "ece-region", + "plan" : { + "cluster_topology" : [ + { + "id" : "hot_content", + "node_type" : { + "master" : true, + "data" : true, + "ingest" : true + }, + "node_roles" : [ + "master", + "ingest", + "remote_cluster_client", + "data_hot", + "transform", + "data_content" + ], + "zone_count" : 1, + "elasticsearch" : { + "node_attributes" : { + "data" : "hot" + } + }, + "instance_configuration_id" : "data.default", + "size" : { + "value" : 4096, + "resource" : "memory" + }, + "autoscaling_max" : { + "value" : 4194304, + "resource" : "memory" + }, + "topology_element_control" : { + "min" : { + "value" : 1024, + "resource" : "memory" + } + } + }, + { + "id" : "warm", + "node_type" : { + "master" : false, + "data" : true, + "ingest" : false + }, + "node_roles" : [ + "data_warm", + "remote_cluster_client" + ], + "zone_count" : 1, + "elasticsearch" : { + "node_attributes" : { + "data" : "warm" + } + }, + "instance_configuration_id" : "data.highstorage", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "autoscaling_max" : { + "value" : 2097152, + "resource" : "memory" + }, + "topology_element_control" : { + "min" : { + "value" : 0, + "resource" : "memory" + } + } + }, + { + "id" : "cold", + "node_type" : { + "master" : false, + "data" : true, + "ingest" : false + }, + "node_roles" : [ + "data_cold", + "remote_cluster_client" + ], + "zone_count" : 1, + "elasticsearch" : { + "node_attributes" : { + "data" : "cold" + } + }, + "instance_configuration_id" : "data.highstorage", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "autoscaling_max" : { + "value" : 2097152, + "resource" : "memory" + }, + "topology_element_control" : { + "min" : { + "value" : 0, + "resource" : "memory" + } + } + }, + { + "id" : "coordinating", + "node_type" : { + "master" : false, + "data" : false, + "ingest" : true + }, + "node_roles" : [ + "ingest", + "remote_cluster_client" + ], + "zone_count" : 1, + "instance_configuration_id" : "coordinating", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "topology_element_control" : { + "min" : { + "value" : 0, + "resource" : "memory" + } + } + }, + { + "id" : "master", + "node_type" : { + "master" : true, + "data" : false, + "ingest" : false + }, + "node_roles" : [ + "master", + "remote_cluster_client" + ], + "zone_count" : 1, + "instance_configuration_id" : "master", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "topology_element_control" : { + "min" : { + "value" : 0, + "resource" : "memory" + } + } + }, + { + "id" : "ml", + "node_type" : { + "master" : false, + "data" : false, + "ingest" : false, + "ml" : true + }, + "node_roles" : [ + "ml", + "remote_cluster_client" + ], + "zone_count" : 1, + "instance_configuration_id" : "ml", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "autoscaling_min" : { + "value" : 0, + "resource" : "memory" + }, + "autoscaling_max" : { + "value" : 2097152, + "resource" : "memory" + }, + "topology_element_control" : { + "min" : { + "value" : 0, + "resource" : "memory" + } + } + } + ], + "elasticsearch" : { + + }, + "autoscaling_enabled" : true + }, + "settings" : { + "dedicated_masters_threshold" : 6 + } + } + ], + "kibana" : [ + { + "ref_id" : "kibana-ref-id", + "elasticsearch_cluster_ref_id" : "es-ref-id", + "region" : "ece-region", + "plan" : { + "zone_count" : 1, + "cluster_topology" : [ + { + "instance_configuration_id" : "kibana", + "size" : { + "value" : 1024, + "resource" : "memory" + } + } + ], + "kibana" : { + + } + } + } + ], + "apm" : [ + { + "ref_id" : "apm-ref-id", + "elasticsearch_cluster_ref_id" : "es-ref-id", + "region" : "ece-region", + "plan" : { + "cluster_topology" : [ + { + "instance_configuration_id" : "apm", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "zone_count" : 1 + } + ], + "apm" : { + + } + } + } + ], + "enterprise_search" : [ + { + "ref_id" : "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id" : "es-ref-id", + "region" : "ece-region", + "plan" : { + "cluster_topology" : [ + { + "node_type" : { + "appserver" : true, + "worker" : true, + "connector" : true + }, + "instance_configuration_id" : "enterprise.search", + "size" : { + "value" : 0, + "resource" : "memory" + }, + "zone_count" : 2 + } + ], + "enterprise_search" : { + + } + } + } + ] + } + }, + "system_owned" : true, + "metadata" : [ + { + "key" : "parent_solution", + "value" : "stack" + } + ], + "order" : 0, + "template_category_id" : "default" + }' + ``` + + +After you have edited the template, you can start [creating new deployments](create-deployment.md) with it. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-create-templates.md b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-create-templates.md new file mode 100644 index 000000000..6924741d5 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-create-templates.md @@ -0,0 +1,423 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-create-templates.html +--- + +# Create deployment templates [ece-configuring-ece-create-templates] + +Elastic Cloud Enterprise comes with some deployment templates already built in, but you can create new deployment templates to address particular use cases that you might have. + +For example: You might decide to create a new deployment template, if you have a specific search use case that requires Elasticsearch data nodes in a specific configuration that also includes machine learning for anomaly detection. If you need to create these deployments fairly frequently, you can create a deployment template once and deploy it as many times as you like. Or, create a single template for both your test and production deployments to ensure they are exactly the same. + + +## Before you begin [ece_before_you_begin_3] + +Before you start creating your own deployment templates, you should have: [tagged your allocators](ece-configuring-ece-tag-allocators.md) to tell ECE what kind of hardware you have available for Elastic Stack deployments. If the default instance configurations don’t provide what you need, you might also need to [create your own instance configurations](ece-configuring-ece-instance-configurations-create.md) first. + + +## Create deployment templates in the UI [ece-configuring-ece-create-templates-ui] + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Templates**. +3. Select **Create template**. +4. Give your template a name and include a description that reflects its intended use. +5. Select **Create template**. The **Configure instances** page opens. +6. Choose whether or not [autoscaling](../../autoscaling.md) is enabled by default for deployments created using the template. Autoscaling adjusts resources available to the deployment automatically as loads change over time. + + :::{image} ../../../images/cloud-enterprise-ece-create-template-autoscaling.png + :alt: screencapture of the "Enable autoscaling by default" switch + ::: + +7. Configure the initial settings for all of the data tiers and components that will be available in the template. A default is provided for every setting and you can adjust these as needed. For each data tier and component, you can: + + * Select which [instance configuration](ece-configuring-ece-instance-configurations-create.md) to assign to the template. This allows you to optimize the performance of your deployments by matching a machine type to a use case. A hot data and content tier, for example, is best suited to be allocated with an instance configuration having fast SSD storage, while warm and cold data tiers should be allocated with an instance configuration with larger storage but likely less performant, lower cost hardware. + + :::{image} ../../../images/cloud-enterprise-ece-create-template-instance-configuration.png + :alt: screencapture of the "Initial size per zone" dropdown box + ::: + + * Adjust the default, initial amount of memory and storage. Increasing memory and storage also improves performance by increasing the CPU resources that get assigned relative to the size of the instance, meaning that a 32 GB instance gets twice as much CPU resource as a 16 GB one. These resources are just template defaults that can be adjusted further before you create actual deployments. + + :::{image} ../../../images/cloud-enterprise-ece-create-template-initial-size.png + :alt: screencapture of the "Initial size per zone" dropdown box + ::: + + * Configure autoscaling settings for the deployment. + + :::{image} ../../../images/cloud-enterprise-ece-create-template-max-autoscaling.png + :alt: screencapture of the "Maximum autoscaling size per zone" dropdown box + ::: + + * For data nodes, autoscaling up is supported based on the amount of available storage. You can set the default initial size of the node and the default maximum size that the node can be autoscaled up to. + * For machine learning nodes, autoscaling is supported based on the expected memory requirements for machine learning jobs. You can set the default minimum size that the node can be scaled down to and the default maximum size that the node can be scaled up to. If autoscaling is not enabled for the deployment, the "minimum" value will instead be the default initial size of the machine learning node. + + The default values provided by the deployment template can be adjusted at any time. Check our [Autoscaling example](../../autoscaling/ece-autoscaling-example.md) for details about these settings. Nodes and components that currently support autoscaling are indicated by a `supports autoscaling` badge on the **Configure instances** page. + + * Add [fault tolerance](ece-ha.md) (high availability) by using more than one availability zone. + + :::{image} ../../../images/cloud-enterprise-ece-create-template-availability-zones.png + :alt: screencapture of the "Availability zones" radio buttons + ::: + + * Add user settings to configure how Elasticsearch and other components run. Check [Editing your user settings](edit-stack-settings.md) for details about what settings are available. + + :::{image} ../../../images/cloud-enterprise-ece-create-template-user-settings.png + :alt: screencapture of the "User settings" expandable section + ::: + + + If a data tier or component is not required for your particular use case, you can simply set its initial size per zone to `0`. You can enable a tier or component anytime you need it just by scaling up the size. If autoscaling is enabled, data tiers and machine learning nodes are sized up automatically when they’re needed. For example, when you configure your first machine learning job, ML nodes are enabled by the autoscaling process. Similarly, if you choose to create a cold data phase as part of your deployment’s index lifecycle management (ILM) policy, a cold data node is enabled automatically without your needing to configure it. + +8. Select **Manage indices**. +9. On this page you can [configure index management](ece-configure-templates-index-management.md) by assigning attributes to each of the data nodes in the deployment template. In Kibana, you can configure an index lifecycle management (ILM) policy, based on the node attributes, to control how data moves across the nodes in your deployment. +10. Select **Stack features**. +11. You can select a [snapshot repository](../../tools/snapshot-and-restore/cloud-enterprise.md) to be used by default for deployment backups. +12. You can choose to [enable logging and monitoring](../../monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md) by default, so that deployment logs and metrics are send to a dedicated monitoring deployment, and so that additional log types, retention options, and Kibana visualizations are available on all deployments created using this template. +13. Select **Extensions**. +14. Select any Elasticsearch extensions that you would like to be available automatically to all deployments created using the template. +15. Select **Save and create template**. + + +## Create deployment templates through the RESTful API [ece_create_deployment_templates_through_the_restful_api] + +1. Obtain the existing deployment templates to get some examples of what the required JSON looks like. You can take the JSON for one of the existing templates and modify it to create a new template, similar to what gets shown in the next step. + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/templates?region=ece-region + ``` + +2. Post the JSON for your new deployment template. + + The following example creates a deployment template that defaults to a highly available Elasticsearch cluster with 4 GB per hot node, a 16 GB machine learning node, 3 dedicated master nodes of 1 GB each, a 1 GB Kibana instance, and a 1 GB dedicated coordinating node that is tasked with handling and coordinating all incoming requests for the cluster. Elasticsearch and Kibana use the default instance configurations, but the machine learning node is based on the custom instance configuration in our previous example. + + ```sh + curl -k -X POST -H "Authorization: ApiKey $ECE_API_KEY" https://$COORDINATOR_HOST:12443/api/v1/deployments/templates?region=ece-region -H 'content-type: application/json' -d '{ + "name" : "Default", + "description" : "Default deployment template for clusters", + "deployment_template": { + "resources": { + "elasticsearch": [ + { + "ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "master": true, + "data": true, + "ingest": true + }, + "zone_count": 1, + "instance_configuration_id": "data.default", + "size": { + "value": 4096, + "resource": "memory" + }, + "node_roles": [ + "master", + "ingest", + "data_hot", + "data_content", + "remote_cluster_client", + "transform" + ], + "id": "hot_content", + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "topology_element_control": { + "min": { + "value": 1024, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 0 + }, + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "id": "warm", + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "instance_configuration_id": "data.highstorage", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 0 + }, + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "id": "cold", + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "node_type": { + "data": true, + "ingest": false, + "master": false + }, + "instance_configuration_id": "data.frozen", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 0 + }, + "node_roles": [ + "data_frozen" + ], + "id": "frozen", + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + }, + { + "node_type": { + "master": false, + "data": false, + "ingest": true + }, + "zone_count": 1, + "instance_configuration_id": "coordinating", + "size": { + "value": 1024, + "resource": "memory" + }, + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "id": "coordinating", + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "node_type": { + "master": true, + "data": false, + "ingest": false + }, + "zone_count": 3, + "instance_configuration_id": "master", + "size": { + "value": 1024, + "resource": "memory" + }, + "node_roles": [ + "master", + "remote_cluster_client" + ], + "id": "master", + "topology_element_control": { + "min": { + "value": 0, + "resource": "memory" + } + } + }, + { + "node_type": { + "master": false, + "data": false, + "ingest": false, + "ml": true + }, + "zone_count": 1, + "instance_configuration_id": "ml", + "size": { + "value": 0, + "resource": "memory" + }, + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "id": "ml", + "topology_element_control": { + "min": { + "value": 16384, + "resource": "memory" + } + }, + "autoscaling_min": { + "resource": "memory", + "value": 16384 + }, + "autoscaling_max": { + "value": 2097152, + "resource": "memory" + } + } + ], + "elasticsearch": {}, + "autoscaling_enabled": false + }, + "settings": { + "dedicated_masters_threshold": 3 + } + } + ], + "kibana": [ + { + "ref_id": "kibana-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + } + } + ], + "kibana": {} + } + } + ], + "apm": [ + { + "ref_id": "apm-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": {} + } + } + ], + "enterprise_search": [ + { + "ref_id": "enterprise_search-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "node_type": { + "appserver": true, + "connector": true, + "worker": true + }, + "instance_configuration_id": "enterprise.search", + "size": { + "value": 0, + "resource": "memory" + }, + "zone_count": 2 + } + ], + "enterprise_search": {} + } + } + ] + } + } + }' + ``` + + +::::{note} +When specifying `node_roles` in the Elasticsearch plan of the deployment template, the template must contain all resource types and all Elasticsearch tiers. The deployment template must contain exactly one entry for each resource type. It must have one Elasticsearch, one Kibana, one APM, and one Enterprise Search. On top of that, it must also include all supported Elasticsearch tiers in the Elasticsearch plan. The supported tiers are identified by the IDs `hot_content`, `warm`, `cold`, `frozen`, `master`, `coordinating` and `ml`. +:::: + + +::::{note} +Deployment templates without `node_roles` or `id` should only contain hot and warm data tiers, with different `instance_configuration_id`s. Node roles are highly recommended when using the cold tier and are mandatory for the frozen tier. +:::: + + +After you have saved your new template, you can start [creating new deployments](create-deployment.md) with it. + +::::{note} +To support deployment templates that are versioned due to a constraint on architecture that is only supported by newer versions of ECE, for example ARM instances, you must add additional configuration: + +* The `template_category_id` for both template versions must be identical. +* The `min_version` attribute must be set. + +These attributes are set at the same level as `name` and `description`. The UI selects the template with the highest matching `min_version` that is returned by the API. + +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-create.md b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-create.md new file mode 100644 index 000000000..8b18432af --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-create.md @@ -0,0 +1,140 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-instance-configurations-create.html +--- + +# Create instance configurations [ece-configuring-ece-instance-configurations-create] + +If you plan to [create your own templates](ece-configuring-ece-create-templates.md) and the default instance configurations that ship with ECE don’t quite suit your purpose, it’s generally easier and safer to create your own custom instance configurations first. Instance configurations match components of the Elastic Stack to allocators and tailor how memory and storage resources get sized relative to each other, and what sizes are available. + + +## Before you begin [ece_before_you_begin_2] + +Before you start creating your own instance configurations, you should have [tagged your allocators](ece-configuring-ece-tag-allocators.md) to tell ECE what kind of hardware you have available for Elastic Stack deployments. If you do not tag your allocators, templates that use these instance configurations will deploy wherever there is space rather than on specific allocators. + + +## Create an instance configuration in the UI [ece_create_an_instance_configuration_in_the_ui] + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Templates**. +3. Open the **Instance configurations** tab and select **Create instance configuration**. +4. In the **Input** section, construct a query that filters on specific allocator tags. + + ::::{tip} + An *outer clause* ANDs or ORs your main filtering criteria. You use outer clauses to find the allocators that you tagged earlier. An *inner clause* modifies an outer clause and let’s you refine your filtering criteria further. If you are unsure how the process works, try searching on some of the allocator tags that you added and check how the query results change. + :::: + + + 1. Select **And** or **Or** to add a first outer clause. + 2. Enter a key-value pair in the **Key** and **Value** fields that you previously [tagged your allocators](ece-configuring-ece-tag-allocators.md) with. + + For example: If you tagged your allocators with this tag, enter `SSD` and `true` or enter whatever tag you are using for a similar purpose. + + 3. Check the list of allocators that get matched by your query: + + * If you are satisfied that your query matches all the allocators where the component(s) of the Elastic Stack can be deployed, move on to the next step. + * If you need to refine your query further, continue to adjust your outer or inner clauses. If you are unsure what to do, we recommend keeping your initial query simple. You can always refine the query later on by re-editing the instance configuration. + +5. Select **Instance types**. +6. Pick the products and features of the Elastic Stack that can get deployed on the allocators you identified in the previous step. For products such as Elasticsearch, you can also select some additional options, such as the specific node types that can be deployed. + + Note that not all combinations of Elasticsearch node types are available. You can create either a general purpose Elasticsearch node that includes all three of data, master, and coordinating, or a dedicated node that includes any one of these types. Machine learning is also available as a separate instance type. + +7. Select **Sizes**. +8. Adjust how memory and storage resources get sized relative to each other and set the available sizes, including the default size. Size your instance configuration so that it will use the available memory and storage on your allocators efficiently, without leaving hardware resources unused. Keep in mind that very small sizes might not provide adequate performance for some use cases. + + The size of an instance configuration also determines performance, as CPU resources get sized in lockstep. For example: A 32 GB instance configuration receives double the CPU resources of a 16 GB one. + +9. Select **Name**. +10. Give your instance configuration a name and include a description that reflects its intended use. +11. Select **Save and create configuration**. + + +## Create an instance configuration through the RESTful API [ece_create_an_instance_configuration_through_the_restful_api] + +1. Obtain the existing instance configurations to get some examples of what the required JSON looks like. You can take the JSON for one of the existing configurations and modify it to create a new instance configuration, similar to what gets shown in the next step. + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/platform/configuration/instances + ``` + +2. Post the JSON for your new instance configuration. + + The following examples creates an instance configuration for machine learning with size increments that start at the recommended minimum of 16 GB of memory. To make sure that machine learning nodes get deployed only on the right allocators, this instance configuration also filters for [allocator tags from our earlier example](ece-configuring-ece-tag-allocators.md) to match only allocators with high CPU resources and SSD storage. + + ```sh + curl -k -X POST -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/platform/configuration/instances -H 'content-type: application/json' -d '{ + "name": "Machine Learning Only", + "description": "Custom machine learning instance configuration", + "storage_multiplier": 32.0, + "discrete_sizes": { + "sizes": [16384, 32768, 65536], + "default_size": 16384, + "resource": "memory" + }, + "allocator_filter": { + "bool": { + "must": [{ + "bool": { + "must": [{ + "nested": { + "query": { + "bool": { + "must": [{ + "term": { + "metadata.key": { + "value": "SSD" + } + } + }, { + "term": { + "metadata.value.keyword": { + "value": "true" + } + } + }] + } + }, + "path": "metadata" + } + }] + } + }, { + "bool": { + "must": [{ + "nested": { + "query": { + "bool": { + "must": [{ + "term": { + "metadata.key": { + "value": "highCPU" + } + } + }, { + "term": { + "metadata.value.keyword": { + "value": "true" + } + } + }] + } + }, + "path": "metadata" + } + }] + } + }] + } + }, + "node_types": ["ml"], <1> + "instance_type": "elasticsearch" + }' + ``` + + 1. Note, that not all combinations of Elasticsearch node types are allowed here. You can create either a general purpose Elasticsearch node that includes all three of `data`, `master`, and `ingest`, or a dedicated node, that includes any one of these types or `ml`. + + + After you have created your new instance configuration, you can use it when you [create new deployment templates](ece-configuring-ece-create-templates.md) or when you edit existing ones. + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-default.md b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-default.md new file mode 100644 index 000000000..3576abd18 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-default.md @@ -0,0 +1,24 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-instance-configurations-default.html +--- + +# Default instance configurations [ece-configuring-ece-instance-configurations-default] + +Elastic Cloud Enterprise ships with a number of default instance configurations: + +| Instance configuration | Instance types / node types | Default size | Memory sizes | Memory to storage multiplier | +| --- | --- | --- | --- | --- | +| `apm` | APM | 512 MB | 512, 1, 2, 4, 8 | 4 | +| `appsearch` | Application server, Worker | 4 GB | 2, 4, 8 | 2 | +| `ccs.default` | Data, Master, Coordinating | 1 GB | 1, 2, 4, 8, 16, 32, 64 | 4 | +| `coordinating` | Coordinating | 1 GB | 1, 2, 4, 8 | 2 | +| `data.default` | Data, Master, Coordinating | 4 GB | 1, 2, 4, 8, 16, 32, 64 | 32 | +| `data.frozen` | Data | 4 GB | 4, 8, 16, 32, 64 | 80 | +| `data.highstorage` | Data, Master, Coordinating | 2 GB | 1, 2, 4, 8, 16, 32, 64 | 64 | +| `enterprise.search` | Application server, Connector, Worker | 4 GB | 2, 4, 8 | 2 | +| `integrations.server` | Integrations Server | 512 MB | 512, 1, 2, 4, 8 | 4 | +| `kibana` | Kibana | 1 GB | 1, 2, 4, 8 | 4 | +| `master` | Master | 1 GB | 1, 2, 4, 8, 16, 32, 64 | 4 | +| `ml` | Machine Learning | 1 GB | 1, 2, 4, 8, 16, 32, 64 | 4 | + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-edit.md b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-edit.md new file mode 100644 index 000000000..85fc9167f --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-edit.md @@ -0,0 +1,60 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-instance-configurations-edit.html +--- + +# Edit instance configurations [ece-configuring-ece-instance-configurations-edit] + +Instance configurations enable components of the Elastic Stack to be matched to allocators for a specific use case. The matching is accomplished by defining a query that filters possible allocators based on their tags. For existing instance configurations, you can edit the query to change how allocators get matched, which in turn changes what components of the Elastic Stack get hosted on the matching allocators when creating or changing a deployment. + +You might need to edit instance configurations under the following circumstances: + +* After you upgrade to or install Elastic Cloud Enterprise 2.0 or later and [have tagged your allocators](ece-configuring-ece-tag-allocators.md), to indicate how you want to use these tagged allocators. +* If tagged allocators in your ECE installation are not being used as expected when you create or change deployments. Editing an instance configuration affects all deployments that depend on it, and tagged allocators that do not get matched by an instance configuration will not be used. If this happens, you can edit your instance configurations to create less restrictive queries. + +::::{tip} +If you edit instance configurations, so that they match fewer allocators, instances of the Elastic Stack that were previously matched to those allocators might be relocated. Keep this in mind when making queries more restrictive. +:::: + + + +## Steps [ece_steps] + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Templates**. +3. Select the **Instance configurations** tab to check the default instance configurations that ship with ECE. +4. Choose one of the instance configurations and select **Edit instance configuration**. + + For example: Select to edit the `data.default` default instance configuration, so that you can specify where Elasticsearch data nodes for incoming data should be deployed. In a hot-warm architecture, this will determine where your hot data gets sent to. + +5. In the **Input** section, construct a query that filters on specific allocator tags. + + The following steps assume that no query exists, as is the case when you edit the default instance configurations for the first time after installing ECE version 2.0 or later. You can also edit an existing query by modifying the inner and outer clauses. + + ::::{tip} + An *outer clause* ANDs or ORs your main filtering criteria. You use outer clauses to find the allocators that you tagged earlier. An *inner clause* modifies an outer clause and let’s you refine your filtering criteria further. If you are unsure how the process works, try searching on some of the allocator tags that you added and check how the query results change. If you are editing the `data.default` default instance configuration, you want your query to return all allocators on which Elasticsearch data nodes for incoming data can be placed. + :::: + + + 1. Select **And** or **Or** to add a first outer clause. + 2. Enter a key-value pair in the **Key** and **Value** fields that you previously [tagged your allocators](ece-configuring-ece-tag-allocators.md) with. + + For example: Enter `SSD` and `true`, if you tagged your allocators with this tag, or enter whatever tag you are using to identify allocators that can host Elasticsearch data nodes for incoming data. + + :::{image} ../../../images/cloud-enterprise-ece-query-ui.png + :alt: Creating a query that filters on allocator tags + ::: + + 3. Check the list of allocators that get matched by your query: + + * If you are satisfied that your query matches all the allocators where the component(s) of the Elastic Stack can be deployed, move on to the next step. For the `data.default` default instance configuration, this means all the allocators where Elasticsearch data nodes for incoming data should be deployed, for example. + * If you need to refine your query further, continue to adjust your outer or inner clauses. If you are unsure what to do, keep your initial query simple. You can always refine the query later on by re-editing the instance configuration. + +6. Select **Save changes**. +7. If you are configuring the default instance configurations for the hot-warm template: Repeat steps 4 through 6 for the `data.highstorage`, `master`, `coordinating`, `kibana`, and `ml` instance configurations. + + For example: For the `data.highstorage` instance configuration, your query should filter for allocators that use spindle-based storage. If you are using our [sample tags](ece-configuring-ece-tag-allocators.md#allocator-sample-tags), you could filter on either `SSD: false` or `highstorage: true`, depending on which tag you decided to use. For the `master` and `kibana` configurations, some multi-purpose hardware might work well. The `ml` instance configuration can benefit from hardware that provides higher CPU (`highCPU: true` in our sample tags). + + +After you have saved your changes, the updated instance configurations will be used whenever you create or edit deployments that use deployment templates based on these instance configurations. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-tag-allocators.md b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-tag-allocators.md new file mode 100644 index 000000000..0ce8fc9a6 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-configuring-ece-tag-allocators.md @@ -0,0 +1,132 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-ece-tag-allocators.html +--- + +# Tag your allocators [ece-configuring-ece-tag-allocators] + +You tag allocators to indicate what kind of hardware you have available. These tags matter, because they enable instance configurations to filter on allocators where components of the Elastic Stack should get deployed. Without tags, instance configurations will allow Elastic Stack components to get deployed wherever there is space on allocators. With tags, instance configurations can filter out those allocators that are best suited to deploy specific components of the Elastic Stack and make sure they get deployed there. + +Allocator tags are a simple way of characterizing the hardware resources that you have in your ECE installation, such as: + +* CPU (compute) +* Memory +* Storage +* I/O + +You should tag your allocators under the following circumstances: + +* After you upgrade to or install Elastic Cloud Enterprise 2.0 or later, to characterize what kind of hardware you have available in your installation. +* Before you create your own instance configurations and your own deployment templates, to indicate what hardware resources you can work with. +* After you add new allocators to your installation, to indicate what kind of hardware resources they provide. + +::::{tip} +You can also delete tags, if you have no more use for them. Keep in mind that removing tags from allocators can in turn affect what allocators get matched. Removing a tag might prompt ECE to move instances of the Elastic Stack to other allocators. +:::: + + + +## Before You Begin [ece_before_you_begin] + +Your tags should characterize what kind of hardware you have available. As you start developing your own tags, keep in mind that simpler is often better and that the tags you use will likely evolve over time. The main purpose of tagging is to go from *this is an allocator*, which doesn’t tell you anything about the allocator’s hardware resources, to *this is an allocator with better CPU resources* or *this allocator provides a large amount of spindle-based storage*. + +$$$allocator-sample-tags$$$Tags are simple key-value pairs. A small sampling of tags that you could use include: + +`SSD: true`, `SSD: false`, `highstorage: true` +: Indicates if you have fast SSD storage for incoming data (`SSD: true`) or spindle-based storage that can store larger volumes of less frequently queried data (`SSD: false` or `highstorage: true`). + +`highCPU: true` +: Indicates allocators that can run CPU-intensive workloads faster than others. + +`instanceFamily: i3`, `instanceFamily: m5` +: Indicates the host type, used extensively on our hosted Elasticsearch Service to identify hosts with specific hardware characteristics. If you run your own hardware on-premise and have standardized on several specific host configurations, you could use similar tags. If you are deploying ECE on another cloud platform, you could use the instance type or machine type names from your provider. + +Avoid tags that describe a particular use case or an Elastic Stack component you plan to run on these allocators. Examples of tags to avoid include `elasticsearch: false` or `kibana: true`. You should define the intended use at the level of instance configurations instead and tag your allocators only to describe hardware characteristics. + +::::{tip} +If you have an allocator that meets several criteria, such as an allocator with multi-purpose hardware, consider assigning it a single tag that identifies its multipurpose view, such as the `instanceFamily: i3` example mentioned earlier. While it is not wrong to assign multiple tags to an allocator, filtering on the allocator when you create or edit instance configurations will be simpler with a single tag. +:::: + + + +## Tag allocators in the Cloud UI [ece_tag_allocators_in_the_cloud_ui] + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Hosts**. +3. Select one of the hosts, and under the **Allocator** tab locate the **Allocator tags** section. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +4. Enter values into the **Key** and **Value** fields, and then select **Add tag**. For example: You could add `SSD: true` and `highCPU: true` tags from our [example tags](#allocator-sample-tags) if your allocator meets these criteria. + + :::{image} ../../../images/cloud-enterprise-ece-tagging-ui.png + :alt: Adding key-value pairs as an allocator tags + ::: + +5. Repeat the previous step until you have added all of the tags that you want to use to characterize the hardware of this allocator. +6. Repeat the previous steps for your other allocators until you have tagged all of them. + + +## Tag an allocator through the RESTful API [ece_tag_an_allocator_through_the_restful_api] + +1. Get a list of the allocators in your ECE installation: + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/platform/infrastructure/allocators + ``` + + ::::{note} + The user must have sufficient privileges, such as the `admin` user. + :::: + +2. $$$check-allocator-tags$$$Check what tags have already been assigned to your allocators. In a new or newly upgraded ECE installation, this command returns `[]`, which means that you have not assigned any tags, yet. + + ```sh + curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/platform/infrastructure/allocators/ALLOCATOR_ID/metadata + ``` + + `ALLOCATOR_ID` + : The value of the `allocator_id` field for one of your allocators as returned by the `/api/v1/platform/infrastructure/allocators` API endpoint. + + ::::{tip} + The examples in this section all use HTTPS over port 12443 and run against a host that holds the coordinator role. Using HTTPS requires that you have [a TLS certificate already installed](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md). For testing purposes only, you can specify the `-k` option to turn off certificate verification, as shown in our examples, or use HTTP over port 12400 until you get your TLS certificate sorted out. + :::: + +3. Tag an allocator by assigning it the tags that you might need. + + * Example: To assign a single `highCPU: true` tag to an allocator: + + ```sh + curl -k -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/platform/infrastructure/allocators/ALLOCATOR_ID/metadata/highCPU -H 'content-type: application/json' -d '{ "value": "true" }' + [{ + "key": "highCPU", + "value": "true" + }] + ``` + + After the API call completes successfully, ECE returns JSON output to show that the operation was successful. + + * Example: To assign multiple tags to an allocator with a single command: + + ```sh + curl -k -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/platform/infrastructure/allocators/ALLOCATOR_ID/metadata -H 'content-type: application/json' -d ' + { + "items": [ + { + "key": "highCPU", + "value": "true" + }, + { + "key": "SSD", + "value": "true" + } + ] + }' + ``` + + ::::{tip} + When you assign multiple tags to an allocator as shown, any tags you assigned previously get replaced. That is, existing tags are not preserved and they do not get merged with new tags. If in doubt, <<[check-allocator-tag,check which tags have already been assigned>> and make sure you include those tags that you want to keep along with new tags. + :::: + +4. Repeat the previous step for your other allocators until you have tagged all of them. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-containerization.md b/deploy-manage/deploy/cloud-enterprise/ece-containerization.md new file mode 100644 index 000000000..d17e19ea3 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-containerization.md @@ -0,0 +1,20 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-containerization.html +--- + +# Services as Docker containers [ece-containerization] + +Services are deployed as Docker containers, which simplifies the operational effort and makes it easy to provision similar environments for development and staging. Using Docker containers has the following advantages: + +* **Shares of resources** + + Each cluster node is run within a Docker container to make sure that all of the nodes have access to a guaranteed share of host resources. This mitigates the *noisy neighbor effect* where one busy deployment can overwhelm the entire host. The CPU resources are relative to the size of the Elasticsearch cluster they get assigned to. For example, a cluster with 32GB of RAM gets assigned twice as many CPU resources as a cluster with 16GB of RAM. + +* **Better security** + + On the assumption that any cluster can be compromised, containers are given no access to the platform. The same is true for the services: each service can read or write only those parts of the system state that are relevant to it. Even if some services are compromised, the attacker won’t get hold of the keys to the rest of them and will not compromise the whole platform. + +* **Secure communication through Stunnel** + + Docker containers communicate securely with one another through Transport Layer Security, provided by [Stunnel](https://www.stunnel.org/) (as not all of the services or components support TLS natively). Tunneling all traffic between containers makes sure that it is not possible to eavesdrop, even when someone else has access to the underlying cloud or network infrastructure. diff --git a/deploy-manage/deploy/cloud-enterprise/ece-ha.md b/deploy-manage/deploy/cloud-enterprise/ece-ha.md new file mode 100644 index 000000000..f6766b75a --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-ha.md @@ -0,0 +1,72 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-ha.html +--- + +# High availability [ece-ha] + + +## Availability zones [ece-ece-ha-1-az] + +Fault tolerance for Elastic Cloud Enterprise is based around the concept of *availability zones*. + +An availability zone contains resources available to an Elastic Cloud Enterprise installation that are isolated from other availability zones to safeguard against potential failure. + +Planning for a fault-tolerant installation with multiple availability zones means avoiding any single point of failure that could bring down Elastic Cloud Enterprise. + +The main difference between Elastic Cloud Enterprise installations that include two or three availability zones is that three availability zones enable Elastic Cloud Enterprise to create clusters with a *tiebreaker*. If you have only two availability zones in total in your installation, no tiebreaker is created. + +We recommend that for each deployment you use at least two availability zones for production and three for mission-critical systems. Using more than three availability zones for a deployment is not required nor supported. Availability zones are intended for high availability, not scalability. + +::::{warning} +{{es}} clusters that are set up to use only one availability zone are not [highly available](https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability-cluster-design.html) and are at risk of data loss. To safeguard against data loss, you must use at least two {{ece}} availability zones. +:::: + + +::::{warning} +Increasing the number of zones should not be used to add more resources. The concept of zones is meant for High Availability (2 zones) and Fault Tolerance (3 zones), but neither will work if the cluster relies on the resources from those zones to be operational. The recommendation is to scale up the resources within a single zone until the cluster can take the full load (add some buffer to be prepared for a peak of requests), then scale out by adding additional zones depending on your requirements: 2 zones for High Availability, 3 zones for Fault Tolerance. +:::: + + + +## Master nodes [ece-ece-ha-2-master-nodes] + +$$$ece-ha-tiebreaker$$$Tiebreakers are used in distributed clusters to avoid cases of [split brain](https://en.wikipedia.org/wiki/Split-brain_(computing)), where an {{es}} cluster splits into multiple, autonomous parts that continue to handle requests independently of each other, at the risk of affecting cluster consistency and data loss. A split-brain scenario is avoided by making sure that a minimum number of [master-eligible nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#master-node) must be present in order for any part of the cluster to elect a master node and accept user requests. To prevent multiple parts of a cluster from being eligible, there must be a [quorum-based majority](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-quorums.html) of `(n/2)+1` nodes, where `n` is the number of master-eligible nodes in the cluster. The minimum number of master nodes to reach quorum in a two-node cluster is the same as for a three-node cluster: two nodes must be available. + +When you create a cluster with nodes in two availability zones when a third zone is available, Elastic Cloud Enterprise can create a tiebreaker in the third availability zone to help establish quorum in case of loss of an availability zone. The extra tiebreaker node that helps to provide quorum does not have to be a full-fledged and expensive node, as it does not hold data. For example: By tagging allocators hosts in Elastic Cloud Enterprise, can you create a cluster with eight nodes each in zones `ece-1a` and `ece-1b`, for a total of 16 nodes, and one tiebreaker node in zone `ece-1c`. This cluster can lose any of the three availability zones whilst maintaining quorum, which means that the cluster can continue to process user requests, provided that there is sufficient capacity available when an availability zone goes down. + +By default, each node in an {{es}} cluster is a master-eligible node and a data node. In larger clusters, such as production clusters, it’s a good practice to split the roles, so that master nodes are not handling search or indexing work. When you create a cluster, you can specify to use dedicated [master-eligible nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#master-node), one per availability zone. + +::::{warning} +Clusters that only have two or fewer master-eligible node are not [highly available](https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability-cluster-design.html) and are at risk of data loss. You must have [at least three master-eligible nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-quorums.html). +:::: + + + +## Replica shards [ece-ece-ha-3-replica-shards] + +With multiple {{es}} nodes in multiple availability zones you have the recommended hardware, the next thing to consider is having the recommended index replication. Each index, with the exception of searchable snapshot indexes, should have one or more replicas. Use the index settings API to find any indices with no replica: + +```sh +GET _all/_settings/index.number_of_replicas +``` + +::::{warning} +Indices with no replica, except for [searchable snapshot indices](https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html), are not highly available. You should use replicas to mitigate against possible data loss. +:::: + + + +## Snapshot backups [ece-ece-ha-4-snapshot] + +You should configure and use [{{es}} snapshots](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html). Snapshots provide a way to backup and restore your {{es}} indices. They can be used to copy indices for testing, to recover from failures or accidental deletions, or to migrate data to other deployments. We recommend configuring an [{{ece}}-level repository](../../tools/snapshot-and-restore/cloud-enterprise.md) to apply across all deployments. See [Work with snapshots](../../tools/snapshot-and-restore.md) for more guidance. + + +## Furthermore considerations [ece-ece-ha-5-other] + +* Make sure you have three Zookeepers - by default, on the Director host - for your ECE installation. Similar to three Elasticsearch master nodes can form a quorum, three Zookeepers can forum the quorum for high availability purposes. Backing up Zookeeper data directory is also recommended, read [this doc](../../../troubleshoot/deployments/cloud-enterprise/rebuilding-broken-zookeeper-quorum.md) for more guidance. +* Make sure that if you’re using a [private Docker registry server](ece-install-offline-with-registry.md) or are using any [custom bundles and plugins](../../../solutions/search/full-text/search-with-synonyms.md) hosted on a web server, that these are available to all ECE allocators, so that they can continue to be accessed in the event of a network partition or zone outage. +* Don’t delete containers unless guided by Elastic Support or there’s public documentation explicitly describing this as required action. Otherwise, it can cause issues and you may lose access or functionality of your {{ece}} platform. See [Troubleshooting container engines](../../../troubleshoot/deployments/cloud-enterprise/troubleshooting-container-engines.md) for more information. + +If in doubt, please [contact support for help](../../../troubleshoot/deployments/cloud-enterprise/ask-for-help.md). + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-hardware-prereq.md b/deploy-manage/deploy/cloud-enterprise/ece-hardware-prereq.md new file mode 100644 index 000000000..6d5a1a6ad --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-hardware-prereq.md @@ -0,0 +1,62 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-hardware-prereq.html +--- + +# Hardware prerequisites [ece-hardware-prereq] + +ECE has specific hardware requirements for memory and storage. + +* [Memory](#ece-memory) +* [Storage](#ece-storage) +* [SSD Storage](#ece-ssd) + +::::{note} +For ECE 3.5.0 and prior versions, the host machines you use must support the x86-64 instruction set. From ECE 3.5.1 and newer versions, ARM based architecture (`aarch64`) is also supported. +:::: + + +::::{warning} +ECE installations with **spinning disks** are not supported when you run allocators and ECE management services on the same server. +:::: + + + +## Memory [ece-memory] + +| **Memory** | Coordinators | Directors | Proxies | Allocators | +| --- | --- | --- | --- | --- | +| Minimum to install | 8 GB RAM | 8 GB RAM | 8 GB RAM | 8 GB RAM
| +| Minimum recommended | 16 GB RAM | 8 GB RAM | 8 GB RAM | 128 GB to 256 GB RAM1
| +| **Small deployment**2 | 32 GB RAM | 32 GB RAM | 16 GB RAM | 128 GB RAM
| +| **Medium deployment**2 | 32 GB RAM | 32 GB RAM | 16 GB RAM | 256 GB RAM
| +| **Large deployment**3 | 128 GB RAM | 128 GB RAM | 16 GB RAM | 256 GB RAM
| + +1 Allocators must be sized to support your Elasticsearch clusters and Kibana instances. We recommend host machines that provide between 128 GB and 256 GB of memory. While smaller hosts might not pack larger Elasticsearch clusters and Kibana instances as efficiently, larger hosts might provide fewer CPU resources per GB of RAM on average. For example, running 64 * 2GB nodes on a 128GB host with 16 vCPUs means that each node will get 2/128 of the total CPU time. This is 1/4 core on average, and might not be sufficient. We recommend inspecting both what is the expected number and size of the nodes you plan to run on your hosts in order to understand which hardware will work best in your environment. + +2 For high availability, requires three hosts each of the capacities indicated, spread across three availability zones. + +3 For high availability, requires three hosts each of the capacities indicated (except for allocators), spread across three availability zones. For allocators, requires three or more hosts of the capacity indicated, spread across three availability zones. + +The size of your ECE deployment has a bearing on the JVM heap sizes that you should specify during installation. To learn more, check [JVM Heap Sizes](ece-jvm.md). + + +## Storage [ece-storage] + +| **Storage** | Coordinators | Directors | Proxies | Allocators | +| --- | --- | --- | --- | --- | +| Minimum to install | 10 GB | 10 GB | 15 GB | 10 GB | +| Minimum recommended | 1:4 RAM-to-storage ratio1 | 1:4 RAM-to-storage ratio1 | 1:4 RAM-to-storage ratio1 | Enough storage to support the RAM-to-storage ratio2 | + +1 Control-plane services usually require about 1:4 RAM-to-storage ratio, this may vary. + +2 For example, if you use a host with 256 GB of RAM and the default ratio of 1:32, your host must provide 8192 GB of disk space. + + +## SSD storage [ece-ssd] + +The ECE management services provided by the coordinators and directors require fast SSD storage to work correctly. For smaller deployments that co-locate the ECE management services with proxies and allocators on the same hosts, you must use fast SSD storage for your entire deployment. If SSD-only storage is not feasible, [some of the ECE management services need to be separated](ece-roles.md). + +::::{note} +When using SSDs on an external (shared) storage system, please check with your storage vendor whether TRIM [should be disabled](https://www.elastic.co/blog/is-your-elasticsearch-trimmed) on the ECE hosts to avoid unnecessary stress on the storage system. +:::: diff --git a/deploy-manage/deploy/cloud-enterprise/ece-include-additional-kibana-plugin.md b/deploy-manage/deploy/cloud-enterprise/ece-include-additional-kibana-plugin.md new file mode 100644 index 000000000..c235968cc --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-include-additional-kibana-plugin.md @@ -0,0 +1,155 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-include-additional-kibana-plugin.html +--- + +# Include additional Kibana plugins [ece-include-additional-kibana-plugin] + +In certain cases you may choose to expand the Kibana Docker image included in an Elastic Stack pack to include one or more additional plugins that are not bundled in the image by default. Plugins can extend the features included in Kibana, for example to include specialized visualizations. Adding plugins allows you to tailor your ECE deployments that include Kibana to suit your specific use cases. + +The process involves two main steps: + +1. [Extend an existing Kibana Docker image to include the additional plugins.](#ece-create-modified-docker-image) +2. [Update the Elastic Stack pack included in your ECE installation to point to your modified Docker image.](#ece-modify-stack-pack) + + +## Before you begin [ece_before_you_begin_5] + +Note the following restrictions: + +* These instructions have been tested for Elastic Stack versions starting with 6.7.0 and may not work for earlier versions. +* Plugins that you bundle yourself to be included in the Elastic Stack are not covered by Elastic Customer Support and include no guarantee from Elastic. +* After uploading a modified version of an Elastic Stack pack, if you reapply the original stack the changes will be lost and new Kibana instances will use the original Docker image provided by Elastic. +* The Dockerfile used in this example includes an optimization process that is relatively expensive and may require a machine with several GB of RAM to run successfully. + + +## Extend a Kibana Docker image to include additional plugins [ece-create-modified-docker-image] + +This example runs a Dockerfile to install the [analyze_api_ui plugin](https://github.com/johtani/analyze-api-ui-plugin) or [kibana-enhanced-table](https://github.com/fbaligand/kibana-enhanced-table) into different versions of Kibana Docker image. The contents of the Dockerfile varies depending on the version of the Elastic Stack pack that you want to modify. + +1. Choose a directory on your ECE installation and save the Dockerfile code for your Elastic Stack version as a file named `Dockerfile`. + + ```sh + FROM docker.elastic.co/cloud-release/kibana-cloud:8.13.1 + MAINTAINER Cloud Developers + + RUN /usr/share/kibana/bin/kibana-plugin install https://github.com/fbaligand/kibana-enhanced-table/releases/download/v1.14.0/enhanced-table-1.14.0_8.13.1.zip + ``` + +2. Update the Dockerfile for your specific use case by changing these settings: + + * The maintainer + * The version of the image + * The plugin name and version number + + ::::{important} + When you modify a Kibana Docker image, make sure you maintain the original image structure and only add the additional plugins. + :::: + +3. Build the modified Docker image, specifying an image name and version number. If you are using your own Docker repository, the `docker.elastic.co/cloud-assets` section must match your specific configuration. The image build process can take several minutes. + + ```sh + docker build . -t docker.elastic.co/cloud-assets/kibana-with-plugin:8.13.1 + ``` + +4. If you have your own Docker repository, you can [push the modified Docker image to your repository](ece-install-offline-no-registry.md). Otherwise, run the following commands to compress and load the image into Docker: + + 1. Create a .tar file of the Docker image, specifying the image name and version number: + + ```sh + docker save -o kibana.8.13.1.tar docker.elastic.co/cloud-assets/kibana-with-plugin:8.13.1 + ``` + + 2. Copy the .tar file to a location on your network where it is available to each ECE host. Alternatively, you can copy the .tar file to each host directly. A third option is to run the previous steps on each host to create the modified Docker image and .tar file. + 3. On each host, load the image into Docker, where `FILE_PATH` is the location of your modified Docker image: + + ```sh + docker load < FILE_PATH/kibana.8.13.1.tar + ``` + + + +## Modify the Elastic Stack pack to point to your modified image [ece-modify-stack-pack] + +Follow these steps to update the Elastic Stack pack zip files in your ECE setup to point to your modified Docker image: + +1. Download to a local directory the [Elastic Stack pack](manage-elastic-stack-versions.md) that you want to modify. +2. Save the following bash script with the name `change-kibana-image.sh`: + + ```sh + #!/usr/bin/env bash + + set -eo pipefail + + # Repack a stackpack to modify the Kibana image it points to + + NO_COLOR='\033[0m' + ERROR_COLOR='\033[1;31m' + WARN_COLOR='\033[0;33m' + ERROR="${ERROR_COLOR}[ERROR]${NO_COLOR}" + WARNING="${WARN_COLOR}[WARNING]${NO_COLOR}" + + if [[ -z "$1" ]]; then + echo -e "$ERROR Missing required stackpack argument" + exit 1 + fi + + if [[ -z "$2" ]]; then + echo -e "$ERROR Missing required kibana docker image argument" + exit 1 + fi + + STACKPACK=$1 + KIBANA_IMAGE=$2 + + if [[ ! -s "$STACKPACK" ]]; then + echo -e "$ERROR $STACKPACK: No such stackpack" + exit 1 + fi + + TMP_DIR=$(mktemp -d) + + TMP_FILE="$TMP_DIR/$(basename "$STACKPACK")" + cp "$STACKPACK" "$TMP_FILE" + + pushd "$TMP_DIR" > /dev/null + + MANIFEST=$(zipinfo -1 "$TMP_FILE" | grep -E "stack.*\.json") + unzip "$TMP_FILE" "$MANIFEST" > /dev/null + + jq ".kibana.docker_image |= \"${KIBANA_IMAGE}\"" "$MANIFEST" > "${MANIFEST}.updated" + mv "${MANIFEST}.updated" "$MANIFEST" + zip "$TMP_FILE" "$MANIFEST" > /dev/null + + popd > /dev/null + + cp "$TMP_FILE" "$STACKPACK" + + rm -rf "$TMP_DIR" + ``` + +3. Modify the script permissions so that you can run it: + + ```sh + sudo chmod 755 change-kibana-image.sh + ``` + +4. Run the script to update the Elastic Stack pack, where `FILE_PATH` is the location where you downloaded the Elastic Stack pack zip file: + + ```sh + ./change-kibana-image.sh FILE_PATH/8.13.1.zip docker.elastic.co/cloud-assets/kibana-with-plugin:8.13.1 + ``` + +5. Upload the modified Elastic Stack pack to your ECE installation: + + 1. [Log into the Cloud UI](log-into-cloud-ui.md). + 2. Go to **Platform** and then **Elastic Stack**. + 3. Select **Upload Elastic Stack pack** to add the new Elastic Stack pack or replace an existing one. You can create a new deployment using the new or updated Elastic stack pack. When you launch Kibana the additional plugin is available. + + + +## Common causes of problems [ece-custom-plugin-problems] + +1. If the custom Docker image is not available, make sure that the image has been uploaded to your Docker repository or loaded locally onto each ECE allocator. +2. If the container takes a long time to start, the problem might be that the `reoptimize` step in the Dockerfile did not complete successfully. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-install-offline-images.md b/deploy-manage/deploy/cloud-enterprise/ece-install-offline-images.md new file mode 100644 index 000000000..9647ab726 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-install-offline-images.md @@ -0,0 +1,1165 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-offline-images.html +--- + +# Available Docker images [ece-install-offline-images] + +Versions of the Elastic Stack, containing Elasticsearch, Kibana, and other products, are available as downloadable Docker images. + +The first table contains the stack versions that shipped with the 3.8 version of Elastic Cloud Enterprise. You can also check the [most recent stack packs and Docker images](#ece-recent-download-list), which might have released after the 3.8 version of ECE, as well as the [full list of available stack packs and Docker images](#ece-full-download-list). + +| Docker images included with Elastic Cloud Enterprise 3.8.1 | +| --- | +| docker.elastic.co/cloud-enterprise/elastic-cloud-enterprise:3.8.1 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.23-0 | +| docker.elastic.co/cloud-assets/kibana:6.8.23-0 | +| docker.elastic.co/cloud-assets/apm:6.8.23-0 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 | +| docker.elastic.co/cloud-assets/kibana:7.17.27-0 | +| docker.elastic.co/cloud-assets/apm:7.17.27-0 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 | +| docker.elastic.co/cloud-release/kibana-cloud:8.17.1 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 | + +$$$ece-all-stacks$$$Additional Elastic Stack versions are available as Docker images that you can use with ECE. For offline installations, you need to download both the Elastic Stack pack and the Docker images for the same version. + +To learn more about adding the stack pack to ECE, check [Manage Elastic Stack Versions](manage-elastic-stack-versions.md). + + +## Most recent Elastic Stack packs and Docker images [ece-recent-download-list] + +| Required downloads | Minimum required ECE version | +| --- | --- | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.17.1](https://download.elastic.co/cloud-enterprise/versions/8.17.1.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.17.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.27](https://download.elastic.co/cloud-enterprise/versions/7.17.27.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.27-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.27-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.23](https://download.elastic.co/cloud-enterprise/versions/6.8.23.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.23-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.23-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.23-0 | ECE 2.1.0 | +| | | + + +## All available Elastic Stack packs and Docker images [ece-full-download-list] + +::::{dropdown} **Expand to view the full list** +| Required downloads | Minimum required ECE version | +| --- | --- | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.17.1](https://download.elastic.co/cloud-enterprise/versions/8.17.1.zip) | ECE 3.0.0
(+ docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.17.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.17.0](https://download.elastic.co/cloud-enterprise/versions/8.17.0.zip) | ECE 3.0.0
(+ docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.0 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.17.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.0 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.3](https://download.elastic.co/cloud-enterprise/versions/8.16.3.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.16.3 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.16.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.16.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.16.3 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.2](https://download.elastic.co/cloud-enterprise/versions/8.16.2.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.16.2 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.16.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.16.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.16.2 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.1](https://download.elastic.co/cloud-enterprise/versions/8.16.1.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.16.1 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.16.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.16.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.16.1 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.0](https://download.elastic.co/cloud-enterprise/versions/8.16.0.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.16.0 | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| docker.elastic.co/cloud-release/kibana-cloud:8.16.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.16.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.16.0 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.5](https://download.elastic.co/cloud-enterprise/versions/8.15.5.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.15.5 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.15.5 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.15.5 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.15.5 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.4](https://download.elastic.co/cloud-enterprise/versions/8.15.4.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.15.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.15.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.15.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.15.4 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.3](https://download.elastic.co/cloud-enterprise/versions/8.15.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.15.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.15.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.15.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.15.3 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.2](https://download.elastic.co/cloud-enterprise/versions/8.15.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.15.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.15.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.15.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.15.2 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.1](https://download.elastic.co/cloud-enterprise/versions/8.15.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.15.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.15.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.15.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.15.1 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.0](https://download.elastic.co/cloud-enterprise/versions/8.15.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.15.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.15.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.15.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.15.0 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.3](https://download.elastic.co/cloud-enterprise/versions/8.14.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.14.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.14.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.14.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.14.3 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.2](https://download.elastic.co/cloud-enterprise/versions/8.14.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.14.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.14.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.14.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.14.2 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.1](https://download.elastic.co/cloud-enterprise/versions/8.14.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.14.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.14.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.14.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.14.1 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.0](https://download.elastic.co/cloud-enterprise/versions/8.14.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.14.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.14.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.14.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.14.0 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.4](https://download.elastic.co/cloud-enterprise/versions/8.13.4.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.13.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.13.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.13.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.13.4 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.3](https://download.elastic.co/cloud-enterprise/versions/8.13.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.13.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.13.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.13.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.13.3 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.2](https://download.elastic.co/cloud-enterprise/versions/8.13.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.13.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.13.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.13.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.13.2 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.1](https://download.elastic.co/cloud-enterprise/versions/8.13.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.13.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.13.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.13.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.13.1 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.0](https://download.elastic.co/cloud-enterprise/versions/8.13.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.13.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.13.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.13.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.13.0 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.12.2](https://download.elastic.co/cloud-enterprise/versions/8.12.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.12.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.12.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.12.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.12.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.12.1](https://download.elastic.co/cloud-enterprise/versions/8.12.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.12.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.12.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.12.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.12.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.12.0](https://download.elastic.co/cloud-enterprise/versions/8.12.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.12.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.12.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.12.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.12.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.4](https://download.elastic.co/cloud-enterprise/versions/8.11.4.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.11.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.11.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.11.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.11.4 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.3](https://download.elastic.co/cloud-enterprise/versions/8.11.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.11.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.11.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.11.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.11.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.2](https://download.elastic.co/cloud-enterprise/versions/8.11.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.11.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.11.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.11.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.11.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.1](https://download.elastic.co/cloud-enterprise/versions/8.11.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.11.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.11.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.11.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.11.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.0](https://download.elastic.co/cloud-enterprise/versions/8.11.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.11.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.11.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.11.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.11.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.4](https://download.elastic.co/cloud-enterprise/versions/8.10.4.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.10.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.10.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.10.4 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.10.4 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.3](https://download.elastic.co/cloud-enterprise/versions/8.10.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.10.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.10.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.10.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.10.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.2](https://download.elastic.co/cloud-enterprise/versions/8.10.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.10.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.10.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.10.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.10.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.1](https://download.elastic.co/cloud-enterprise/versions/8.10.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.10.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.10.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.10.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.10.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.0](https://download.elastic.co/cloud-enterprise/versions/8.10.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.10.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.10.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.10.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.10.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.9.2](https://download.elastic.co/cloud-enterprise/versions/8.9.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.9.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.9.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.9.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.9.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.9.1](https://download.elastic.co/cloud-enterprise/versions/8.9.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.9.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.9.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.9.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.9.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.9.0](https://download.elastic.co/cloud-enterprise/versions/8.9.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.9.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.9.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.9.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.9.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.8.2](https://download.elastic.co/cloud-enterprise/versions/8.8.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.8.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.8.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.8.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.8.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.8.1](https://download.elastic.co/cloud-enterprise/versions/8.8.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.8.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.8.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.8.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.8.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.8.0](https://download.elastic.co/cloud-enterprise/versions/8.8.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.8.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.8.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.8.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.8.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.7.1](https://download.elastic.co/cloud-enterprise/versions/8.7.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.7.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.7.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.7.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.7.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.7.0](https://download.elastic.co/cloud-enterprise/versions/8.7.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.7.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.7.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.7.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.7.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.6.2](https://download.elastic.co/cloud-enterprise/versions/8.6.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.6.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.6.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.6.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.6.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.6.1](https://download.elastic.co/cloud-enterprise/versions/8.6.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.6.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.6.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.6.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.6.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.6.0](https://download.elastic.co/cloud-enterprise/versions/8.6.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.6.0-2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.6.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.6.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.6.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.3](https://download.elastic.co/cloud-enterprise/versions/8.5.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.5.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.5.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.5.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.5.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.2](https://download.elastic.co/cloud-enterprise/versions/8.5.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.5.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.5.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.5.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.5.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.1](https://download.elastic.co/cloud-enterprise/versions/8.5.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.5.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.5.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.5.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.5.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.0](https://download.elastic.co/cloud-enterprise/versions/8.5.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.5.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.5.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.5.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.5.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.3](https://download.elastic.co/cloud-enterprise/versions/8.4.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.4.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.4.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.4.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.4.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.2](https://download.elastic.co/cloud-enterprise/versions/8.4.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.4.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.4.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.4.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.4.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.1](https://download.elastic.co/cloud-enterprise/versions/8.4.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.4.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.4.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.4.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.4.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.0](https://download.elastic.co/cloud-enterprise/versions/8.4.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.4.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.4.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.4.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.4.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.3](https://download.elastic.co/cloud-enterprise/versions/8.3.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.3.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.3.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.3.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.3.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.2](https://download.elastic.co/cloud-enterprise/versions/8.3.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.3.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.3.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.3.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.3.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.1](https://download.elastic.co/cloud-enterprise/versions/8.3.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.3.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.3.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.3.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.3.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.0](https://download.elastic.co/cloud-enterprise/versions/8.3.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.3.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.3.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.3.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.3.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.3](https://download.elastic.co/cloud-enterprise/versions/8.2.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.2.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.2.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.2.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.2.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.2](https://download.elastic.co/cloud-enterprise/versions/8.2.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.2.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.2.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.2.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.2.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.1](https://download.elastic.co/cloud-enterprise/versions/8.2.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.2.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.2.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.2.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.2.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.0](https://download.elastic.co/cloud-enterprise/versions/8.2.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.2.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.2.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.2.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.2.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.3](https://download.elastic.co/cloud-enterprise/versions/8.1.3.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.1.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.1.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.1.3 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.1.3 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.2](https://download.elastic.co/cloud-enterprise/versions/8.1.2.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.1.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.1.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.1.2 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.1.2 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.1](https://download.elastic.co/cloud-enterprise/versions/8.1.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.1.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.1.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.1.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.1.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.0](https://download.elastic.co/cloud-enterprise/versions/8.1.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.1.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.1.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.1.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.1.0 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.0.1](https://download.elastic.co/cloud-enterprise/versions/8.0.1.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.0.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.0.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.0.1 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.0.1 | ECE 3.0.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.0.0](https://download.elastic.co/cloud-enterprise/versions/8.0.0.zip) | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.0.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/kibana-cloud:8.0.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/elastic-agent-cloud:8.0.0 | ECE 3.0.0 | +| docker.elastic.co/cloud-release/enterprise-search-cloud:8.0.0 | ECE 3.0.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.27](https://download.elastic.co/cloud-enterprise/versions/7.17.27.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.27-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.27-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.26](https://download.elastic.co/cloud-enterprise/versions/7.17.26.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.26-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.26-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.26-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.26-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.25](https://download.elastic.co/cloud-enterprise/versions/7.17.25.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.25-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.25-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.25-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.25-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.24](https://download.elastic.co/cloud-enterprise/versions/7.17.24.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.24-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.24-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.24-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.24-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.23](https://download.elastic.co/cloud-enterprise/versions/7.17.23.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.23-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.23-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.23-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.23-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.22](https://download.elastic.co/cloud-enterprise/versions/7.17.22.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.22-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.22-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.22-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.22-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.21](https://download.elastic.co/cloud-enterprise/versions/7.17.21.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.21-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.21-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.21-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.21-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.20](https://download.elastic.co/cloud-enterprise/versions/7.17.20.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.20-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.20-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.20-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.20-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.19](https://download.elastic.co/cloud-enterprise/versions/7.17.19.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.19-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.19-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.19-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.19-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.18](https://download.elastic.co/cloud-enterprise/versions/7.17.18.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.18-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.18-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.18-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.18-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.17](https://download.elastic.co/cloud-enterprise/versions/7.17.17.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.17-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.17-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.17-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.17-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.16](https://download.elastic.co/cloud-enterprise/versions/7.17.16.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.16-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.16-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.16-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.16-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.15](https://download.elastic.co/cloud-enterprise/versions/7.17.15.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.15-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.15-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.15-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.15-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.14](https://download.elastic.co/cloud-enterprise/versions/7.17.14.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.14-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.14-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.14-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.14-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.13](https://download.elastic.co/cloud-enterprise/versions/7.17.13.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.13-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.13-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.13-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.13-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.12](https://download.elastic.co/cloud-enterprise/versions/7.17.12.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.12-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.12-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.12-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.12-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.11](https://download.elastic.co/cloud-enterprise/versions/7.17.11.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.11-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.11-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.11-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.11-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.10](https://download.elastic.co/cloud-enterprise/versions/7.17.10.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.10-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.10-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.10-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.10-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.9](https://download.elastic.co/cloud-enterprise/versions/7.17.9.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.9-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.9-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.9-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.9-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.8](https://download.elastic.co/cloud-enterprise/versions/7.17.8.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.8-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.8-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.8-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.8-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.7](https://download.elastic.co/cloud-enterprise/versions/7.17.7.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.7-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.7-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.7-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.7-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.6](https://download.elastic.co/cloud-enterprise/versions/7.17.6.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.6-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.6-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.6-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.6-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.5](https://download.elastic.co/cloud-enterprise/versions/7.17.5.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.5-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.5-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.5-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.5-0 | ECE 2.6.0 | +| | | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.4](https://download.elastic.co/cloud-enterprise/versions/7.17.4.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.4-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.4-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.4-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.4-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.3](https://download.elastic.co/cloud-enterprise/versions/7.17.3.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.3-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.2](https://download.elastic.co/cloud-enterprise/versions/7.17.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.2-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.1](https://download.elastic.co/cloud-enterprise/versions/7.17.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.0](https://download.elastic.co/cloud-enterprise/versions/7.17.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.17.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.17.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.17.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.17.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.3](https://download.elastic.co/cloud-enterprise/versions/7.16.3.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.16.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.16.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.16.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.16.3-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.2](https://download.elastic.co/cloud-enterprise/versions/7.16.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.16.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.16.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.16.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.16.2-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.1](https://download.elastic.co/cloud-enterprise/versions/7.16.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.16.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.16.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.16.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.16.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.0](https://download.elastic.co/cloud-enterprise/versions/7.16.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.16.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.16.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.16.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.16.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.15.2](https://download.elastic.co/cloud-enterprise/versions/7.15.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.15.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.15.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.15.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.15.2-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.15.1](https://download.elastic.co/cloud-enterprise/versions/7.15.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.15.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.15.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.15.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.15.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.15.0](https://download.elastic.co/cloud-enterprise/versions/7.15.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.15.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.15.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.15.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.15.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.14.2](https://download.elastic.co/cloud-enterprise/versions/7.14.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.14.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.14.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.14.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.14.2-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.14.1](https://download.elastic.co/cloud-enterprise/versions/7.14.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.14.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.14.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.14.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.14.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.14.0](https://download.elastic.co/cloud-enterprise/versions/7.14.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.14.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.14.0-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.14.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.14.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.4](https://download.elastic.co/cloud-enterprise/versions/7.13.4.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.13.4-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.13.4-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.13.4-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.13.4-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.3](https://download.elastic.co/cloud-enterprise/versions/7.13.3.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.13.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.13.3-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.13.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.13.3-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.2](https://download.elastic.co/cloud-enterprise/versions/7.13.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.13.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.13.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.13.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.13.2-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.1](https://download.elastic.co/cloud-enterprise/versions/7.13.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.13.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.13.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.13.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.13.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.0](https://download.elastic.co/cloud-enterprise/versions/7.13.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.13.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.13.0-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.13.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.13.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.12.1](https://download.elastic.co/cloud-enterprise/versions/7.12.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.12.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.12.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.12.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/enterprise-search:7.12.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.12.0](https://download.elastic.co/cloud-enterprise/versions/7.12.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.12.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.12.0-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.12.0-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.12.0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.11.2](https://download.elastic.co/cloud-enterprise/versions/7.11.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.11.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.11.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.11.2-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.11.2 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.11.1](https://download.elastic.co/cloud-enterprise/versions/7.11.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.11.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.11.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.11.1-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.11.1 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.11.0](https://download.elastic.co/cloud-enterprise/versions/7.11.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.11.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.11.0-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.11.0-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.11.0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.10.2](https://download.elastic.co/cloud-enterprise/versions/7.10.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.10.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.10.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.10.2-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.10.2 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.10.1](https://download.elastic.co/cloud-enterprise/versions/7.10.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.10.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.10.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.10.1-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.10.1 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.10.0](https://download.elastic.co/cloud-enterprise/versions/7.10.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.10.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.10.0-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.10.0-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.10.0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.3](https://download.elastic.co/cloud-enterprise/versions/7.9.3.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.9.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.9.3-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.9.3-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.9.3 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.2](https://download.elastic.co/cloud-enterprise/versions/7.9.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.9.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.9.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.9.2-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.9.2 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.1](https://download.elastic.co/cloud-enterprise/versions/7.9.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.9.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.9.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.9.1-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.9.1 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.0](https://download.elastic.co/cloud-enterprise/versions/7.9.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.9.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.9.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.9.0-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.9.0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.8.1](https://download.elastic.co/cloud-enterprise/versions/7.8.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.8.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.8.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.8.1-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.8.1 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.8.0](https://download.elastic.co/cloud-enterprise/versions/7.8.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.8.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.8.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.8.0-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.8.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.7.1](https://download.elastic.co/cloud-enterprise/versions/7.7.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.7.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.7.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.7.1-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.7.1-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.7.0](https://download.elastic.co/cloud-enterprise/versions/7.7.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.7.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.7.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.7.0-0 | ECE 2.2.2 | +| docker.elastic.co/enterprise-search/enterprise-search:7.7.0-0 | ECE 2.6.0 | +| | | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.6.2](https://download.elastic.co/cloud-enterprise/versions/7.6.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.6.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.6.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.6.2-0 | ECE 2.2.2 | +| docker.elastic.co/app-search/app-search:7.6.2 | ECE 2.4.0 | +| | | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.6.1](https://download.elastic.co/cloud-enterprise/versions/7.6.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.6.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.6.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.6.1-0 | ECE 2.2.2 | +| docker.elastic.co/app-search/app-search:7.6.1 | ECE 2.4.0 | +| | | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.6.0](https://download.elastic.co/cloud-enterprise/versions/7.6.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.6.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.6.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.6.0-0 | ECE 2.2.2 | +| docker.elastic.co/app-search/app-search:7.6.0 | ECE 2.4.0 | +| | | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.5.2](https://download.elastic.co/cloud-enterprise/versions/7.5.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.5.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.5.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.5.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/app-search:7.5.2-0 | ECE 2.4.0 | +| | | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.5.1](https://download.elastic.co/cloud-enterprise/versions/7.5.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.5.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.5.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.5.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/app-search:7.5.1-0 | ECE 2.4.0 | +| | | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.5.0](https://download.elastic.co/cloud-enterprise/versions/7.5.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.5.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.5.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.5.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/app-search:7.5.0-0 | ECE 2.4.0 | +| | | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.4.2](https://download.elastic.co/cloud-enterprise/versions/7.4.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.4.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.4.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.4.2-0 | ECE 2.2.2 | +| docker.elastic.co/app-search/app-search:7.4.2 | ECE 2.4.0 | +| | | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.4.1](https://download.elastic.co/cloud-enterprise/versions/7.4.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.4.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.4.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.4.1-1 | ECE 2.2.2 | +| docker.elastic.co/app-search/app-search:7.4.1 | ECE 2.4.0 | +| | | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.4.0](https://download.elastic.co/cloud-enterprise/versions/7.4.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.4.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.4.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.4.0-0 | ECE 2.2.2 | +| docker.elastic.co/app-search/app-search:7.4.0 | ECE 2.4.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.3.2](https://download.elastic.co/cloud-enterprise/versions/7.3.2.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.3.2-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.3.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.3.2-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.3.1](https://download.elastic.co/cloud-enterprise/versions/7.3.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.3.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.3.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.3.1-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.3.0](https://download.elastic.co/cloud-enterprise/versions/7.3.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.3.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.3.2-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.3.0-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.2.1](https://download.elastic.co/cloud-enterprise/versions/7.2.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.2.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.2.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.2.1-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.2.0](https://download.elastic.co/cloud-enterprise/versions/7.2.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.2.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.2.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.2.0-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.1.1](https://download.elastic.co/cloud-enterprise/versions/7.1.1.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.1.1-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.1.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.1.1-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.1.0](https://download.elastic.co/cloud-enterprise/versions/7.1.0.zip) | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/elasticsearch:7.1.0-0 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/kibana:7.1.1-1 | ECE 2.2.2 | +| docker.elastic.co/cloud-assets/apm:7.1.0-0 | ECE 2.2.2 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.0.1](https://download.elastic.co/cloud-enterprise/versions/7.0.1.zip) | ECE 2.2.0 | +| docker.elastic.co/cloud-assets/elasticsearch:7.0.1-0 | ECE 2.2.0 | +| docker.elastic.co/cloud-assets/kibana:7.0.1-1 | ECE 2.2.0 | +| docker.elastic.co/cloud-assets/apm:7.0.1-0 | ECE 2.2.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 7.0.0](https://download.elastic.co/cloud-enterprise/versions/7.0.0.zip) | ECE 2.2.0 | +| docker.elastic.co/cloud-assets/elasticsearch:7.0.0-0 | ECE 2.2.0 | +| docker.elastic.co/cloud-assets/kibana:7.0.1-1 | ECE 2.2.0 | +| docker.elastic.co/cloud-assets/apm:7.0.0-0 | ECE 2.2.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.23](https://download.elastic.co/cloud-enterprise/versions/6.8.23.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.23-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.23-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.23-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.22](https://download.elastic.co/cloud-enterprise/versions/6.8.22.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.22-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.22-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.22-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.21](https://download.elastic.co/cloud-enterprise/versions/6.8.21.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.21-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.21-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.21-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.20](https://download.elastic.co/cloud-enterprise/versions/6.8.20.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.20-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.20-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.20-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.19](https://download.elastic.co/cloud-enterprise/versions/6.8.19.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.19-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.19-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.19-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.18](https://download.elastic.co/cloud-enterprise/versions/6.8.18.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.18-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.18-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.18-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.17](https://download.elastic.co/cloud-enterprise/versions/6.8.17.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.17-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.17-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.17-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.16](https://download.elastic.co/cloud-enterprise/versions/6.8.16.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.16-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.16-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.16-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.15](https://download.elastic.co/cloud-enterprise/versions/6.8.15.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.15-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.15-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.15-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.14](https://download.elastic.co/cloud-enterprise/versions/6.8.14.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.14-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.14-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.14-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.13](https://download.elastic.co/cloud-enterprise/versions/6.8.13.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.13-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.13-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.13-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.12](https://download.elastic.co/cloud-enterprise/versions/6.8.12.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.12-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.12-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.12-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.11](https://download.elastic.co/cloud-enterprise/versions/6.8.11.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.11-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.11-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.11-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.10](https://download.elastic.co/cloud-enterprise/versions/6.8.10.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.10-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.10-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.10-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.9](https://download.elastic.co/cloud-enterprise/versions/6.8.9.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.9-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.8](https://download.elastic.co/cloud-enterprise/versions/6.8.8.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.8-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.8-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.7](https://download.elastic.co/cloud-enterprise/versions/6.8.7.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.7-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.7-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.6](https://download.elastic.co/cloud-enterprise/versions/6.8.6.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.6-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.6-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.5](https://download.elastic.co/cloud-enterprise/versions/6.8.5.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.5-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.5-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.4](https://download.elastic.co/cloud-enterprise/versions/6.8.4.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.4-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.4-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.3](https://download.elastic.co/cloud-enterprise/versions/6.8.3.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.3-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.3-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.2](https://download.elastic.co/cloud-enterprise/versions/6.8.2.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.2-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.1](https://download.elastic.co/cloud-enterprise/versions/6.8.1.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.1-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.0](https://download.elastic.co/cloud-enterprise/versions/6.8.0.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.8.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.8.9-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.8.0-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.7.2](https://download.elastic.co/cloud-enterprise/versions/6.7.2.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.7.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.7.2-1 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.7.2-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.7.1](https://download.elastic.co/cloud-enterprise/versions/6.7.1.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.7.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.7.2-1 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.7.1-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.7.0](https://download.elastic.co/cloud-enterprise/versions/6.7.0.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.7.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.7.2-1 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.7.0-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.6.2](https://download.elastic.co/cloud-enterprise/versions/6.6.2.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.6.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.6.2-1 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.6.2-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.6.1](https://download.elastic.co/cloud-enterprise/versions/6.6.1.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.6.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.6.2-1 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.6.1-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.6.0](https://download.elastic.co/cloud-enterprise/versions/6.6.0.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.6.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.6.2-1 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.6.0-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.4](https://download.elastic.co/cloud-enterprise/versions/6.5.4.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.5.4-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.5.4-2 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.5.4-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.3](https://download.elastic.co/cloud-enterprise/versions/6.5.3.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.5.3-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.5.4-2 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.5.3-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.2](https://download.elastic.co/cloud-enterprise/versions/6.5.2.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.5.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.5.4-2 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.5.2-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.1](https://download.elastic.co/cloud-enterprise/versions/6.5.1.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.5.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.5.4-2 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.5.1-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.0](https://download.elastic.co/cloud-enterprise/versions/6.5.0.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.5.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.5.4-2 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.5.0-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.3](https://download.elastic.co/cloud-enterprise/versions/6.4.3.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.4.3-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.4.3-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.4.3-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.2](https://download.elastic.co/cloud-enterprise/versions/6.4.2.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.4.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.4.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.4.2-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.1](https://download.elastic.co/cloud-enterprise/versions/6.4.1.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.4.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.4.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.4.1-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.0](https://download.elastic.co/cloud-enterprise/versions/6.4.0.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.4.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.4.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.4.0-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.3.2](https://download.elastic.co/cloud-enterprise/versions/6.3.2.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.3.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.3.2-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.3.2-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.3.1](https://download.elastic.co/cloud-enterprise/versions/6.3.1.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.3.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.3.1-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.3.1-0 | ECE 2.1.0 | +| | | +| [Elasticsearch, Kibana, and APM stack pack: 6.3.0](https://download.elastic.co/cloud-enterprise/versions/6.3.0.zip) | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/elasticsearch:6.3.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/kibana:6.3.0-0 | ECE 1.1.4 | +| docker.elastic.co/cloud-assets/apm:6.3.0-0 | ECE 2.1.0 | +| | | +| [Elasticsearch and Kibana stack pack: 6.2.4](https://download.elastic.co/cloud-enterprise/versions/6.2.4.zip) | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/elasticsearch:6.2.4-0 | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/kibana:6.2.4-0 | ECE 1.1.2 | +| | | +| [Elasticsearch and Kibana stack pack: 6.2.3](https://download.elastic.co/cloud-enterprise/versions/6.2.3.zip) | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/elasticsearch:6.2.3-0 | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/kibana:6.2.3-0 | ECE 1.1.2 | +| | | +| [Elasticsearch and Kibana stack pack: 6.2.2](https://download.elastic.co/cloud-enterprise/versions/6.2.2.zip) | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/elasticsearch:6.2.2-0 | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/kibana:6.2.2-0 | ECE 1.1.2 | +| | | +| [Elasticsearch and Kibana stack pack: 6.1.4](https://download.elastic.co/cloud-enterprise/versions/6.1.4.zip) | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/elasticsearch:6.1.4-0 | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/kibana:6.1.4-0 | ECE 1.1.2 | +| | | +| [Elasticsearch and Kibana stack pack: 6.1.3](https://download.elastic.co/cloud-enterprise/versions/6.1.3.zip) | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/elasticsearch:6.1.3-0 | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/kibana:6.1.3-0 | ECE 1.1.2 | +| | | +| [Elasticsearch and Kibana stack pack: 6.0.1](https://download.elastic.co/cloud-enterprise/versions/6.0.1.zip) | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/elasticsearch:6.0.1-0 | ECE 1.1.2 | +| docker.elastic.co/cloud-assets/kibana:6.0.1-0 | ECE 1.1.2 | +| | | +| [Elasticsearch and Kibana stack pack: 6.0.0](https://download.elastic.co/cloud-enterprise/versions/6.0.0.zip) | ECE 1.1.0 | +| docker.elastic.co/cloud-assets/elasticsearch:6.0.0-0 | ECE 1.1.0 | +| docker.elastic.co/cloud-assets/kibana:6.0.0-0 | ECE 1.1.0 | +| | | +| [Elasticsearch and Kibana stack pack: 5.6.16](https://download.elastic.co/cloud-enterprise/versions/5.6.16.zip) | ECE 1.1.0 | +| docker.elastic.co/cloud-assets/elasticsearch:5.6.16-0 | ECE 1.1.0 | +| docker.elastic.co/cloud-assets/kibana:5.6.16-0 | ECE 1.1.0 | +| | | +| [Elasticsearch and Kibana stack pack: 2.4.6](https://download.elastic.co/cloud-enterprise/versions/2.4.6.zip) | ECE 1.0.0 | +| docker.elastic.co/cloud-assets/elasticsearch:2.4.6-1 | ECE 1.0.0 | +| docker.elastic.co/cloud-assets/kibana:4.6.6-2 | ECE 1.0.0 | +| | | +| [Elasticsearch and Kibana stack pack: 2.4.5](https://download.elastic.co/cloud-enterprise/versions/2.4.5.zip) | ECE 1.0.0 | +| docker.elastic.co/cloud-assets/elasticsearch:2.4.5-1 | ECE 1.0.0 | +| docker.elastic.co/cloud-assets/kibana:4.6.4-0 | ECE 1.0.0 | + +:::: diff --git a/deploy-manage/deploy/cloud-enterprise/ece-install-offline-no-registry.md b/deploy-manage/deploy/cloud-enterprise/ece-install-offline-no-registry.md new file mode 100644 index 000000000..74ef4134c --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-install-offline-no-registry.md @@ -0,0 +1,82 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-offline-no-registry.html +--- + +# Without a private Docker registry [ece-install-offline-no-registry] + +To perform an offline installation without a private Docker registry, you have to download the available Docker Images on each host. + +1. On an internet-connected host that has Docker installed, download the [Available Docker Images](ece-install-offline-images.md). Note that for ECE version 3.0, if you want to use Elastic Stack version 8.0 in your deployments, you need to download and make available both the version 7.x and version 8.x Docker images (the version 7.x images are required for system deployments). + + ```sh + docker pull docker.elastic.co/cloud-enterprise/elastic-cloud-enterprise:3.8.1 + docker pull docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 + docker pull docker.elastic.co/cloud-assets/kibana:7.17.27-0 + docker pull docker.elastic.co/cloud-assets/apm:7.17.27-0 + docker pull docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 + docker pull docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 + docker pull docker.elastic.co/cloud-release/kibana-cloud:8.17.1 + docker pull docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 + docker pull docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 + ``` + + For example, for Elastic Cloud Enterprise 3.8.1 and the Elastic Stack versions it shipped with, you need: + + * Elastic Cloud Enterprise 3.8.1 + * Elasticsearch 8.17.1, Kibana 8.17.1, APM 8.17.1, and Enterprise Search 8.17.1 + +2. Create .tar files of the images: + + ```sh + docker save -o ece.3.8.1.tar docker.elastic.co/cloud-enterprise/elastic-cloud-enterprise:3.8.1 + docker save -o es.7.17.27-0.tar docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 + docker save -o kibana.7.17.27-0.tar docker.elastic.co/cloud-assets/kibana:7.17.27-0 + docker save -o apm.7.17.27-0.tar docker.elastic.co/cloud-assets/apm:7.17.27-0 + docker save -o enterprise-search.7.17.27-0.tar docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 + docker save -o es.8.17.1.tar docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 + docker save -o kibana.8.17.1.tar docker.elastic.co/cloud-release/kibana-cloud:8.17.1 + docker save -o apm.8.17.1.tar docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 + docker save -o enterprise-search.8.17.1.tar docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 + ``` + +3. Copy the .tar files to a location on your network where they are available to each host where you plan to install Elastic Cloud Enterprise. Alternatively, you can copy the .tar files to each host directly. +4. On each host, load the images into Docker, replacing `FILE_PATH` with the correct path to the .tar files: + + ```sh + docker load < FILE_PATH/ece.3.8.1.tar + docker load < FILE_PATH/es.7.17.27-0.tar + docker load < FILE_PATH/kibana.7.17.27-0.tar + docker load < FILE_PATH/apm.7.17.27-0.tar + docker load < FILE_PATH/enterprise-search.7.17.27-0.tar + docker load < FILE_PATH/es.8.17.1.tar + docker load < FILE_PATH/kibana.8.17.1.tar + docker load < FILE_PATH/apm.8.17.1.tar + docker load < FILE_PATH/enterprise-search.8.17.1.tar + ``` + +5. Optional: Remove the .tar files after installation. +6. On an internet-connected host, download the installation script: + + ```sh + curl -L -O https://download.elastic.co/cloud/elastic-cloud-enterprise.sh + ``` + +7. Copy the installation script to each host where you plan to install Elastic Cloud Enterprise or make it available on your network. +8. Invoke the installation script on each host: + + 1. On the first host: + + ```sh + bash elastic-cloud-enterprise.sh install + ``` + + 2. On additional hosts, include the `--coordinator-host HOST_IP` and `--roles-token 'TOKEN'` parameters provided to you when you installed on the first host: + + ```sh + bash elastic-cloud-enterprise.sh install + --coordinator-host HOST_IP + --roles-token 'TOKEN' + ``` + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-install-offline-with-registry.md b/deploy-manage/deploy/cloud-enterprise/ece-install-offline-with-registry.md new file mode 100644 index 000000000..c8ff0849e --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-install-offline-with-registry.md @@ -0,0 +1,88 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-offline-with-registry.html +--- + +# With your private Docker registry [ece-install-offline-with-registry] + +Installing ECE on multiple hosts with your own registry server is simpler, because you do not have to load the Docker images on each host. + +1. Set up your private Docker registry. To learn more, check [Deploy a registry server](https://docs.docker.com/registry/deploying/). + + ::::{tip} + As part of the ECE [high availability](ece-ha.md) strategy, it’s a good idea to make sure that your Docker registry server is available to all ECE allocators, so that it can continue to be accessed in the event of a network partition or zone outage. Allocators attempting to start instances requiring Docker images that have not yet been pulled from a custom Docker registry will fail to start if the registry is unavailable. + :::: + +2. On an internet-connected host that has Docker installed, download the [Available Docker Images](ece-install-offline-images.md) and push them to your private Docker registry. Note that for ECE version 3.0, if you want to use Elastic Stack version 8.0 in your deployments, you need to download and make available both the version 7.x and version 8.x Docker images. + + ```sh + docker pull docker.elastic.co/cloud-enterprise/elastic-cloud-enterprise:3.8.1 + docker pull docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 + docker pull docker.elastic.co/cloud-assets/kibana:7.17.27-0 + docker pull docker.elastic.co/cloud-assets/apm:7.17.27-0 + docker pull docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 + docker pull docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 + docker pull docker.elastic.co/cloud-release/kibana-cloud:8.17.1 + docker pull docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 + docker pull docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 + ``` + + For example, for Elastic Cloud Enterprise 3.8.1 and the Elastic Stack versions it shipped with, you need: + + * Elastic Cloud Enterprise 3.8.1 + * Elasticsearch 8.17.1, Kibana 8.17.1, APM 8.17.1, and Enterprise Search 8.17.1 + +3. Tag the Docker images with your private registry, where `REGISTRY` is `my.private.repo:5000`, for example: + + ```sh + docker tag docker.elastic.co/cloud-enterprise/elastic-cloud-enterprise:3.8.1 REGISTRY/cloud-enterprise/elastic-cloud-enterprise:3.8.1 + docker tag docker.elastic.co/cloud-assets/elasticsearch:7.17.27-0 REGISTRY/cloud-assets/elasticsearch:7.17.27-0 + docker tag docker.elastic.co/cloud-assets/kibana:7.17.27-0 REGISTRY/cloud-assets/kibana:7.17.27-0 + docker tag docker.elastic.co/cloud-assets/apm:7.17.27-0 REGISTRY/cloud-assets/apm:7.17.27-0 + docker tag docker.elastic.co/cloud-assets/enterprise-search:7.17.27-0 REGISTRY/cloud-assets/enterprise-search:7.17.27-0 + docker tag docker.elastic.co/cloud-release/elasticsearch-cloud-ess:8.17.1 REGISTRY/cloud-release/elasticsearch-cloud-ess:8.17.1 + docker tag docker.elastic.co/cloud-release/kibana-cloud:8.17.1 REGISTRY/cloud-release/kibana-cloud:8.17.1 + docker tag docker.elastic.co/cloud-release/elastic-agent-cloud:8.17.1 REGISTRY/cloud-release/elastic-agent-cloud:8.17.1 + docker tag docker.elastic.co/cloud-release/enterprise-search-cloud:8.17.1 REGISTRY/cloud-release/enterprise-search-cloud:8.17.1 + ``` + +4. Push the Docker images to your private Docker registry, where `REGISTRY` is `my.private.repo:5000`, for example: + + ```sh + docker push REGISTRY/cloud-enterprise/elastic-cloud-enterprise:3.8.1 + docker push REGISTRY/cloud-assets/elasticsearch:7.17.27-0 + docker push REGISTRY/cloud-assets/kibana:7.17.27-0 + docker push REGISTRY/cloud-assets/apm:7.17.27-0 + docker push REGISTRY/cloud-assets/enterprise-search:7.17.27-0 + docker push REGISTRY/cloud-release/elasticsearch-cloud-ess:8.17.1 + docker push REGISTRY/cloud-release/kibana-cloud:8.17.1 + docker push REGISTRY/cloud-release/elastic-agent-cloud:8.17.1 + docker push REGISTRY/cloud-release/enterprise-search-cloud:8.17.1 + ``` + +5. On an internet-connected host, download the installation script: + + ```sh + curl -L -O https://download.elastic.co/cloud/elastic-cloud-enterprise.sh + ``` + +6. Copy the installation script to each host where you plan to install Elastic Cloud Enterprise. (Alternatively, you can place the installation script in a secure network location where your other hosts can access it.) +7. Invoke the installation script on each host with the `--docker-registry REGISTRY` parameter, where `REGISTRY` is `my.private.repo:5000`, for example: + + 1. On the first host: + + ```sh + bash elastic-cloud-enterprise.sh install + --docker-registry REGISTRY + ``` + + 2. On additional hosts, include the `--coordinator-host HOST_IP` and `--roles-token 'TOKEN'` parameters provided to you when you installed on the first host, along with the `--docker-registry REGISTRY` parameter: + + ```sh + bash elastic-cloud-enterprise.sh install + --coordinator-host HOST_IP + --roles-token 'TOKEN' + --docker-registry REGISTRY + ``` + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-jvm.md b/deploy-manage/deploy/cloud-enterprise/ece-jvm.md new file mode 100644 index 000000000..6cc8797d3 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-jvm.md @@ -0,0 +1,25 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-jvm.html +--- + +# JVM heap size [ece-jvm] + +::::{important} +ECE uses default JVM heap sizes for services that work for testing. Make sure to configure the JVM heap size that fits your use case. Not following the recommended settings may cause issues later on as volume of data and usage increases. +:::: + + +When you install ECE specify the recommended JVM heap sizes with `--memory-settings JVM_SETTINGS` parameter, based on the use cases as described below: + +* [Deploy a small installation](deploy-small-installation-onprem.md): For development, test, and small-scale use cases. +* [Deploy a medium installation](deploy-medium-installation-onprem.md): For many production setups. +* [Deploy a large installation](deploy-large-installation-onprem.md): For deployments with significant overall search and indexing throughput. + +Other JVM heap sizes can be left at their defaults. + +::::{note} +In the current release, there is no direct way to change the Java heap size in the UI. In case you need to configure the settings after ECE installation, refer to [Cloud UI login failures](../../../troubleshoot/deployments/cloud-enterprise/common-issues.md#ece-issues-login-failure) for further guidance. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-load-balancers.md b/deploy-manage/deploy/cloud-enterprise/ece-load-balancers.md new file mode 100644 index 000000000..220612d36 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-load-balancers.md @@ -0,0 +1,65 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-load-balancers.html +--- + +# Load balancers [ece-load-balancers] + +Elastic Cloud Enterprise is designed to be used in conjunction with at least one load balancer. A load balancer is not included with Elastic Cloud Enterprise, so you need to provide one yourself and place it in front of the Elastic Cloud Enterprise proxies. + +Use the following recommendations when configuring your load balancer: + +* **High availability**: The exact number of load balancers depends on the utilization rate for your clusters. In a highly available installation, use at least two load balancers for each availability zone in your installation. +* **Inbound ports**: Load balancers require that inbound traffic is open on the ports used by Elasticsearch, Kibana, and the transport client. +* **X-found-cluster**: ECE proxy uses the header `X-found-cluster` to know which cluster’s UUID (Universally Unique Identifier) the traffic needs to be routed to. If the load balancer rewrites a URL, make sure the HTTP header `X-Found-Cluster` gets added. For example: `X-found-cluster: d59109b8d542c5c4845679e597810796`. +* **X-Forwarded-For**: Configure load balancers to strip inbound `X-Forwarded-For` headers and to replace them with the client source IP as seen by the load balancer. This is required to prevent clients from spoofing their IP addresses. Elastic Cloud Enterprise uses `X-Forwarded-For` for logging client IP addresses and, if you have implemented IP filtering, for traffic management. +* **HTTP**: Use *HTTP mode* for ports 9200/9243 (HTTP traffic to clusters) and also for ports 12400/12443 (adminconsole traffic). +* **TCP**: Use *TCP mode* for ports 9300/9343 (transport client traffic to clusters) and the load balancer should enable the proxy protocol support. +* **TCP**: Use *TCP mode* for port 9400 for TLS authenticated passthrough between clusters for cross-cluster search (CCS) and replication (CCR), if used. The load balancer should **not** enable the proxy protocol support. +* **TCP**: Use *HTTP mode* for port 9443 for API key authenticated traffic between clusters for cross-cluster search (CCS) and replication (CCR), if used. Make sure that all load balancers or proxies sending this traffic to deployments hosted on Elastic Cloud Enterprise are sending HTTP/1.1 traffic. +* **Deployment traffic and Admin traffic**: Create separate load balancers for Deployment traffic (Elasticsearch and Kibana traffic) and Admin traffic (Cloud UI Console and Admin API). This separation allows you to migrate to a large installation topology without reconfiguring or creating an additional load balancer. +* **Traffic across proxies**: Balance traffic evenly across all proxies. Proxies are constantly updated with the internal routing information on how to direct requests to clusters on allocators that are hosting their nodes across zones. Proxies prefer cluster nodes in their local zone and route requests primarily to nodes in their own zone. +* **Network**: Use network that is fast enough from a latency and throughput perspective to be considered local for the Elasticsearch clustering requirement. There shouldn’t be a major advantage in "preferring local" from a load balancer perspective (rather than a proxy perspective), it might even lead to potential hot spotting on specific proxies, so it should be avoided. +* **TCP Timeout**: Use the default (or required) TCP timeout value from the cloud provider and do not to set a timeout for the load balancer. + + +## Proxy health check for ECE 2.0 and earlier [ece_proxy_health_check_for_ece_2_0_and_earlier] + +You can use `/__elb_health__` on your proxy hosts and check for a 200 response that indicates healthy. + +``` +http://:9200>/__elb_health__ +``` + +or + +``` +https://:9243>/__elb_health__ +``` + +This returns a healthy response as: + +``` +{"ok":true,"status":200} +``` + + +## Proxy health check for ECE 2.1 and later [ece_proxy_health_check_for_ece_2_1_and_later] + +For Elastic Cloud Enterprise 2.1 and later, the health check endpoint has changed. You can use `/_health` on proxy hosts with a result of either a 200 OK to indicate healthy or a 502 Bad Gateway response for unhealthy. A healthy response also means that internal routing tables in the proxy are valid and initialized, but not necessarily up-to-date. + +``` +http://PROXY_ADDRESS:9200/_health +``` + +or + +``` +https://PROXY_ADDRESS:9243/_health +``` + +This returns a healthy response as: + +``` +{"ok":true,"status":200} +``` diff --git a/deploy-manage/deploy/cloud-enterprise/ece-manage-capacity.md b/deploy-manage/deploy/cloud-enterprise/ece-manage-capacity.md new file mode 100644 index 000000000..3032f5368 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-manage-capacity.md @@ -0,0 +1,151 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-capacity.html +--- + +# Manage your installation capacity [ece-manage-capacity] + +In ECE, every host is a runner. Depending on the size of your platform, runners can have [one or more roles](ece-roles.md): Coordinator, director, proxy, and allocator. While planning the capacity of your ECE installation, you have to properly size the capacity for all roles. However, the allocator role deserves particular attention, as it hosts the Elasticsearch, Kibana, APM, Enterprise Search nodes, and the relevant services. + +This section focuses on the allocator role, and explains how to plan its capacity in terms of memory, CPU, `processors` setting, and storage. + +* [Memory](#ece-alloc-memory) +* [CPU quotas](#ece-alloc-cpu) +* [Processors setting](#ece-alloc-processors-setting) +* [Storage](#ece-alloc-storage) + + +## Memory [ece-alloc-memory] + +You should plan your deployment size based on the amount of data you ingest. Memory is the main scaling unit for a deployment. Other units, like CPU and disks, are proportional to the memory size. The memory available for an allocator is called *capacity*. + +During installation, the allocator capacity defaults to 85% of the host physical memory, as the rest is reserved for ECE system services. + +::::{note} +ECE does not support hot-adding of resources to a running node. When increasing CPU/memory allocated to a ECE node, a restart is needed to utilize the additional resources. +:::: + + +To adjust the allocator capacity, prior to ECE 3.5.0; it is necessary to reinstall ECE on the host with a new value assigned to the `--capacity` parameter. From ECE 3.5.0 onwards, just use the ECE API : + +```sh +curl -X PUT \ + http(s):///api/v1/platform/infrastructure/allocators//settings \ + -H “Authorization: ApiKey $ECE_API_KEY” \ + -H 'Content-Type: application/json' \ + -d '{"capacity":}' +``` + +For more information on how to use API keys for authentication, check the section [Access the API from the Command Line](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-api-command-line.html). + +::::{important} +Prior to ECE 3.5.0, regardless of the use of this API, the [CPU quota](#ece-alloc-cpu) used the memory specified at installation time. +:::: + + + +### Examples [ece_examples] + +Here are some examples to make Elastic deployments and ECE system services run smoothly on your host: + +* If the runner has more than one role (allocator, coordinator, director, or proxy), you should reserve 28GB of host memory. For example, on a host with 256GB of RAM, 228GB is suitable for deployment use. +* If the runner has only the Allocator role, you should reserve 12GB of host memory. For example, on a host with 256GB of RAM, 244GB is suitable for deployment use. + +Note that the recommended reservations above are not guaranteed upper limits, if you measure actual memory usage you may see numbers 0-2GB higher or lower. + +These fluctuations should not be a concern in practice. To get actual limits that could be used in alerts, you could add 4GB to the recommended values above. + + +## CPU quotas [ece-alloc-cpu] + +ECE uses CPU quotas to assign shares of the allocator host to the instances that are running on it. To calculate the CPU quota, use the following formula: + +`CPU quota = DeploymentRAM / HostCapacity` + + +### Examples [ece_examples_2] + +Consider a 32GB deployment hosted on a 128GB allocator. + +If you use the default system service reservation, the CPU quota is 29%: + +
+
+\$CPU quota = 32 / (128 * 0.85) = 29%\$ +
+
+If you use 12GB Allocator system service reservation, the CPU quota is 28%: + +
+
+\$CPU quota = 32 / (128 - 12) = 28%\$ +
+
+Those percentages represent the upper limit of the % of the total CPU resources available in a given 100ms period. + + +## Processors setting [ece-alloc-processors-setting] + +In addition to the [CPU quotas](#ece-alloc-cpu), the `processors` setting also plays a relevant role. + +The allocated `processors` setting originates from Elasticsearch and is responsible for calculating your [thread pools](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-threadpool.html#node.processors). While the CPU quota defines the percentage of the total CPU resources of an allocator that are assigned to an instance, the allocated `processors` define how the thread pools are calculated in Elasticsearch, and therefore how many concurrent search and indexing requests an instance can process. In other words, the CPU ratio defines how fast a single task can be completed, while the `processors` setting defines how many different tasks can be completed at the same time. + +We rely on Elasticsearch and the `-XX:ActiveProcessorCount` JVM setting to automatically detect the allocated `processors`. + +In earlier versions of ECE and Elasticsearch, the [Elasticsearch processors](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-threadpool.html#node.processors) setting was used to configure the allocated `processors` according to the following formula: + +`Math.min(16,Math.max(2,(16*instanceCapacity*1.0/1024/64).toInt))` + +The following table gives an overview of the allocated `processors` that are used to calculate the Elasticsearch [thread pools](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-threadpool.html) based on the preceding formula: + +| instance size | vCPU | +| --- | --- | +| 1024 | 2 | +| 2048 | 2 | +| 4096 | 2 | +| 8192 | 2 | +| 16384 | 4 | +| 32768 | 8 | + +This table also provides a rough indication of what the auto-detected value could be on newer versions of ECE and Elasticsearch. + + +## Storage [ece-alloc-storage] + +ECE has specific [hardware prerequisites](ece-hardware-prereq.md) for storage. Disk space is consumed by system logs, container overhead, and deployment data. + +The main factor for selecting a disk quota is the deployment data, that is, data from your Elasticsearch, Kibana, and APM nodes. The biggest portion of data is consumed by the Elasticsearch nodes. + +::::{note} +ECE uses [XFS](ece-software-prereq.md#ece-xfs) to enforce specific disk space quotas to control the disk consumption for the deployment nodes running on your allocator. +:::: + + +::::{important} +You must use XFS and have quotas enabled on all allocators, otherwise disk usage won’t display correctly. +:::: + + +To calculate the disk quota, use the following formula: + +`Diskquota = ICmultiplier * Deployment RAM` + +`ICmultiplier` is the disk multiplier of the instance configuration that you defined in your ECE environment. + +The default multiplier for `data.default` is 32, which is used for hot nodes. The default multiplier for `data.highstorage` is 64, which is used for warm and cold nodes. The FS multiplier for `data.frozen` is 80, which is used for frozen nodes. + +You can change the value of the disk multiplier at different levels: + +* At the ECE level, check [Edit instance configurations](ece-configuring-ece-instance-configurations-edit.md). +* At the instance level, [log into the Cloud UI](log-into-cloud-ui.md) and proceed as follows: + + 1. From your deployment overview page, find the instance you want and open the instance menu. + 2. Select **Override disk quota**. + 3. Adjust the disk quota to your needs. + + +::::{important} +The override only persists during the lifecycle of the instance container. If a new container is created, for example during a `grow_and_shrink` plan or a vacate operation, the quota is reset to its default. To increase the storage ratio in a persistent way, [edit the instance configurations](ece-configuring-ece-instance-configurations-edit.md). +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-networking-prereq.md b/deploy-manage/deploy/cloud-enterprise/ece-networking-prereq.md new file mode 100644 index 000000000..02d8024ac --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-networking-prereq.md @@ -0,0 +1,74 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-networking-prereq.html +--- + +# Networking prerequisites [ece-networking-prereq] + +The first host you install ECE on initially requires the ports for all roles to be open, which includes the ports for the coordinator, allocator, director, and proxy roles. After you have brought up your initial ECE installation, only the ports for the roles that the initial host continues to hold need to remain open. Before installing a host, make sure that ports 20000, 21000, and 22000 are open for the installation script checks. Port 2375 will also be utilized on each host you install ECE on for internal Docker communication. + +For versions 2.4.0 and 2.4.1, IPv6 should remain enabled on any host with the Proxy role. In 2.4.2 and later, IPv6 can be disabled. + +* [Inbound traffic](#ece-inbound) +* [Outbound traffic](#ece-outbound) +* [Hosts in multiple data centers](#ece-multiple-data-centers) + + +## Inbound traffic [ece-inbound] + +When there are multiple hosts for each role, the inbound networking and ports can be represented by the following diagram: + +![ECE networking and ports](../../../images/cloud-enterprise-ece-networking-ports.png "") + +| **Number** | **Host role** | **Inbound ports** | *Purpose* | +| --- | --- | --- | --- | +| | All | 22 | Installation and troubleshooting SSH access only (TCP)
| +| 2 | Coordinator | 12300/12343, 12400/12443 | Admin API access (HTTP/HTTPS)
| +| 3 | Proxy | 9200, 9243 | Elasticsearch REST API. 9200 is plain text and 9243 is with TLS, also required by load balancers
| +| 3 | Proxy | 9300, 9343 | Elasticsearch transport client. 9300 is plain text and 9343 is with TLS, also required by load balancers
| +| 3 | Proxy | 9400, 9443 | Elasticsearch Cross Cluster Search and Cross Cluster Replication with TLS authentication (9400) or API key authentication (9443), also required by load balancers. Can be blocked if [CCR/CCS](../../remote-clusters/ece-enable-ccs.md) is not used.
| +| 7 | Coordinator | 12400/12443 | Cloud UI console to API (HTTP/HTTPS)
| + +In addition to the following list, you should open 12898-12908 and 13898-13908 on the director host for ZooKeeper leader and election activity. + +| **Number** | **Host role** | **Inbound ports** | *Purpose* | +| --- | --- | --- | --- | +| 1 | Director | 2112 | ZooKeeper ensemble discovery/joining (TCP)
| +| 4 | Director | 12191-12201 | Client forwarder to ZooKeeper, one port per director (TLS tunnels)
| +| 5 | Allocator | 19000-19999 | Elasticsearch node to node and Proxy to Elasticsearch for CCR/CCS (Node Transport 6.x+/TLS 6.x+)
| +| 7 | Coordinator | 22191-22195 | Connections to initial coordinator from allocators and proxies, one port per coordinator, up to five (TCP)
| +| 9 | Proxy | 9200/9243, 9300/9343 | Kibana and Elasticsearch (HTTPS)
| +| 10 | Allocator | 18000-18999 | Constructor to Elasticsearch cluster (HTTPS)
| +| 11 | Allocator | 18000-18999/20000-20999 | Proxy to Elasticsearch/Kibana/APM Server instance (HTTPS/Transport Client 6.x+/TLS 6.x+)
| +| | Allocator | 21000-21999 | APM Server (Instance Monitoring)
| +| 12 | Allocator | 23000-23999 | Elasticsearch node to node and Proxy to Elasticsearch for CCR/CCS using Remote Cluster Security
| +| 13 | Allocator | 14000 | Proxy to Allocator service endpoint (HTTPS)
| +| 14 | Proxy | 14043 | API to Proxy for Allocator service traffic (HTTPS)
| + + +## Outbound traffic [ece-outbound] + +Open these ports for outbound traffic: + +| Host role | Outbound ports | Purpose | +| --- | --- | --- | +| All | 80 | Installation script and docker.elastic.co Docker registry access (HTTP) | +| All | 443 | Installation script and docker.elastic.co Docker registry access (HTTPS) | + +::::{note} +Outbound traffic must also permit connections to the [snapshot repositories](../../tools/snapshot-and-restore/cloud-enterprise.md) you intend to use. Ports depend on the snapshot repository type. Refer to the external supported providers to confirm the exact list of ports. +:::: + + + +## Hosts in multiple data centers [ece-multiple-data-centers] + +A typical ECE installation should be contained within a single data center. We recommend that ECE installations not span different data centers, due to variations in networking latency and bandwidth that cannot be controlled. + +Installation of ECE across multiple data centers might be feasible with sufficiently low latency and high bandwidth, with some restrictions around what we can support. Based on our experience with our hosted Elastic Cloud service, the following is required: + +* A typical network latency between the data centers of less than 10ms round-trip time during pings +* A network bandwidth of at least 10 Gigabit + +If you choose to deploy a single ECE installation across multiple data centers, you might need to contend with additional disruptions due to bandwidth or latency issues. Both ECE and Elasticsearch are designed to be resilient to networking issues, but this resiliency is intended to handle exceptions and should not be depended on as part of normal operations. If Elastic determines during a support case that an issue is related to an installation across multiple data centers, the recommended resolution will be to consolidate your installation into a single data center, with further support limited until consolidation is complete. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-regional-deployment-aliases.md b/deploy-manage/deploy/cloud-enterprise/ece-regional-deployment-aliases.md new file mode 100644 index 000000000..c62edb938 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-regional-deployment-aliases.md @@ -0,0 +1,103 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-regional-deployment-aliases.html +--- + +# Custom endpoint aliases [ece-regional-deployment-aliases] + +Custom aliases for your deployment endpoints on Elastic Cloud Enterprise allow you to have predictable, human-readable URLs that can be shared easily. + +Before setting up your custom alias, your platform administrator must enable the feature. Check [Enable custom endpoint aliases](enable-custom-endpoint-aliases.md) for more information. + + +## Create a custom endpoint alias for a deployment [ece-create-regional-deployment-alias] + +To add an alias to an existing deployment: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Deployments** menu, select a deployment. +3. Under **Custom endpoint alias**, select **Edit**. +4. Define a new alias. Make sure you choose something meaningful to you. + + ::::{tip} + Make the alias as unique as possible to avoid collisions. Aliases might have been already claimed by other users for deployments in the region. + :::: + +5. Select **Update alias**. + + +## Remove a custom endpoint alias [ece-delete-regional-deployment-alias] + +To remove an alias from your deployment, or if you want to re-assign an alias to another deployment, follow these steps: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Deployments** menu, select a deployment. +3. Under **Custom endpoint alias**, select **Edit**. +4. Remove the text from the **Custom endpoint alias** text box. +5. Select **Update alias**. + + +## Using the custom endpoint URL [ece-using-regional-deployment-alias] + +To use your new custom endpoint URL to access your Elastic products, note that each has its own alias to use in place of the default application UUID. For example, if you configured the custom endpoint alias for your deployment to be `test-alias`, the corresponding alias for the Elasticsearch cluster in that deployment is `test-alias.es`. + +::::{note} +You can get the application-specific custom endpoint alias by selecting **Copy endpoint** for that product. It should contain a subdomain for each application type, for example `es`, `kb`, `apm`, or `ent`. +:::: + + + +### With the REST Client [ece-rest-regional-deployment-alias] + +* As part of the host name: + + After configuring your custom endpoint alias, select **Copy endpoint** on the deployment overview page, which gives you the fully qualified custom endpoint URL for that product. + +* As an HTTP request header: + + Alternatively, you can reach your application by passing the application-specific custom endpoint alias, for example, `test-alias.es`, as the value for the `X-Found-Cluster` HTTP header. + + +For more information on setting up a load balancer to ensure proper routing, check [Load balancers](ece-load-balancers.md). + + +### With the `TransportClient` [ece-transport-regional-deployment-alias] + +While the `TransportClient` is deprecated, your custom endpoint aliases still work with it. Similar to the REST Client, there are two ways to use your custom endpoint alias with the `TransportClient`: + +* As part of the host name: + + Similar to HTTP, you can find the fully qualified host on the deployment overview page by selecting **Copy endpoint** next to Elasticsearch. Make sure to remove the unnecessary `https://` prefix as well as the trailing HTTP port. + +* As part of the **Settings**: + + Include the application-specific custom endpoint alias as the value for `request.headers.X-Found-Cluster` setting in place of the `clusterId`: + + ```java + // Build the settings for our client. + String alias = "test-alias.es"; // Your application-specific custom endpoint alias here + String region = "us-east-1"; // Your region here + boolean enableSsl = true; + + Settings settings = Settings.settingsBuilder() + .put("transport.ping_schedule", "5s") + //.put("transport.sniff", false) // Disabled by default and *must* be disabled. + .put("action.bulk.compress", false) + .put("shield.transport.ssl", enableSsl) + .put("request.headers.X-Found-Cluster", alias) + .put("shield.user", "username:password") // your shield username and password + .build(); + + String hostname = alias + "." + region + ".aws.found.io"; + // Instantiate a TransportClient and add the cluster to the list of addresses to connect to. + // Only port 9343 (SSL-encrypted) is currently supported. + Client client = TransportClient.builder() + .addPlugin(ShieldPlugin.class) + .settings(settings) + .build() + .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName(hostname), 9343)); + ``` + + +For more information on configuring the `TransportClient`, see [Configure the Java Transport Client](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-security-transport.html). + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-roles.md b/deploy-manage/deploy/cloud-enterprise/ece-roles.md new file mode 100644 index 000000000..565387cea --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-roles.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-roles.html +--- + +# Separation of roles [ece-roles] + +The separation of roles is required to group components on ECE and prevent conflicting workloads. When you install Elastic Cloud Enterprise on the first host, it is assigned many different host roles: Allocator, coordinator, director, and proxy. This role assignment is required to bring up your initial deployments. In a production environment, some of these roles need to be separated, as their loads scale differently and can create conflicting demands when placed on the same hosts. There are also certain [security implications that are addressed by separating roles](../../security/secure-your-elastic-cloud-enterprise-installation.md#ece-securing-vectors). + +Roles that should not be held by the same host: + +* Allocators and coordinators +* Allocators and directors +* Coordinators and proxies + +If this separation of roles is not possible, fewer hosts that provide substantial hardware resources with fast SSD storage can be used, but we recommend this setup only for development, test, and small-scale use cases. For example, even if you have only three hosts, sharing roles might be feasible in some cases. If SSD-only storage is not feasible, you must separate the ECE management services provided by the coordinators and directors from your proxies and allocators and place them on different hosts that use fast SSD storage. + +Some roles are safe for hosts to hold at the same time: + +* Directors and coordinators (the ECE management services) + +To learn more about how you can assign roles, check [Assign Roles](assign-roles-to-hosts.md). + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-software-prereq.md b/deploy-manage/deploy/cloud-enterprise/ece-software-prereq.md new file mode 100644 index 000000000..3ac08bad9 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-software-prereq.md @@ -0,0 +1,78 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-software-prereq.html +--- + +# Software prerequisites [ece-software-prereq] + +To install ECE, make sure you prepare your environment with the following software. Pay special attention to what Linux kernel and Docker or Podman versions you plan to use and follow our recommendations. Our testing has shown that not all software combinations work well together. + +* [Supported Linux kernel](#ece-linux-kernel) +* [Linux distributions with compatible Docker versions](#ece-linux-docker) +* [Free RAM](#ece-free-ram) +* [XFS](#ece-xfs) + + +## Supported Linux kernel [ece-linux-kernel] + +Elastic Cloud Enterprise requires 3.10.0-1160.31.1 or later on RHEL. + +We recommend using kernel 4.15.x or later on Ubuntu. + +To check your kernel version, run `uname -r`. + +::::{note} +Elastic Cloud Enterprise is not supported on Linux distributions that use [cgroups](https://man7.org/linux/man-pages/man7/cgroups.7.md) version 2. +:::: + + + +## Linux distributions with compatible Docker or Podman versions [ece-linux-docker] + +ECE requires using a supported combination of Linux distribution and Docker or Podman version, following our official Support matrix: + +[https://www.elastic.co/support/matrix#elastic-cloud-enterprise](https://www.elastic.co/support/matrix#elastic-cloud-enterprise) + +1. Check your operating system: + + ```sh + cat /etc/os-release + ``` + +2. Check whether Docker or Podman is installed and its version is compatible with ECE: + + ```sh + docker --version + ``` + + ```sh + podman --version + ``` + + +::::{note} +Elastic Cloud Enterprise does not support Amazon Linux. +:::: + + + +## Free RAM [ece-free-ram] + +ECE requires at least 8GB of free RAM. Check how much free memory you have: + +```sh +free -h +``` + + +## XFS [ece-xfs] + +XFS is required if you want to use disk space quotas for Elasticsearch data directories. + +Disk space quotas set a limit on the amount of disk space an Elasticsearch cluster node can use. Currently, quotas are calculated by a static ratio of 1:32, which means that for every 1 GB of RAM a cluster is given, a cluster node is allowed to consume 32 GB of disk space. + +::::{important} +You must use XFS and have quotas enabled on all allocators, otherwise disk usage won’t display correctly. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-sysconfig.md b/deploy-manage/deploy/cloud-enterprise/ece-sysconfig.md new file mode 100644 index 000000000..7815d902a --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-sysconfig.md @@ -0,0 +1,24 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-sysconfig.html +--- + +# System configuration [ece-sysconfig] + +Check the following requirements before installing ECE. + + +## Time synchronization [ece-sysconfig-time] + +A time synchronization daemon such as NTP or Chrony must be functioning on the system to keep the time in sync. This is especially critical for virtualized and cloud-hosted machine instances. + +::::{warning} +ECE currently requires setting server hosts to UTC time. If you use non-UTC time on your hosts, some areas of the ECE UI will not function correctly. +:::: + + + +## Disabled nscd daemon [ece-sysconfig-nscd] + +On Linux systems, the [name service cache daemon (nscd)](https://linux.die.net/man/8/nscd) can prevent ECE from installing successfully. For example, it might block various networking components from functioning properly, including the container’s ability to resolve connections to its host. Before running the ECE install process this service should be disabled on your system. The nscd daemon needs to be permanently stopped, even after ECE installation. + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-users-permissions.md b/deploy-manage/deploy/cloud-enterprise/ece-users-permissions.md new file mode 100644 index 000000000..8a0c7014c --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-users-permissions.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-users-permissions.html +--- + +# Users and permissions prerequisites [ece-users-permissions] + +The following users and permissions are required: + +* To prepare your environment: A user with `sudo` permissions, such as the *ubuntu* user provided on Ubuntu. +* To install ECE: A user with a UID and GID greater than or equal to 1000 who is part of the `docker` group. You must not install ECE as the `root` user. + +You can find out information about a user with the `id` command: + +``` +id +uid=1000(elastic) gid=1000(elastic) groups=1000(elastic), +4(adm),20(dialout),24(cdrom),25(floppy), +27(sudo),29(audio),30(dip),44(video), +46(plugdev),102(netdev),112(libvirtd),1001(docker) +``` +In this example, the user `elastic` with a UID and GID of 1000 belongs to both the `sudo` and the `docker` groups. + +::::{note} +For ECE installation with Podman, the user does not need to be added to the `docker` group. Instead, the user must be added to the `podman` group. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/ece-wildcard-dns.md b/deploy-manage/deploy/cloud-enterprise/ece-wildcard-dns.md new file mode 100644 index 000000000..8cda2e978 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/ece-wildcard-dns.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-wildcard-dns.html +--- + +# Wildcard DNS record [ece-wildcard-dns] + +::::{warning} +We do not recommend using `ip.es.io` for production systems. Please set up your own domain name and DNS resolver for production. We do not guarantee uptime with `ip.es.io`. +:::: + + +By default, Elastic Cloud Enterprise uses the external `ip.es.io` service provided by Elastic to resolve virtual Elasticsearch cluster host names in compliance with RFC1918. The service works by resolving host names of the form `.ip.es.io` to ``. In the case of Elastic Cloud Enterprise, each cluster is assigned a virtual host name of the form `..ip.es.io:`, such as `6dfc65aae62341e18a8b7692dcc97186.10.8.156.132.ip.es.io:9243`. The `ip.es.io` service simply resolves the virtual host name of the cluster to the proxy address which is specified during installation, `10.8.156.132` in our example, so that client requests are sent to the proxy. The proxy then extracts the cluster ID from the virtual host name of the cluster and uses its internal routing table to route the request to the right allocator. + +The `ip.es.io` service is provided to help you evaluate Elastic Cloud Enterprise without having to set up DNS records for your environment. You must set up a wildcard DNS record for your production system. You typically set up a wildcard DNS record that resolves to the proxy host or to a load balancer if you set up multiple proxies fronted by a load balancer. You can create both a wildcard DNS entry for your endpoints and a wildcard TLS/SSL certificate, so that you can create multiple clusters without the need for further DNS or TSL/SSL modifications. Simply configure your DNS to point to your load balancers and install your certificates on them, so that communication with the cluster is secure. + +A wildcard certificate is enabled based on the deployment domain name. For more information on modifying the deployment domain name, check [Configure endpoints](change-endpoint-urls.md). The deployment domain name also determines the endpoint URLs that are displayed in the Cloud UI. + diff --git a/deploy-manage/deploy/cloud-enterprise/edit-stack-settings.md b/deploy-manage/deploy/cloud-enterprise/edit-stack-settings.md new file mode 100644 index 000000000..4fb14ed6b --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/edit-stack-settings.md @@ -0,0 +1,32 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/editing-user-settings.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-add-user-settings.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-kibana-settings.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-apm-settings.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-enterprise-search-settings.html +--- + +# Edit stack settings + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/339 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/editing-user-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-add-user-settings.md +% Notes: instructions only, link to reference +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-manage-kibana-settings.md +% Notes: instructions only, link to reference +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-manage-apm-settings.md +% Notes: instructions only, link to reference +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-manage-enterprise-search-settings.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ece-edit-apm-fleet-tls$$$ + +$$$ece-edit-apm-standalone-settings-ece$$$ + diff --git a/deploy-manage/deploy/cloud-enterprise/enable-custom-endpoint-aliases.md b/deploy-manage/deploy/cloud-enterprise/enable-custom-endpoint-aliases.md new file mode 100644 index 000000000..eba4241ce --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/enable-custom-endpoint-aliases.md @@ -0,0 +1,38 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-deployment-aliases.html +--- + +# Enable custom endpoint aliases [ece-configuring-deployment-aliases] + +Custom endpoint aliases allow users to replace the UUID for each application with a human readable string. Platform administrators must enable this feature to allow deployment managers to create and modify aliases for their deployments. + +::::{note} +You need to update your proxy certificates to support this feature. +:::: + + +After installing or upgrading to version 2.10 or later: + +1. [Login to the Cloud UI](log-into-cloud-ui.md) +2. [Update your proxy certificate(s)](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md). In addition to currently configured domains, additional SAN entries must be configured for each application-specific subdomain: + + ::::{note} + If you are not using wildcard certificates, you need to repeat this process for each deployment to account for specific aliases. + :::: + + + * For Elasticsearch, the certificate needs to allow for ***.es.** + * For Kibana, the certificate needs to allow for ***.kb.** + * For APM, the certificate needs to allow for ***.apm.** + * For Enterprise Search or AppSearch, the certificate needs to allow for ***.ent.** + * For Fleet, the certificate needs to allow for ***.fleet.** + +3. In the **Platform** menu, select **Settings**. +4. Under the **Enable custom endpoint alias naming**, toggle the setting to allow platform administrators and deployment managers to choose a simplified, unique URL for the endpoint. + +If you do not perform these steps, application endpoints will behave as they did in versions before 2.10. + +To learn about setting up custom endpoint aliases for your deployments, check [Custom endpoint aliases](ece-regional-deployment-aliases.md). + + diff --git a/deploy-manage/deploy/cloud-enterprise/find-cloud-id.md b/deploy-manage/deploy/cloud-enterprise/find-cloud-id.md new file mode 100644 index 000000000..9fbae64b5 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/find-cloud-id.md @@ -0,0 +1,69 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-cloud-id.html +--- + +# Find your Cloud ID [ece-cloud-id] + +The Cloud ID reduces the number of steps required to start sending data from Beats or Logstash to your hosted Elasticsearch cluster on Elastic Cloud Enterprise. Because we made it easier to send data, you can start exploring visualizations in Kibana on Elastic Cloud Enterprise that much more quickly. + +:::{image} ../../../images/cloud-enterprise-ec-ce-cloud-id-beats-logstash.png +:alt: Exploring data from Beats or Logstash in Kibana after sending it to a hosted Elasticsearch cluster +::: + +The Cloud ID works by assigning a unique ID to your hosted Elasticsearch cluster on Elastic Cloud Enterprise. All deployments automatically get a Cloud ID. + +You include your Cloud ID along with your Elastic Cloud Enterprise user credentials (defined in `cloud.auth`) when you run Beats or Logstash locally, and then let Elastic Cloud Enterprise handle all of the remaining connection details to send the data to your hosted cluster on Elastic Cloud Enterprise safely and securely. + +:::{image} ../../../images/cloud-enterprise-ec-ce-cloud-id.png +:alt: The Cloud ID and `elastic` user information shown when you create a deployment +::: + + +## What are Beats and Logstash? [ece_what_are_beats_and_logstash] + +Not sure why you need Beats or Logstash? Here’s what they do: + +* [Beats](https://www.elastic.co/products/beats) is our open source platform for single-purpose data shippers. The purpose of Beats is to help you gather data from different sources and to centralize the data by shipping it to Elasticsearch. Beats install as lightweight agents and ship data from hundreds or thousands of machines to your hosted Elasticsearch cluster on Elastic Cloud Enterprise. If you want more processing muscle, Beats can also ship to Logstash for transformation and parsing before the data gets stored in Elasticsearch. +* [Logstash](https://www.elastic.co/products/logstash) is an open source, server-side data processing pipeline that ingests data from a multitude of sources simultaneously, transforms it, and then sends it to your favorite place where you stash things, here your hosted Elasticsearch cluster on Elastic Cloud Enterprise. Logstash supports a variety of inputs that pull in events from a multitude of common sources — logs, metrics, web applications, data stores, and various AWS services — all in continuous, streaming fashion. + + +## Before you begin [ece_before_you_begin_16] + +To use the Cloud ID, you need: + +* A deployment with an Elasticsearch cluster to send data to. +* Beats or Logstash, installed locally wherever you want to send data from. +* To configure Beats or Logstash, you need: + + * The unique Cloud ID for your deployment, available from the deployment overview page. + * A user ID and password that has permission to send data to your cluster. + + In our examples, we use the `elastic` superuser that every Elasticsearch cluster comes with. The password for the `elastic` user is provided when you create a deployment (and can also be [reset](../../users-roles/cluster-or-deployment-auth/built-in-users.md) if you forget it). On a production system, you should adapt these examples by creating a user that can write to and access only the minimally required indices. For each Beat, review the specific feature and role table, similar to the one in [Metricbeat](https://www.elastic.co/guide/en/beats/metricbeat/current/feature-roles.html) documentation. + + + +## Configure Beats with your Cloud ID [ece-cloud-id-beats] + +The following example shows how you can send operational data from Metricbeat to Elastic Cloud Enterprise by using the Cloud ID. Any of the available Beats will work, but we had to pick one for this example. + +::::{tip} +For others, you can learn more about [getting started](https://www.elastic.co/guide/en/beats/libbeat/current/getting-started.html) with each Beat. +:::: + + +To get started with Metricbeat and Elastic Cloud Enterprise: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. [Create a new deployment](create-deployment.md) and copy down the password for the `elastic` user. +3. On the deployment overview page, copy down the Cloud ID. +4. Set up the Beat of your choice, such as [Metricbeat](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-installation-configuration.html). +5. [Configure the Beat output to send to Elastic Cloud](https://www.elastic.co/guide/en/beats/metricbeat/current/configure-cloud-id.html). + + ::::{note} + Make sure you replace the values for `cloud.id` and `cloud.auth` with your own information. + :::: + +6. Open Kibana and explore! + +Metricbeat creates a data view (formerly *index pattern*) with defined fields, searches, visualizations, and dashboards that you can start exploring in Kibana. Look for information related to system metrics, such as CPU usage, utilization rates for memory and disk, and details for processes. diff --git a/deploy-manage/deploy/cloud-enterprise/find-endpoint-url.md b/deploy-manage/deploy/cloud-enterprise/find-endpoint-url.md new file mode 100644 index 000000000..d9806daa7 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/find-endpoint-url.md @@ -0,0 +1,66 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-connect.html +--- + +# Find your endpoint URL [ece-connect] + +To connect to your Elasticsearch cluster, you need to look up the the cluster Endpoint URL: + +1. [Log into the Cloud UI](log-into-cloud-ui.md), if you aren’t logged in already. +2. On the **Deployments** page, select one of your deployments. +3. Under **Endpoints**, the endpoint link for Elasticsearch is listed. If you already enabled Kibana, the endpoint where you can access Kibana is listed as well. Select the Elasticsearch endpoint to connect to the cluster in your browser. You should get the following standard message: + + ```json + { + "name" : "instance-0000000000", + "cluster_name" : "85943ce00a934471cb971009e73d2d39", + "cluster_uuid" : "0z2PsOX1TCGSk7PKgB9ajg", + "version" : { + "number" : "2.4.1", + "build_hash" : "c67dc32e24162035d18d6fe1e952c4cbcbe79d16", + "build_timestamp" : "2016-09-27T18:57:55Z", + "build_snapshot" : false, + "lucene_version" : "5.5.2" + }, + "tagline" : "You Know, for Search" + } + ``` + + If you are prompted for authentication credentials, you are trying to connect to a cluster that already has Shield enabled or that uses the X-Pack security features. Specify the credentials of a user, such as the default `elastic` user, to connect. + + +Currently, we support the following ways of connecting to an Elasticsearch cluster: + +RESTful API with JSON over HTTP and HTTPS +: Used by the `curl` command and most programming languages that aren’t Java. To interact with your cluster, use your Elasticsearch cluster endpoint information from the **Overview** page in the Cloud UI. Port 9200 is used for plain text, insecure HTTP connections while port 9243 is used for HTTPS. Using HTTPS is generally recommended, as it is more secure. + + If this is your first time using Elasticsearch, you can try out some `curl` commands to become familiar with the basics. If you’re on an operating system like macOS or Linux, you probably already have the `curl` command installed. For example, to connect to your cluster from the command line over HTTPS with the `curl` command: + + ```sh + curl --cacert /path/to/elastic-ece-ca-cert.pem https://45e366dc3a4142e9a4d6bbe3c7eedee7.192.168.43.10.ip.es.io:9243 + { + "name" : "instance-0000000000", + "cluster_name" : "45e366dc3a4142e9a4d6bbe3c7eedee7", + "version" : { + "number" : "2.3.5", + "build_hash" : "90f439ff60a3c0f497f91663701e64ccd01edbb4", + "build_timestamp" : "2016-07-27T10:36:52Z", + "build_snapshot" : false, + "lucene_version" : "5.5.0" + }, + "tagline" : "You Know, for Search" + } + ``` + + To make this `curl` command work with your cluster, you need to replace the endpoint URL with your own. + + +::::{tip} +If you created a cluster on Elasticsearch 5.0 or later or if you already enabled the security features, you must include authentication details with the -u parameter. For example: `curl -u elastic:W0UN0Rh9WX8eKeN69grVk3bX https://85943ce00a934471cb971009e73d2d39.us-east-1.aws.found.io:9243`. You can check [Get existing ECE security certificates](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md) for how to get the CA certificate (`elastic-ece-ca-cert.pem` in this example) and use it to connect to the Elasticsearch cluster. +:::: + + +Ingest methods +: There are several ways to connect to Elasticsearch, perform searches, insert data, and more. See the [ingesting data](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-cloud-ingest-data.html) documentation. + diff --git a/deploy-manage/deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-cloud.md b/deploy-manage/deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-cloud.md new file mode 100644 index 000000000..c41e86540 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-cloud.md @@ -0,0 +1,84 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-using-podman-cloud.html +--- + +# Fresh installation of ECE using Podman hosts cloud [ece-install-using-podman-cloud] + +This section provides guidelines and recommendations to install ECE using a Podman-based environment. The recommended approach consists of two (2) high-level steps. + +**Step 1**: Install ECE. + +**Step 2**: Add additional Podman hosts + +::::{note} +When copy-pasting commands, verify that characters like quotes (“) are encoded correctly in the console where you copy the command to. +:::: + + +::::{note} +Steps that run commands starting with `sudo` can be run as any sudoers user. Otherwise, the corresponding user is mentioned as part of the step description. +:::: + + +::::{note} +Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. +:::: + + +1. Install ECE + + Use the ECE installer script together with the `--podman` flag. + + Refer to the official [Install ECE online](install-ece-onprem.md) documentation to adapt the command line parameters to your environment. + + [JVM heap sizes](ece-jvm.md) describes recommended JVM options. + + ::::{important} + Important while running `./elastic-cloud-enterprise.sh` + + * Execute the installer script as user `elastic`. + * Ensure to use an installer script that supports podman. + * Make sure you use `--podman`. + * Use `--cloud-enterprise-version VERSION_NAME` to specify the correct version. + * If you are using SELinux, make sure you also use `--selinux`. + + :::: + +2. Add additional Podman hosts + + Refer to the official [Install Elastic Cloud Enterprise on an additional host](install-ece-on-additional-hosts.md) and [Install ECE online](install-ece-onprem.md) documentation to adapt the command line parameters to your environment including fetching the role token. + + [JVM heap sizes](ece-jvm.md) describes recommended JVM options. + + ::::{important} + Important while running `./elastic-cloud-enterprise.sh` + + * Execute the installer script as user `elastic`. + * Ensure to use an installer script that supports podman. + * Make sure you use `--podman`. + * If you are using SELinux, make sure you also use `--selinux`. + * To fetch a role token following the [Generate Roles Tokens](generate-roles-tokens.md) guidelines, you need to send a JSON token to the admin console. Double check the correct format of the roles. Roles are a list of individual strings in quotes, **NOT a single string**. + + **Example** + + ```json + { "persistent": true, "roles": [ "allocator","coordinator","director","proxy" ] } + ``` + + * The ECE version of the additional host must be the same as the version used in step 2. Use `--cloud-enterprise-version VERSION_NAME` to specify the correct version. + * Make sure to apply the roles to the additional host. The value for the `--roles` flag is a single string. + + **Example** + + ```sh + --roles "allocator,coordinator,director,proxy" + ``` + + + :::: + + + To add a new allocator, use `--roles "allocator"`. To add a new coordinator, director, proxy, and allocator, use `--roles "allocator,coordinator,director,proxy"` + + diff --git a/deploy-manage/deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-onprem.md b/deploy-manage/deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-onprem.md new file mode 100644 index 000000000..290c64fa8 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-onprem.md @@ -0,0 +1,84 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-using-podman-onprem.html +--- + +# Fresh installation of ECE using Podman hosts onprem [ece-install-using-podman-onprem] + +This section provides guidelines and recommendations to install ECE using a Podman-based environment. The recommended approach consists of two (2) high-level steps. + +**Step 1**: Install ECE. + +**Step 2**: Add additional Podman hosts + +::::{note} +When copy-pasting commands, verify that characters like quotes (“) are encoded correctly in the console where you copy the command to. +:::: + + +::::{note} +Steps that run commands starting with `sudo` can be run as any sudoers user. Otherwise, the corresponding user is mentioned as part of the step description. +:::: + + +::::{note} +Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. +:::: + + +1. Install ECE + + Use the ECE installer script together with the `--podman` flag. + + Refer to the official [Install ECE online](install-ece-onprem.md) documentation to adapt the command line parameters to your environment. + + [JVM heap sizes](ece-jvm.md) describes recommended JVM options. + + ::::{important} + Important while running `./elastic-cloud-enterprise.sh` + + * Execute the installer script as user `elastic`. + * Ensure to use an installer script that supports podman. + * Make sure you use `--podman`. + * Use `--cloud-enterprise-version VERSION_NAME` to specify the correct version. + * If you are using SELinux, make sure you also use `--selinux`. + + :::: + +2. Add additional Podman hosts + + Refer to the official [Install Elastic Cloud Enterprise on an additional host](install-ece-on-additional-hosts.md) and [Install ECE online](install-ece-onprem.md) documentation to adapt the command line parameters to your environment including fetching the role token. + + [JVM heap sizes](ece-jvm.md) describes recommended JVM options. + + ::::{important} + Important while running `./elastic-cloud-enterprise.sh` + + * Execute the installer script as user `elastic`. + * Ensure to use an installer script that supports podman. + * Make sure you use `--podman`. + * If you are using SELinux, make sure you also use `--selinux`. + * To fetch a role token following the [Generate Roles Tokens](generate-roles-tokens.md) guidelines, you need to send a JSON token to the admin console. Double check the correct format of the roles. Roles are a list of individual strings in quotes, **NOT a single string**. + + **Example** + + ```json + { "persistent": true, "roles": [ "allocator","coordinator","director","proxy" ] } + ``` + + * The ECE version of the additional host must be the same as the version used in step 2. Use `--cloud-enterprise-version VERSION_NAME` to specify the correct version. + * Make sure to apply the roles to the additional host. The value for the `--roles` flag is a single string. + + **Example** + + ```sh + --roles "allocator,coordinator,director,proxy" + ``` + + + :::: + + + To add a new allocator, use `--roles "allocator"`. To add a new coordinator, director, proxy, and allocator, use `--roles "allocator,coordinator,director,proxy"` + + diff --git a/deploy-manage/deploy/cloud-enterprise/generate-roles-tokens.md b/deploy-manage/deploy/cloud-enterprise/generate-roles-tokens.md new file mode 100644 index 000000000..8dbffee49 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/generate-roles-tokens.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-generate-roles-token.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-revoke-roles-token.html +--- + +# Generate roles tokens + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/339 + +% Scope notes: merge these two pages + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-generate-roles-token.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-revoke-roles-token.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/identify-deployment-scenario.md b/deploy-manage/deploy/cloud-enterprise/identify-deployment-scenario.md new file mode 100644 index 000000000..c25b3a874 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/identify-deployment-scenario.md @@ -0,0 +1,73 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-deploy-scenario.html +--- + +# Identify the deployment scenario [ece-deploy-scenario] + +Before you start deploying ECE, choose the deployment scenario that best fits your use case. All deployment scenarios have 3 director nodes for [high availability](ece-ha.md). + + +## Small deployment [ece_small_deployment] + +The type of deployment is recommended for development, test, and small-scale use cases. You need: + +* 3 hosts with 128 GB RAM +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-3.png +:alt: A small baseline installation with three hosts across three availability zones +::: + +* This type of installation is **not recommended for high-traffic workloads**. +* Avoid ECE installations with **spinning disks** as these are not supported when you run allocators and control plane on the same server. +* Note that the small-size ECE installation keeps the directors and coordinators roles (ECE management services) on the same hosts as your allocators and proxies. + +You can proceed with this scenario and install ECE with [Ansible](alternative-install-ece-with-ansible.md), on a [public cloud](install-ece-on-public-cloud.md), or on [your own premises](install-ece-on-own-premises.md). + + +## Medium deployment [ece_medium_deployment] + +This type of deployment is recommended for many production setups. You need: + +* 3 hosts with at least 32 GB RAM each for directors and coordinators (ECE management services) +* 3 hosts for allocators, each with one of the following RAM configurations: + + * 1 x 256 GB RAM + * 2 x 128 GB RAM + * 4 x 64 GB RAM + +* 3 hosts with 16 GB RAM each for proxies +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-6.png +:alt: A medium installation with nine to twelve hosts across three availability zones +::: + +* Monitor the load on proxies and make sure the volume of user requests routed by the proxies does not affect the resources available to the ECE management services. +* Note that the large-sized Elastic Cloud Enterprise installation separates the allocator and proxy roles from the director and coordinator roles (ECE management services). + +You can proceed with this scenario and install ECE with [Ansible](alternative-install-ece-with-ansible.md), on a [public cloud](install-ece-on-public-cloud.md), or on [your own premises](install-ece-on-own-premises.md). + + +## Large deployment [ece_large_deployment] + +This type of deployment is recommended for deployments with significant overall search and indexing throughput. You need: + +* 3 hosts with at least 64 GB RAM each for directors and coordinators (ECE management services) +* 3 hosts for allocators, each with one of the following RAM configurations: + + * 1 x 256 GB RAM + * 2 x 128 GB RAM + * 4 x 64 GB RAM + +* 3 hosts with 16 GB RAM each for proxies +* 3 availability zones + +:::{image} ../../../images/cloud-enterprise-ece-pb-9.png +:alt: A large installation with nine to twelve hosts across three availability zones +::: + +Note that the large-sized Elastic Cloud Enterprise installation separates the allocator and proxy roles from the director and coordinator roles (ECE management services). + +You can proceed with this scenario and install ECE with [Ansible](alternative-install-ece-with-ansible.md), on a [public cloud](install-ece-on-public-cloud.md), or on [your own premises](install-ece-on-own-premises.md). diff --git a/deploy-manage/deploy/cloud-enterprise/install-ece-cloud.md b/deploy-manage/deploy/cloud-enterprise/install-ece-cloud.md new file mode 100644 index 000000000..501b8fa54 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/install-ece-cloud.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-cloud.html +--- + +# Install ECE cloud [ece-install-cloud] + +Choose the Elastic Cloud Enterprise deployment scenario that best fits your business needs: + +* [Deploy a small installation](deploy-small-installation-cloud.md): For development, test, and small-scale use cases. +* [Deploy a medium installation](deploy-medium-installation-cloud.md): For many production setups. +* [Deploy a large installation](deploy-large-installation-cloud.md): For deployments with significant overall search and indexing throughput. +* [Deploy using Podman](fresh-installation-of-ece-using-podman-hosts-cloud.md): Fresh installation of ECE using Podman hosts. + + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/install-ece-on-additional-hosts.md b/deploy-manage/deploy/cloud-enterprise/install-ece-on-additional-hosts.md new file mode 100644 index 000000000..9d1506d83 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/install-ece-on-additional-hosts.md @@ -0,0 +1,32 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-installing-additional.html +--- + +# Install ECE on additional hosts [ece-installing-additional] + +You can install Elastic Cloud Enterprise on additional hosts if you want: + +* More processing capacity for Elasticsearch nodes in your deployment. You can add a host by installing Elastic Cloud Enterprise on it and then [assign the allocator role](assign-roles-to-hosts.md) in the Cloud UI. +* To [create a deployment](create-deployment.md) that is fault-tolerant, with enough resources available to support multiple availability zones. + +To install Elastic Cloud Enterprise on additional hosts: + +1. Download and run the installation script on each additional host. Include the `--coordinator-host HOST_IP` and `--roles-token 'TOKEN'` parameters provided to you when you installed on the first host, otherwise the new host will be rejected. As well, `VERSION_NAME` must match your current ECE installation version for the process to succeed. + + ``` + bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install + --coordinator-host HOST_IP + --roles-token 'TOKEN' + --cloud-enterprise-version VERSION_NAME + ``` + If you are creating a larger Elastic Cloud Enterprise installation: + + * Make your installation [fault tolerant or highly available](ece-ha.md) by determining the failure domain for each host and using the `--availability-zone ZONE_NAME` parameter to specify the name of an [availability zone](ece-ha.md). For production systems, hosts should go into three different availability zones. For example, including the parameter `--availability-zone ece-zone-1c` when you install on additional hosts will assign each host to availability zone `ece-zone-1c`. + * To simplify the steps for assigning roles so that you do not have to change the roles in the Cloud UI later on, include the `--roles` parameter. For example, to bring up additional allocators to scale out your installation, specify the `--roles "allocator"` parameter. You do need to [generate a roles token](generate-roles-tokens.md) that has the right permissions for this to work; the token generated during the installation on the first host will not suffice. + + +After installation completes, additional hosts come online with some roles assigned to them already. If you did not specify additional roles with the `--roles` parameter, you can [assign new roles to nodes](assign-roles-to-hosts.md) in the Cloud UI later. + +For automation purposes, you can set up a DNS hostname for the coordinator host. Setting up a round robin CNAME should be enough to ensure that the value does not need to change in automation scripts. Any one coordinator can be used, including the initial coordinator (the first host you installed Elastic Cloud Enterprise on). + diff --git a/deploy-manage/deploy/cloud-enterprise/install-ece-on-own-premises.md b/deploy-manage/deploy/cloud-enterprise/install-ece-on-own-premises.md new file mode 100644 index 000000000..cf05d016b --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/install-ece-on-own-premises.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-your-infra.html +--- + +# Install ECE on your own premises [ece-install-your-infra] + +Before you start, make sure that your existing infrastructure meets the [requirements](prepare-environment.md). + +ECE supports a [wide range of OS versions](https://www.elastic.co/support/matrix). Here are some OS-specific instructions for preparing your hosts; other versions will be similar: + +* [Ubuntu 20.04 LTS (Focal Fossa) and 22.04 LTS (Jammy Jellyfish)](configure-host-ubuntu-onprem.md) +* [Red Hat Enterprise Linux (RHEL) 8 and 9, and Rocky Linux 8 and 9](configure-host-rhel-onprem.md) +* [SUSE Linux Enterprise Server (SLES) 12 SP5 and 15](configure-host-suse-onprem.md) + +After your hosts are prepared, choose your preferred installation type: + +* [Install ECE online](install-ece-onprem.md) +* [Install ECE offline](air-gapped-install.md) + +::::{note} +In these pages we frequently refer to [Docker](https://www.docker.com/), as its currently the most common container engine, but these instructions are generally valid for [Podman](https://podman.io/) as well, with `podman` replacing `docker` in commands as appropriate. +:::: + + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/install-ece-on-public-cloud.md b/deploy-manage/deploy/cloud-enterprise/install-ece-on-public-cloud.md new file mode 100644 index 000000000..36d082621 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/install-ece-on-public-cloud.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-public.html +--- + +# Install ECE on a Public Cloud [ece-install-public] + +You can deploy ECE on any of the following cloud providers: + +* Amazon Web Services (AWS) +* Google Cloud Platform (GCP) +* Microsoft Azure + +with one of the following operating systems: + +* [Ubuntu 20.04 LTS (Focal Fossa) and Ubuntu 22.04 LTS (Jammy Jellyfish)](configure-host-ubuntu-cloud.md) +* [Red Hat Enterprise Linux (RHEL) 8 and 9](configure-host-rhel-cloud.md) +* [Rocky Linux 8 and 9](configure-host-rhel-cloud.md) +* [SUSE Linux Enterprise Server (SLES) 12 SP5 and 15](configure-host-suse-cloud.md) + +::::{important} +Cloud providers default provide automatic operating system patching for their virtual machines. We strongly recommend disabling this feature to avoid potential data loss and installation failure. All patching should be done via [Perform host maintenance](../../maintenance/ece/perform-ece-hosts-maintenance.md). +:::: + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/install-ece-onprem.md b/deploy-manage/deploy/cloud-enterprise/install-ece-onprem.md new file mode 100644 index 000000000..a7f52b8cf --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/install-ece-onprem.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-onprem.html +--- + +# Install ECE onprem [ece-install-onprem] + +Choose the Elastic Cloud Enterprise deployment scenario that best fits your business needs: + +* [Deploy a small installation](deploy-small-installation-onprem.md): For development, test, and small-scale use cases. +* [Deploy a medium installation](deploy-medium-installation-onprem.md): For many production setups. +* [Deploy a large installation](deploy-large-installation-onprem.md): For deployments with significant overall search and indexing throughput. +* [Deploy using Podman](fresh-installation-of-ece-using-podman-hosts-onprem.md): Fresh installation of ECE using Podman hosts. + + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/install.md b/deploy-manage/deploy/cloud-enterprise/install.md new file mode 100644 index 000000000..63076e676 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/install.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-installing.html +--- + +# Install [ece-installing] + +Before you start, make sure you [identify your deployment scenario](identify-deployment-scenario.md) and [prepare your hosts](prepare-environment.md). + +You can get ECE up and running using the official bash script on a [public cloud](install-ece-on-public-cloud.md) or on [your own premises](install-ece-on-own-premises.md). Alternatively, you can install ECE with the [Ansible](alternative-install-ece-with-ansible.md) playbook. The ECE Ansible playbook is a community project, supported by Elastic, aimed at installing ECE at scale. + +Once you have installed ECE, check some final [post-installation steps](post-installation-steps.md) to get ready for production. + +::::{tip} +This outline pertains to troubleshooting on the container engine level. The following outline is structured according to [Docker](https://www.docker.com/) as the most common engine but is also valid for [Podman](https://podman.io/), replacing out commands as needed. +:::: + + +::::{note} +In these pages we frequently refer to [Docker](https://www.docker.com/), as its currently the most common container engine, but these instructions are generally valid for [Podman](https://podman.io/) as well, with `podman` replacing `docker` in commands as appropriate. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/keep-track-of-deployment-activity.md b/deploy-manage/deploy/cloud-enterprise/keep-track-of-deployment-activity.md new file mode 100644 index 000000000..22bb62257 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/keep-track-of-deployment-activity.md @@ -0,0 +1,42 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-activity-page.html +--- + +# Keep track of deployment activity [ece-activity-page] + +The deployment **Activity** page gives you a convenient way to follow all configuration changes that have been applied to your deployment, including which resources were affected, when the changes were applied, who initiated the changes, and whether or not the changes were successful. You can also select **Details** for an expanded, step-by-step view of each change applied to each deployment resource. + +To view the activity for a deployment: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. In your deployment menu, select **Activity**. +4. You can: + + 1. View the activity for all deployment resources (the default). + 2. Use one of the available filters to view configuration changes by status or type. You can use the query field to create a custom search. Select the filter buttons to get examples of the query format. + 3. Select one of the resource filters to view activity for only that resource type. + + +:::{image} ../../../images/cloud-enterprise-ec-ce-activity-page.png +:alt: The Activity page +::: + +In the table columns you find the following information: + +Change +: Which deployment resource the configuration change was applied to. + +Summary +: A summary of what change was applied, when the change was performed, and how long it took. + +Applied by +: The user who submitted the configuration change. `System` indicates configuration changes initiated automatically by the Elastic Cloud Enterprise platform. + +Actions +: Select **Details** for an expanded view of each step in the configuration change, including the start time, end time, and duration. You can select **Reapply** to re-run the configuration change. + diff --git a/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md b/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md new file mode 100644 index 000000000..414f7d31a --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-login.html +--- + +# Log into the Cloud UI [ece-login] + +To access the Cloud UI in a web browser: + +1. Connect to one of the URLs provided at the end of the installation process on your first host, replacing `FIRST_HOST` with the correct IP address or DNS hostname. + + ```sh + http://FIRST_HOST:12400 + https://FIRST_HOST:12443 + ``` + + Secure access through the HTTPS protocol is available with certificates generated during the installation of Elastic Cloud Enterprise, but will prompt you with a warning in your browser. To avoid this warning, you can add [your own TLS/SSL security certificates](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md). If you are on AWS and can’t access the Cloud UI, [check if the URL points to a private IP address](../../../troubleshoot/deployments/cloud-enterprise/common-issues.md#ece-aws-private-ip). + +2. Log in as user `admin` with the credentials provided. +3. On your first login, agree to the software license agreement to continue. You can opt out of sharing some basic usage statistics with Elastic. [Here is what we collect.](statistics-collected-by-cloud-enterprise.md) + +The Cloud UI displays the available deployments and some important information about them. Three deployments are always shown: + +* `admin-console-elasticsearch`: Backs the Cloud UI itself. +* `logging-and-metrics`: Collects logs and performance metrics for your ECE installation. You must not use this deployment to index monitoring data from your own Elasticsearch clusters or use it to index data from Beats and Logstash. Always create a separate, dedicated monitoring deployment for your own use. +* `security`: Stores all security-related configurations. + diff --git a/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md b/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md new file mode 100644 index 000000000..7ae5459ee --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md @@ -0,0 +1,442 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-elastic-stack.html +--- + +# Manage Elastic Stack versions [ece-manage-elastic-stack] + +Elastic Cloud Enterprise ships with a number of different versions of the Elastic Stack containing Elasticsearch and Kibana. Periodically, you might need to manage Elastic Stack versions for one of the following reasons: + +* To add new versions of the Elastic Stack as they become available +* To obtain information about existing Elastic Stack versions +* To update existing versions of the Elastic Stack +* To add the Elastic Stack versions that shipped with a version of ECE that you upgraded to + +New or updated versions of the Elastic Stack must be prepared to work with Elastic Cloud Enterprise and are provided as packs that you can download. + +::::{important} +Elasticsearch 7.8 and later comes with Index Lifecycle Management (ILM) always enabled. Before upgrading to 7.8 or later, to avoid any unpredictable behavior it is important to configure hot-warm clusters on Elastic Cloud Enterprise with ILM rather than index curation. Check [migrate to index lifecycle management](../../../manage-data/lifecycle/index-lifecycle-management.md) for existing clusters, and [configure index management](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-index-management.html) for new clusters. +:::: + + + +## Most recent Elastic Stack packs [ece_most_recent_elastic_stack_packs] + +The following are the most recently released Elastic Stack packs for version 8.x, 7.x, and 6.x, respectively: + +$$$ece-elastic-stack-stackpacks-recent$$$ + +| Required downloads | Minimum required ECE version | +| --- | --- | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.17.1](https://download.elastic.co/cloud-enterprise/versions/8.17.1.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.27](https://download.elastic.co/cloud-enterprise/versions/7.17.27.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.23](https://download.elastic.co/cloud-enterprise/versions/6.8.23.zip) | ECE 1.1.4 | + + +## All available Elastic Stack packs [ece-elastic-stack-stackpacks] + +Following is the full list of available packs containing Elastic Stack versions. Note that Enterprise Search was introduced with ECE 2.6.0 and requires that version or higher. + +::::{dropdown} **Expand to view the full list** +| Required downloads | Minimum required ECE version | +| --- | --- | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.17.1](https://download.elastic.co/cloud-enterprise/versions/8.17.1.zip) | ECE 3.0.0
(+ docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.17.0](https://download.elastic.co/cloud-enterprise/versions/8.17.0.zip) | ECE 3.0.0
(+ docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.3](https://download.elastic.co/cloud-enterprise/versions/8.16.3.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.2](https://download.elastic.co/cloud-enterprise/versions/8.16.2.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.1](https://download.elastic.co/cloud-enterprise/versions/8.16.1.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.16.0](https://download.elastic.co/cloud-enterprise/versions/8.16.0.zip) | ECE 3.0.0
(+ Docker 20.10.10+ required for 8.16+) | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.5](https://download.elastic.co/cloud-enterprise/versions/8.15.5.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.4](https://download.elastic.co/cloud-enterprise/versions/8.15.4.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.3](https://download.elastic.co/cloud-enterprise/versions/8.15.3.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.2](https://download.elastic.co/cloud-enterprise/versions/8.15.2.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.1](https://download.elastic.co/cloud-enterprise/versions/8.15.1.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.15.0](https://download.elastic.co/cloud-enterprise/versions/8.15.0.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.3](https://download.elastic.co/cloud-enterprise/versions/8.14.3.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.2](https://download.elastic.co/cloud-enterprise/versions/8.14.2.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.1](https://download.elastic.co/cloud-enterprise/versions/8.14.1.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.14.0](https://download.elastic.co/cloud-enterprise/versions/8.14.0.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.4](https://download.elastic.co/cloud-enterprise/versions/8.13.4.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.3](https://download.elastic.co/cloud-enterprise/versions/8.13.3.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.2](https://download.elastic.co/cloud-enterprise/versions/8.13.2.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.1](https://download.elastic.co/cloud-enterprise/versions/8.13.1.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.13.0](https://download.elastic.co/cloud-enterprise/versions/8.13.0.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.12.2](https://download.elastic.co/cloud-enterprise/versions/8.12.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.12.1](https://download.elastic.co/cloud-enterprise/versions/8.12.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.12.0](https://download.elastic.co/cloud-enterprise/versions/8.12.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.4](https://download.elastic.co/cloud-enterprise/versions/8.11.4.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.3](https://download.elastic.co/cloud-enterprise/versions/8.11.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.2](https://download.elastic.co/cloud-enterprise/versions/8.11.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.1](https://download.elastic.co/cloud-enterprise/versions/8.11.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.11.0](https://download.elastic.co/cloud-enterprise/versions/8.11.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.4](https://download.elastic.co/cloud-enterprise/versions/8.10.4.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.3](https://download.elastic.co/cloud-enterprise/versions/8.10.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.2](https://download.elastic.co/cloud-enterprise/versions/8.10.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.1](https://download.elastic.co/cloud-enterprise/versions/8.10.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.10.0](https://download.elastic.co/cloud-enterprise/versions/8.10.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.9.2](https://download.elastic.co/cloud-enterprise/versions/8.9.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.9.1](https://download.elastic.co/cloud-enterprise/versions/8.9.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.9.0](https://download.elastic.co/cloud-enterprise/versions/8.9.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.8.2](https://download.elastic.co/cloud-enterprise/versions/8.8.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.8.1](https://download.elastic.co/cloud-enterprise/versions/8.8.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.8.0](https://download.elastic.co/cloud-enterprise/versions/8.8.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.7.1](https://download.elastic.co/cloud-enterprise/versions/8.7.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.7.0](https://download.elastic.co/cloud-enterprise/versions/8.7.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.6.2](https://download.elastic.co/cloud-enterprise/versions/8.6.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.6.1](https://download.elastic.co/cloud-enterprise/versions/8.6.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.6.0](https://download.elastic.co/cloud-enterprise/versions/8.6.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.3](https://download.elastic.co/cloud-enterprise/versions/8.5.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.2](https://download.elastic.co/cloud-enterprise/versions/8.5.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.1](https://download.elastic.co/cloud-enterprise/versions/8.5.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.5.0](https://download.elastic.co/cloud-enterprise/versions/8.5.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.3](https://download.elastic.co/cloud-enterprise/versions/8.4.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.2](https://download.elastic.co/cloud-enterprise/versions/8.4.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.1](https://download.elastic.co/cloud-enterprise/versions/8.4.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.4.0](https://download.elastic.co/cloud-enterprise/versions/8.4.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.3](https://download.elastic.co/cloud-enterprise/versions/8.3.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.2](https://download.elastic.co/cloud-enterprise/versions/8.3.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.1](https://download.elastic.co/cloud-enterprise/versions/8.3.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.3.0](https://download.elastic.co/cloud-enterprise/versions/8.3.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.3](https://download.elastic.co/cloud-enterprise/versions/8.2.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.2](https://download.elastic.co/cloud-enterprise/versions/8.2.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.1](https://download.elastic.co/cloud-enterprise/versions/8.2.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.2.0](https://download.elastic.co/cloud-enterprise/versions/8.2.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.3](https://download.elastic.co/cloud-enterprise/versions/8.1.3.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.2](https://download.elastic.co/cloud-enterprise/versions/8.1.2.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.1](https://download.elastic.co/cloud-enterprise/versions/8.1.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.1.0](https://download.elastic.co/cloud-enterprise/versions/8.1.0.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.0.1](https://download.elastic.co/cloud-enterprise/versions/8.0.1.zip) | ECE 3.0.0 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 8.0.0](https://download.elastic.co/cloud-enterprise/versions/8.0.0.zip) | ECE 3.0.0 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.27](https://download.elastic.co/cloud-enterprise/versions/7.17.27.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.26](https://download.elastic.co/cloud-enterprise/versions/7.17.26.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.25](https://download.elastic.co/cloud-enterprise/versions/7.17.25.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.24](https://download.elastic.co/cloud-enterprise/versions/7.17.24.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.23](https://download.elastic.co/cloud-enterprise/versions/7.17.23.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.22](https://download.elastic.co/cloud-enterprise/versions/7.17.22.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.21](https://download.elastic.co/cloud-enterprise/versions/7.17.21.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.20](https://download.elastic.co/cloud-enterprise/versions/7.17.20.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.19](https://download.elastic.co/cloud-enterprise/versions/7.17.19.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.18](https://download.elastic.co/cloud-enterprise/versions/7.17.18.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.17](https://download.elastic.co/cloud-enterprise/versions/7.17.17.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.16](https://download.elastic.co/cloud-enterprise/versions/7.17.16.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.15](https://download.elastic.co/cloud-enterprise/versions/7.17.15.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.14](https://download.elastic.co/cloud-enterprise/versions/7.17.14.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.13](https://download.elastic.co/cloud-enterprise/versions/7.17.13.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.12](https://download.elastic.co/cloud-enterprise/versions/7.17.12.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.11](https://download.elastic.co/cloud-enterprise/versions/7.17.11.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.10](https://download.elastic.co/cloud-enterprise/versions/7.17.10.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.9](https://download.elastic.co/cloud-enterprise/versions/7.17.9.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.8](https://download.elastic.co/cloud-enterprise/versions/7.17.8.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.7](https://download.elastic.co/cloud-enterprise/versions/7.17.7.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.6](https://download.elastic.co/cloud-enterprise/versions/7.17.6.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.5](https://download.elastic.co/cloud-enterprise/versions/7.17.5.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.4](https://download.elastic.co/cloud-enterprise/versions/7.17.4.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.3](https://download.elastic.co/cloud-enterprise/versions/7.17.3.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.2](https://download.elastic.co/cloud-enterprise/versions/7.17.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.1](https://download.elastic.co/cloud-enterprise/versions/7.17.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.17.0](https://download.elastic.co/cloud-enterprise/versions/7.17.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.3](https://download.elastic.co/cloud-enterprise/versions/7.16.3.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.2](https://download.elastic.co/cloud-enterprise/versions/7.16.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.1](https://download.elastic.co/cloud-enterprise/versions/7.16.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.16.0](https://download.elastic.co/cloud-enterprise/versions/7.16.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.15.2](https://download.elastic.co/cloud-enterprise/versions/7.15.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.15.1](https://download.elastic.co/cloud-enterprise/versions/7.15.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.15.0](https://download.elastic.co/cloud-enterprise/versions/7.15.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.14.2](https://download.elastic.co/cloud-enterprise/versions/7.14.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.14.1](https://download.elastic.co/cloud-enterprise/versions/7.14.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.14.0](https://download.elastic.co/cloud-enterprise/versions/7.14.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.4](https://download.elastic.co/cloud-enterprise/versions/7.13.4.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.3](https://download.elastic.co/cloud-enterprise/versions/7.13.3.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.2](https://download.elastic.co/cloud-enterprise/versions/7.13.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.1](https://download.elastic.co/cloud-enterprise/versions/7.13.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.13.0](https://download.elastic.co/cloud-enterprise/versions/7.13.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.12.1](https://download.elastic.co/cloud-enterprise/versions/7.12.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.12.0](https://download.elastic.co/cloud-enterprise/versions/7.12.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.11.2](https://download.elastic.co/cloud-enterprise/versions/7.11.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.11.1](https://download.elastic.co/cloud-enterprise/versions/7.11.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.11.0](https://download.elastic.co/cloud-enterprise/versions/7.11.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.10.2](https://download.elastic.co/cloud-enterprise/versions/7.10.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.10.1](https://download.elastic.co/cloud-enterprise/versions/7.10.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.10.0](https://download.elastic.co/cloud-enterprise/versions/7.10.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.3](https://download.elastic.co/cloud-enterprise/versions/7.9.3.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.2](https://download.elastic.co/cloud-enterprise/versions/7.9.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.1](https://download.elastic.co/cloud-enterprise/versions/7.9.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.9.0](https://download.elastic.co/cloud-enterprise/versions/7.9.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.8.1](https://download.elastic.co/cloud-enterprise/versions/7.8.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.8.0](https://download.elastic.co/cloud-enterprise/versions/7.8.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.7.1](https://download.elastic.co/cloud-enterprise/versions/7.7.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and Enterprise Search stack pack: 7.7.0](https://download.elastic.co/cloud-enterprise/versions/7.7.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.6.2](https://download.elastic.co/cloud-enterprise/versions/7.6.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.6.1](https://download.elastic.co/cloud-enterprise/versions/7.6.1.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.6.0](https://download.elastic.co/cloud-enterprise/versions/7.6.0.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.5.2](https://download.elastic.co/cloud-enterprise/versions/7.5.2.zip) | ECE 2.2.2 | +| [ Elasticsearch, Kibana, APM, and App Search stack pack: 7.5.1](https://download.elastic.co/cloud-enterprise/versions/7.5.1.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.5.0](https://download.elastic.co/cloud-enterprise/versions/7.5.0.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.4.2](https://download.elastic.co/cloud-enterprise/versions/7.4.2.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.4.1](https://download.elastic.co/cloud-enterprise/versions/7.4.1.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, APM, and App Search stack pack: 7.4.0](https://download.elastic.co/cloud-enterprise/versions/7.4.0.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.3.2](https://download.elastic.co/cloud-enterprise/versions/7.3.2.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.3.1](https://download.elastic.co/cloud-enterprise/versions/7.3.1.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.3.0](https://download.elastic.co/cloud-enterprise/versions/7.3.0.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.2.1](https://download.elastic.co/cloud-enterprise/versions/7.2.1.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.2.0](https://download.elastic.co/cloud-enterprise/versions/7.2.0.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.1.1](https://download.elastic.co/cloud-enterprise/versions/7.1.1.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.1.0](https://download.elastic.co/cloud-enterprise/versions/7.1.0.zip) | ECE 2.2.2 | +| [Elasticsearch, Kibana, and APM stack pack: 7.0.1](https://download.elastic.co/cloud-enterprise/versions/7.0.1.zip) | ECE 2.2.0 | +| [Elasticsearch, Kibana, and APM stack pack: 7.0.0](https://download.elastic.co/cloud-enterprise/versions/7.0.0.zip) | ECE 2.2.0 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.23](https://download.elastic.co/cloud-enterprise/versions/6.8.23.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.22](https://download.elastic.co/cloud-enterprise/versions/6.8.22.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.21](https://download.elastic.co/cloud-enterprise/versions/6.8.21.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.20](https://download.elastic.co/cloud-enterprise/versions/6.8.20.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.19](https://download.elastic.co/cloud-enterprise/versions/6.8.19.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.18](https://download.elastic.co/cloud-enterprise/versions/6.8.18.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.17](https://download.elastic.co/cloud-enterprise/versions/6.8.17.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.16](https://download.elastic.co/cloud-enterprise/versions/6.8.16.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.15](https://download.elastic.co/cloud-enterprise/versions/6.8.15.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.14](https://download.elastic.co/cloud-enterprise/versions/6.8.14.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.13](https://download.elastic.co/cloud-enterprise/versions/6.8.13.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.12](https://download.elastic.co/cloud-enterprise/versions/6.8.12.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.11](https://download.elastic.co/cloud-enterprise/versions/6.8.11.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.10](https://download.elastic.co/cloud-enterprise/versions/6.8.10.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.9](https://download.elastic.co/cloud-enterprise/versions/6.8.9.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.8](https://download.elastic.co/cloud-enterprise/versions/6.8.8.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.7](https://download.elastic.co/cloud-enterprise/versions/6.8.7.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.6](https://download.elastic.co/cloud-enterprise/versions/6.8.6.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.5](https://download.elastic.co/cloud-enterprise/versions/6.8.5.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.4](https://download.elastic.co/cloud-enterprise/versions/6.8.4.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.3](https://download.elastic.co/cloud-enterprise/versions/6.8.3.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.2](https://download.elastic.co/cloud-enterprise/versions/6.8.2.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.1](https://download.elastic.co/cloud-enterprise/versions/6.8.1.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.8.0](https://download.elastic.co/cloud-enterprise/versions/6.8.0.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.7.2](https://download.elastic.co/cloud-enterprise/versions/6.7.2.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.7.1](https://download.elastic.co/cloud-enterprise/versions/6.7.1.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.7.0](https://download.elastic.co/cloud-enterprise/versions/6.7.0.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.6.2](https://download.elastic.co/cloud-enterprise/versions/6.6.2.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.6.1](https://download.elastic.co/cloud-enterprise/versions/6.6.1.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.6.0](https://download.elastic.co/cloud-enterprise/versions/6.6.0.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.4](https://download.elastic.co/cloud-enterprise/versions/6.5.4.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.3](https://download.elastic.co/cloud-enterprise/versions/6.5.3.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.2](https://download.elastic.co/cloud-enterprise/versions/6.5.2.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.1](https://download.elastic.co/cloud-enterprise/versions/6.5.1.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.5.0](https://download.elastic.co/cloud-enterprise/versions/6.5.0.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.3](https://download.elastic.co/cloud-enterprise/versions/6.4.3.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.2](https://download.elastic.co/cloud-enterprise/versions/6.4.2.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.1](https://download.elastic.co/cloud-enterprise/versions/6.4.1.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.4.0](https://download.elastic.co/cloud-enterprise/versions/6.4.0.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.3.2](https://download.elastic.co/cloud-enterprise/versions/6.3.2.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.3.1](https://download.elastic.co/cloud-enterprise/versions/6.3.1.zip) | ECE 1.1.4 | +| [Elasticsearch, Kibana, and APM stack pack: 6.3.0](https://download.elastic.co/cloud-enterprise/versions/6.3.0.zip) | ECE 1.1.4 | +| [Elasticsearch and Kibana stack pack: 6.2.4](https://download.elastic.co/cloud-enterprise/versions/6.2.4.zip) | ECE 1.1.2 | +| [Elasticsearch and Kibana stack pack: 6.2.3](https://download.elastic.co/cloud-enterprise/versions/6.2.3.zip) | ECE 1.1.2 | +| [Elasticsearch and Kibana stack pack: 6.2.2](https://download.elastic.co/cloud-enterprise/versions/6.2.2.zip) | ECE 1.1.2 | +| [Elasticsearch and Kibana stack pack: 6.1.4](https://download.elastic.co/cloud-enterprise/versions/6.1.4.zip) | ECE 1.1.2 | +| [Elasticsearch and Kibana stack pack: 6.1.3](https://download.elastic.co/cloud-enterprise/versions/6.1.3.zip) | ECE 1.1.2 | +| [Elasticsearch and Kibana stack pack: 6.0.1](https://download.elastic.co/cloud-enterprise/versions/6.0.1.zip) | ECE 1.1.2 | +| [Elasticsearch and Kibana stack pack: 6.0.0](https://download.elastic.co/cloud-enterprise/versions/6.0.0.zip) | ECE 1.1.0 | +| [Elasticsearch and Kibana stack pack: 5.6.16](https://download.elastic.co/cloud-enterprise/versions/5.6.16.zip) | ECE 1.1.0 | +| [Elasticsearch and Kibana stack pack: 2.4.6](https://download.elastic.co/cloud-enterprise/versions/2.4.6.zip) | ECE 1.0.0 | +| [Elasticsearch and Kibana stack pack: 2.4.5](https://download.elastic.co/cloud-enterprise/versions/2.4.5.zip) | ECE 1.0.0 | + +:::: + + +::::{tip} +For *offline* or *air-gapped* installations, additional steps are required to add Elastic Stack packs, as these packs do not contain any Docker images. After downloading a stack pack, you also need to pull and load the Docker images that match the Elastic Stack version. To learn more about what Docker images you need and about pulling and loading Docker images, check [Install ECE offline](air-gapped-install.md). +:::: + + + +## Before you begin [ece_before_you_begin_10] + +The examples shown all use HTTPS over port 12443, which requires that you have [a TLS certificate configured](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md). Alternatively, you can specify the `-k` option to turn off certificate verification, as shown in our examples, or use HTTP over port 12400. + + +## Get Elastic Stack information [ece_get_elastic_stack_information] + +You can obtain information about existing Elastic Stack versions that are available in your installation through the Cloud UI or through the command line. + +To obtain information about available Elastic Stack versions through the Cloud UI: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Elastic Stack**. +3. Select the version that you want. + + The available Elastic Stack versions are shown. More detailed information about Docker images, plugins, and related Kibana versions are also available for each Elasticsearch version. + + +To obtain information about available Elastic Stack versions through the command line: + +```sh +curl -X GET -u USER:PASSWORD https://COORDINATOR_HOST:12443/api/v1/stack/versions +``` + +For example (output abridged for brevity): + +``` +curl -X GET -u admin:4Z52y8Gq7PrxMDy47ipJPSh4ozBMynOGa9HWxcy2D3j https://10.56.12.153:12443/api/v1/stack/versions +{ + "stacks": [ + { + "version": "2.4.5", + "template": { + "template_version": "", + "hashes": [] + }, + "elasticsearch": { + "docker_image": "docker.elastic.co/cloud-enterprise/elasticsearch:2.4.5-0", + "plugins": [ + "graph", + "analysis-icu", + "analysis-kuromoji", + "analysis-smartcn", + "analysis-stempel", + "analysis-phonetic", + "watcher", + "mapper-attachments", + "delete-by-query" + ], + "default_plugins": [ + "found-elasticsearch", + "cloud-aws", + "found-license-plugin", + "shield", + "marvel-agent" + ... + ] + } + }, + { + "version": "5.2.2", + "template": { + "template_version": "", + "hashes": [] + }, + "elasticsearch": { + "docker_image": "docker.elastic.co/cloud-enterprise/elasticsearch:5.2.2-0", + "plugins": [ + "analysis-icu", + "analysis-kuromoji", + "analysis-smartcn", + "analysis-stempel", + "analysis-phonetic", + "mapper-attachments", + "ingest-attachment", + "ingest-geoip", + "ingest-user-agent" + ], + "default_plugins": [ + "repository-s3", + "found-elasticsearch", + "x-pack" + ... + ] + } + } + ] +} +``` +You can also query for a specific version with a URI such as `https://COORDINATOR_HOST:12443/api/v1/stack/versions/5.3.2`, for example. + + +## Add Elastic Stack packs [ece-manage-elastic-stack-add] + +You can add new Elastic Stack packs to your installation through the Cloud UI, through the Elastic Cloud Enterprise installation script, or through the RESTful API. + +To add a new Elastic Stack pack from the Cloud UI: + +1. Download the [Elastic Stack version]() that you want. +2. [Log into the Cloud UI](log-into-cloud-ui.md). +3. From the **Platform** menu, select **Elastic Stack**. +4. Select **Upload Elastic Stack pack**. +5. Select a .zip file that contains an Elastic Stack pack and upload it. + + After the stack pack has been uploaded successfully, the new version appears in the list of Elastic Stack versions and can be used when you create or change a deployment. + + +To add a new Elastic Stack pack through the Elastic Cloud Enterprise installation script from the command line: + +1. Log into a host running Elastic Cloud Enterprise. +2. Add the Elastic Stack pack with the `add-stack-version` action: + + ```sh + ./elastic-cloud-enterprise.sh add-stack-version \ + --user USER --pass PASSWORD \ + --version X.Y.Z <1> + ``` + + 1. A supported Elastic Stack version, such as `8.12.2` + + + For example: + + ```sh + bash elastic-cloud-enterprise.sh add-stack-version \ + --user admin --pass pGX5DwKzVAAIeCIpTwwAkCuJDu0ASdFP33UmYpfogfF \ + --version 8.12.2 + ``` + + +To add a new Elastic Stack pack through the RESTful API from the command line: + +1. Download the pack on an internet-connected host from Elastic and make it available locally. +2. Add the Elastic Stack pack with the following API call: + + ```sh + curl -X POST -u USER:PASSWORD https://COORDINATOR_HOST:12443/api/v1/stack/versions \ + -H 'content-type: application/zip' \ + --data-binary "@PATH/STACK_PACK_FILE" <1> + ``` + + 1. The local path and the new Elastic Stack pack .zip file + + + For example: + + ```sh + curl -X POST -u admin:pGX5DwKzVAAIeCIpTwwAkCuJDu0ASdFP33UmYpfogfF https://10.56.12.153:12443/api/v1/stack/versions \ + -H 'content-type: application/zip' \ + --data-binary "@/Users/iuriitceretian/Documents/stacks/5.4.0.zip" + ``` + + + +## Update Elastic Stack packs [ece_update_elastic_stack_packs] + +Updating an Elastic Stack pack might become necessary if an Elastic Stack version has been updated with security fixes, for example. You can update an existing Elastic Stack version through the Cloud UI or through the command line. + +Updated versions of Elasticsearch and Kibana are used when you create new Elasticsearch clusters, but they are not automatically applied to already running clusters. To update existing Elasticsearch clusters and Kibana after an updated Elastic Stack pack has been added, you need to [change the deployment configuration](working-with-deployments.md). + +To update Elastic Stack packs through the Cloud UI: + +1. Download the [Elastic Stack version](#ece-elastic-stack-stackpacks) that you want. +2. [Log into the Cloud UI](log-into-cloud-ui.md). +3. From the **Platform** menu, select **Elastic Stack**. +4. Delete the old pack you want to replace. +5. Select **Upload Elastic Stack pack**. +6. Select a ZIP file that contains an Elastic Stack pack and upload it. + + After the stack pack has been uploaded successfully, the updated Elastic Stack version replaces the existing one. + + +To update Elastic Stack packs through the RESTful API from the command line: + +1. Download an updated pack on an internet-connected host from Elastic and make it available locally. +2. Update the Elastic Stack pack with the following API call: + + ```sh + curl -X PUT -u USER:PASSWORD https://COORDINATOR_HOST:12443/api/v1/stack/versions/VERSION \ <1> + -H 'content-type: application/zip' \ + --data-binary "@PATH/STACK_PACK_FILE" <2> + ``` + + 1. The version being updated + 2. The local path and the updated Elastic Stack pack .zip file + + + For example: + + ```sh + curl -X PUT -u admin:pGX5DwKzVAAIeCIpTwAAkCuJDu0ASdFP33UmYpfogfF https://10.58.12.153:12443/api/v1/stack/versions/6.4.0 \ + -H 'content-type: application/zip' \ + --data-binary "@/Users/johnsmith/Documents/stacks/6.4.0.zip" + ``` diff --git a/deploy-manage/deploy/cloud-enterprise/manage-integrations-server.md b/deploy-manage/deploy/cloud-enterprise/manage-integrations-server.md new file mode 100644 index 000000000..eb03e7430 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/manage-integrations-server.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-integrations-server.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-integrations-server-api-example.html +--- + +# Manage your integrations server + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-manage-integrations-server.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-integrations-server-api-example.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/migrate-ece-on-podman-hosts-to-selinux-enforce.md b/deploy-manage/deploy/cloud-enterprise/migrate-ece-on-podman-hosts-to-selinux-enforce.md new file mode 100644 index 000000000..d1e5caf20 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/migrate-ece-on-podman-hosts-to-selinux-enforce.md @@ -0,0 +1,120 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-migrate-to-selinux-in-enforcing-mode.html +--- + +# Migrate ECE on Podman hosts to SELinux enforce [ece-migrate-to-selinux-in-enforcing-mode] + +This section provides guidelines and recommendations for migrating an existing platform on a Podman-based environment to use SELinux in `enforcing` mode. The recommended approach consists of four (4) high-level steps. Steps 2-4 need to be repeated for each host in your environment. + +**Step 1** Migrate existing ECE installation to version >=3.7.2 + +**Step 2** Put host into maintenance mode + +**Step 3** Switch to SELinux in `enforcing` mode + +**Step 4** Remove maintenance mode + +::::{important} +We do not recommend to upgrade ECE and switch to SELinux in `enforcing` mode at the same time. +:::: + + +::::{important} +Execute the following steps on each ECE host, one after the other. Do not execute those steps on multiple hosts at the same time. +:::: + + +Perform the following steps on each host of your {{ECE}} installation: + +1. Ensure that SELinux is `disabled` on the host. + + ```bash + $ sudo getenforce + Disabled + ``` + +2. Verify the SELinux labels on `/mnt/data/docker`. + + At this state, ECE is not running with SELinux enabled. We do not see any SELinux labels yet. + + ```bash + $ sudo ls -alishZ /mnt/data/docker/ + total 848K + 132 0 drwx--x--x 10 elastic elastic ? 203 Nov 14 12:14 . + 128 0 drwxr-xr-x 4 elastic elastic ? 35 Nov 8 10:05 .. + 133 796K -rw-r--r-- 1 root root ? 792K Nov 14 12:14 db.sql + ``` + +3. Put the host into maintenance mode. +4. Set SELinux to `Permissive` mode ([Resource](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_selinux/changing-selinux-states-and-modes_using-selinux#changing-to-permissive-mode_changing-selinux-states-and-modes)) and reboot the host. + + ```bash + $ sudo sed -i 's/SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config + $ sudo reboot + ``` + +5. Verify that SELinux is running in `permissive` mode. + + ```bash + $ getenforce + Permissive + ``` + +6. Fix the SELinux file labels across the system. Run the following command and reboot the host ([Resource](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_selinux/changing-selinux-states-and-modes_using-selinux#enabling-selinux-on-systems-that-previously-had-it-disabled_changing-selinux-states-and-modes)). + + ```bash + $ sudo fixfiles -F onboot + System will relabel on next boot + + sudo reboot + ``` + +7. Verify that SELinux labels are visible. + + ```bash + $ sudo ls -alishZ /mnt/data/docker/ + total 848K + 132 0 drwx--x--x. 10 elastic elastic system_u:object_r:unlabeled_t:s0 203 Nov 14 12:26 . + 128 0 drwxr-xr-x. 4 elastic elastic system_u:object_r:unlabeled_t:s0 35 Nov 8 10:05 .. + 133 796K -rw-r--r--. 1 root root system_u:object_r:unlabeled_t:s0 792K Nov 14 12:26 db.sq + ``` + +8. Run the `configure-selinux-settings` command of the ECE installer as user `elastic`. + + ::::{note} + Ensure that the flag `--podman` is used. + :::: + + + ```bash + $ bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) configure-selinux-settings --podman + ``` + +9. Verify that SELinux labels are visible. The labels change from `object_r:unlabeled_t` to `container_var_lib_t`. + + ```bash + $ sudo ls -alishZ /mnt/data/docker/ + total 848K + 132 0 drwx--x--x. 10 elastic elastic system_u:object_r:container_var_lib_t:s0 203 Nov 14 12:31 . + 128 0 drwxr-xr-x. 4 elastic elastic system_u:object_r:mnt_t:s0 35 Nov 8 10:05 .. + 133 796K -rw-r--r--. 1 root root system_u:object_r:container_var_lib_t:s0 792K Nov 14 12:31 db.sql + ``` + +10. Use SELinux in `enforcing` mode ([Resource](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_selinux/changing-selinux-states-and-modes_using-selinux#changing-to-enforcing-mode_changing-selinux-states-and-modes)) and reboot the host. + + ```bash + $ sudo sed -i 's/SELINUX=.*/SELINUX=enforcing/g' /etc/selinux/config + $ sudo reboot + ``` + +11. Verify that SELinux is running in `enforcing` mode. + + ```bash + $ getenforce + Enforcing + ``` + +12. Verify that all containers are healthy. +13. Remove the maintenance mode of the host. + diff --git a/deploy-manage/deploy/cloud-enterprise/migrate-ece-to-podman-hosts.md b/deploy-manage/deploy/cloud-enterprise/migrate-ece-to-podman-hosts.md new file mode 100644 index 000000000..f24c2cb2c --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/migrate-ece-to-podman-hosts.md @@ -0,0 +1,493 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-migrate-to-podman.html +--- + +# Migrate ECE to Podman hosts [ece-migrate-to-podman] + +This section provides guidelines and recommendations for migrating an existing platform to a Podman-based environment. You have an existing ECE installation version >=3.0 and want to migrate all hosts to use Podman as a container runtime. The recommended approach consists of three (3) high-level steps. + +**Step 1**: Upgrade ECE to version >= 3.3.0 following the [Upgrade your installation](../../upgrade/orchestrator/upgrade-cloud-enterprise.md) guidelines. Skip this step if your ECE installation is already running a version >= 3.3.0. + +**Step 2**: Prepare an additional RHEL or Rocky Linux VM. We recommend using one additional VM to perform a rolling grow-and-shrink upgrade. + +**Step 3**: Migrate each host one by one from Docker to Podman. This allows you to move workloads from Docker-based hosts to Podman-based ones without downtime. We highly recommend to allocate the additional Podman allocator to the same zone as the Docker allocator you want to replace. **Assuming there is sufficient capacity**, you may use existing docker-based hosts as the "new" Podman-based hosts. To reuse a host, you will first follow the steps to [delete a host from the ECE deployment](../../maintenance/ece/delete-ece-hosts.md) followed by the steps [to remove ECE software from the host](../../uninstall/uninstall-elastic-cloud-enterprise.md). The following diagram shows the conceptual steps. + +::::{note} +Using Docker or Podman as container runtime is a configuration local to the host. For example, the admin console is not aware which allocator is using Podman. Hence there is no restriction on the migration ordering of the hosts. This applies to all host role types. +:::: + + +:::{image} ../../../images/cloud-enterprise-podman-migration-overview-1.png +:alt: Migration Overview +::: + +::::{note} +When copy-pasting commands, verify that characters like quotes (“) are encoded correctly in the console where you copy the command to. +:::: + + +::::{note} +Steps that run commands starting with `sudo` can be run as any sudoers user. +:::: + + +::::{note} +Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. +:::: + + +Otherwise, when the file content changes, the corresponding user is mentioned as part of the step description. + +1. Make sure you are running a healthy x-node ECE environment ready to be upgraded. All nodes use the Docker container runtime. +2. Upgrade to ECE 3.3.0+ following the [Upgrade your installation](../../upgrade/orchestrator/upgrade-cloud-enterprise.md) guideline. Skip this step if your existing ECE installation already runs ECE >= 3.3.0. +3. Follow your internal guidelines to add an additional vanilla RHEL (Note that the version must be >= 8.5, but <9), or Rocky Linux 8 or 9 VM to your environment. +4. Verify that required traffic from the host added in step 3 is allowed to the primary ECE VM(s). Check the [Networking prerequisites](ece-networking-prereq.md) and [Google Cloud Platform (GCP)](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-gcp.html) guidelines for a list of ports that need to be open. The technical configuration highly depends on the underlying infrastructure. + + **Example** For AWS, allowing traffic between hosts is implemented using security groups. + +5. Identify the host you want to replace with a podman-based host and copy the associated roles. + + **Example 1** You want to migrate the Docker host `192.168.44.74` with the role `Allocator` to a podman host. Copy the role `allocator`. + + :::{image} ../../../images/cloud-enterprise-podman-migration-fetch-roles-1.png + :alt: Migrate Allocator + ::: + + **Example 2** You want to migrate the Docker host `192.168.44.10` with the roles `Allocator`, `Controller`, `Director`, and `Proxy` to a podman host. Copy the roles `allocator`, `coordinator`, `director`, `proxy`. + + :::{image} ../../../images/cloud-enterprise-podman-migration-fetch-roles-2.png + :alt: Migrate Allocator + ::: + + ::::{important} + The role `Controller` in the admin console is called `coordinator` for the `elastic-cloud-enterprise.sh` script + :::: + +6. Configure the RHEL or Rocky Linux host. + +1. Install the OS packages `lvm2`, `iptables`, `sysstat`, and `net-tools` by executing: + + ```sh + sudo dnf install lvm2 iptables sysstat net-tools <1> + ``` + + 1. The ECE diagnostic script requires `net-tools`.
+ + + ::::{note} + For RHEL 9 and Rocky Linux 9, also install the `containernetworking-plugins` package using:
+ + ```sh + sudo dnf -y install containernetworking-plugins + ``` + + :::: + +2. Remove Docker and previously installed podman packages (if previously installed). + + ```sh + sudo dnf remove docker docker-ce podman podman-remote containerd.io + ``` + +3. As a sudoers user, edit the `/etc/selinux/config` file: + + 1. If you are not using SELinux, set it to permissive mode: + + ```text + SELINUX=permissive + ``` + + 2. If you are using SELinux, set it to enforcing mode: + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```text + SELINUX=enforcing + ``` + +4. Install podman: + + * For RHEL 8 and Rocky Linux, install version `4.*`. + + ```sh + sudo dnf install podman-4.* podman-remote-4.* + ``` + + * For RHEL 9, install the latest available version `4.*` using dnf. + + ```sh + sudo dnf install podman-4.* podman-remote-4.* + ``` + +5. [This step is for RHEL 9 and Rocky Linux 9 only] Switch the network stack from Netavark to CNI: + + 1. If the */etc/containers/containers.conf* file does not exist, copy the */usr/share/containers/containers.conf* file to the */etc/containers/* directory (for example, using `cp /usr/share/containers/containers.conf /etc/containers/`). + 2. Open the */etc/containers/containers.conf* file. Navigate to the **network** section and make sure that the **network_backend** setting is set to `cni`. + 3. Reboot the system (`reboot`). + 4. Check that the network stack has changed to `cni`:
+ + ```sh + cat /etc/containers/containers.conf + [...] + [network] + network_backend="cni" + [...] + ``` + +6. If podman requires a proxy in your infrastructure setup, modify the `/usr/share/containers/containers.conf` file and add the `HTTP_PROXY` and `HTTPS_PROXY` environment variables in the [engine] section. Please note that multiple env variables in that configuration file exists — use the one in the [engine] section. + + Example: + + ```text + [engine] + env = ["HTTP_PROXY=http://{proxy-ip}:{proxy-port}", "HTTPS_PROXY=http://{proxy-ip}:{proxy-port}"] + ``` + +7. Reload systemd configuration + + ```sh + sudo systemctl daemon-reload + ``` + +8. Create OS groups, if they do not exist yet + + Reference: [Users and permissions](ece-users-permissions.md) + + ```sh + sudo groupadd elastic + sudo groupadd podman + ``` + +9. Add user `elastic` to the `podman` group + + Reference: [Users and permissions](ece-users-permissions.md) + + ```sh + sudo useradd -g "elastic" -G "podman" elastic + ``` + +10. As a sudoers user, add the following line to /etc/sudoers.d/99-ece-users + + Reference: [Users and permissions](ece-users-permissions.md) + + ```text + elastic ALL=(ALL) NOPASSWD:ALL + ``` + +11. Add the required options to the kernel boot arguments + + ```sh + sudo /sbin/grubby --update-kernel=ALL --args='cgroup_enable=memory cgroup.memory=nokmem swapaccount=1' + ``` + +12. Create the directory + + ```sh + sudo mkdir -p /etc/systemd/system/podman.socket.d + ``` + +13. As a sudoers user, create the file `/etc/systemd/system/podman.socket.d/podman.conf` with the following content. Set the correct ownership and permission. + + ::::{important} + Both `ListenStream=` and `ListenStream=/var/run/docker.sock` parameters are required! + :::: + + + File content: + + ```text + [Socket] + ListenStream= + ListenStream=/var/run/docker.sock + SocketMode=770 + SocketUser=elastic + SocketGroup=podman + ``` + + File ownership and permission: + + ```sh + sudo chown root:root /etc/systemd/system/podman.socket.d/podman.conf + sudo chmod 0644 /etc/systemd/system/podman.socket.d/podman.conf + ``` + +14. As a sudoers user, create the (text) file `/usr/bin/docker` with the following content. Verify that the regular double quotes in the text file are used (ASCII code Hex 22) + + ```text + #!/bin/bash + podman-remote --url unix:///var/run/docker.sock "$@" + ``` + +15. Set the file permissions on `/usr/bin/docker` + + ```sh + sudo chmod 0755 /usr/bin/docker + ``` + +16. As a sudoers user, add the following two lines to section `[storage]` in the file `/etc/containers/storage.conf`. Verify that those parameters are only defined once. Either remove or comment out potentially existing parameters. + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```text + runroot = "/mnt/data/docker/runroot/" + graphroot = "/mnt/data/docker" + ``` + +17. Enable podman so that itself and running containers start automatically after a reboot + + ```sh + sudo systemctl enable podman.service + sudo systemctl enable podman-restart.service + ``` + +18. Enable the `overlay` kernel module (check [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)) that the Podman `overlay` storage driver uses (check [Working with the Container Storage library and tools in Red Hat Enterprise Linux](https://www.redhat.com/en/blog/working-container-storage-library-and-tools-red-hat-enterprise-linux#:~:text=Storage%20Configuration)). + + In the Docker world there are two overlay drivers, overlay and overlay2. Today most users use the overlay2 driver, so we just use that one, and called it overlay. Refer also to [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/). + + ```sh + echo "overlay" | sudo tee -a /etc/modules-load.d/overlay.conf + ``` + +19. Format the additional data partition + + ```sh + sudo mkfs.xfs /dev/nvme1n1 + ``` + +20. Create the `/mnt/data/` directory used as a mount point + + ```sh + sudo install -o elastic -g elastic -d -m 700 /mnt/data + ``` + +21. As a sudoers user, modify the entry for the XFS volume in the `/etc/fstab` file to add `pquota,prjquota`. The default filesystem path used by Elastic Cloud Enterprise is `/mnt/data`. + + ::::{note} + Replace `/dev/nvme1n1` in the following example with the corresponding device on your host, and add this example configuration as a single line to `/etc/fstab`. + :::: + + + ```text + /dev/nvme1n1 /mnt/data xfs defaults,nofail,x-systemd.automount,prjquota,pquota 0 2 + ``` + +22. Restart the local-fs target + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart local-fs.target + ``` + +23. Set the permissions on the newly mounted device + + ```sh + ls /mnt/data + sudo chown elastic:elastic /mnt/data + ``` + +24. Create the `/mnt/data/docker` directory for the Docker service storage + + ::::{note} + Avoid customizing the host Docker path `/mnt/data/docker` when using SELinux. Otherwise the ECE installer script needs to be adjusted. + :::: + + + ```sh + sudo install -o elastic -g elastic -d -m 700 /mnt/data/docker + ``` + +25. If you want to use FirewallD, please ensure you meet the [networking prerequisites](ece-networking-prereq.md). Otherwise, you can disable it with: + + ```sh + sudo systemctl disable firewalld + ``` + + ::::{note} + If FirewallD does not exist on your VM, you can skip this step. + :::: + +26. Configure kernel parameters + + ```sh + cat <" + } + } + } + ``` + +30. Restart the podman service by running this command: + + ```sh + sudo systemctl daemon-reload + sudo systemctl restart podman + ``` + +31. Reboot the RHEL host + + ```sh + sudo reboot + ``` + + 1. Use the ECE installer script together with the `--podman` flag to add the additional host as a podman-based host. + + Refer to the official [Install Elastic Cloud Enterprise on an additional host](install-ece-on-additional-hosts.md) and [Install ECE online](install-ece-onprem.md) documentation to adapt the command line parameters to your environment including fetching the role token. + + [JVM heap sizes](ece-jvm.md) describes recommended JVM options. + + Important while running `./elastic-cloud-enterprise.sh` + + * Make sure you use `--podman` on the podman host. + * Make sure you use `--selinux` on the Podman host if SELinux runs in `enforcing` mode. + * To fetch a role token following the [Generate Roles Tokens](generate-roles-tokens.md) guidelines, you need to send a JSON token to the admin console. Double check the correct format of the roles. Roles are a list of individual strings in quotes, **NOT a single string**. + + For **example 1**, the JSON object is as follows: + + ```json + '{ "persistent": true, "roles": [ "allocator" ] }' + ``` + + For **example 2**, the JSON object is as follows: + + ```json + '{ "persistent": true, "roles": [ "allocator","coordinator","director","proxy" ] }' + ``` + + * The ECE version of the additional host must be the same as the version used in step 2. Use `--cloud-enterprise-version VERSION_NAME` to specify the correct version. + * To easily identify the podman allocator, apply a tag to the additional host, for example `containerengine:podman`. The podman allocator is needed as the “target allocator” when you later move instances from the Docker allocator to the podman allocator. For example, use `--allocator-tags containerengine:podman`. + * Make sure to apply the roles as copied in step 5 to the additional host. The value for the `--roles` flag is a single string. + + For **example 1** in step 4, use `--roles "allocator"` + + For **example 2** in step 4, use `--roles "allocator,coordinator,director,proxy"` + + * Add the new host to the same availability zone as the Docker host you want to replace. Use the `--availability-zone ` flag. + + 2. Login to admin console + + Verify that the new podman host has the same roles (same coloring of the hexagon) as the Docker host you want to replace. + + The following screenshot shows the state where the correct roles have been applied. Both hosts in ece-zone-1 have the same color. + + :::{image} ../../../images/cloud-enterprise-podman-migration-correct-role-1.png + :alt: Correct role + ::: + + The following screenshot shows the state where incorrect roles have been applied. The hosts in ece-zone-1 do not have the same coloring. + + :::{image} ../../../images/cloud-enterprise-podman-migration-wrong-role-1.png + :alt: Wrong role + ::: + + 3. Put the docker-based allocator you want to replace with a podman allocator in maintenance mode by following the [Enable Maintenance Mode](../../maintenance/ece/enable-maintenance-mode.md) documentation. + + As an alternative, use the [Start maintenance mode](https://www.elastic.co/guide/en/cloud-enterprise/current/start-allocator-maintenance-mode.html) API. + + 4. Move all instances from the Docker allocator to the podman allocator by following the [Move Nodes From Allocators](../../maintenance/ece/move-nodes-instances-from-allocators.md) documentation. + + ::::{important} + Make sure to specify the target podman allocator using the option “Set target allocators”. + :::: + + + ::::{important} + If you move admin console instances, you might update the URL in the browser before continuing with step 11. + :::: + + + :::{image} ../../../images/cloud-enterprise-podman-migration-move-instances-1.png + :alt: Move instances + ::: + + As an alternative, use the [*Move clusters*](https://www.elastic.co/guide/en/cloud-enterprise/current/move-clusters.html) API. + + To identifying the correct target allocator, the following APIs might be helpful: + + * [*Get allocators*](https://www.elastic.co/guide/en/cloud-enterprise/current/get-allocators.html) + * [*Get allocator metadata*](https://www.elastic.co/guide/en/cloud-enterprise/current/get-allocator-metadata.html) + + ```json + { + "allocator_id": "192.168.44.17", + "zone_id": "ece-zone-1", + "host_ip": "192.168.44.17", + "public_hostname": "192.168.44.17", + "capacity": { + "memory": { + "total": 26000, + "used": 0 + } + }, + "settings": {}, + "instances": [], + "metadata": [ + { <1> + "key": "containerengine", + "value": "podman" + } + ] + } + ``` + + 1. If allocators are tagged as mentioned in step 7, the metadata section of the [*Get allocators*](https://www.elastic.co/guide/en/cloud-enterprise/current/get-allocators.html) API should contain the tag. + + + This information allows you to determine what allocators are running on top of podman (automated way) + + 5. Remove the Docker allocator by following the [Delete Hosts](../../maintenance/ece/delete-ece-hosts.md) guidelines. + + As an alternative, use the [Delete Runner](https://www.elastic.co/guide/en/cloud-enterprise/current/delete-runner.html) API. diff --git a/deploy-manage/deploy/cloud-enterprise/post-installation-steps.md b/deploy-manage/deploy/cloud-enterprise/post-installation-steps.md new file mode 100644 index 000000000..d276bcbc5 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/post-installation-steps.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-getting-started-post-installation.html +--- + +# Post-installation steps [ece-getting-started-post-installation] + +After your Elastic Cloud Enterprise installation is up, some additional steps might be required: + +* Add your own load balancer. Load balancers are user supplied and we do not currently provide configuration steps for you. +* [Add more capacity](../../maintenance/ece/scale-out-installation.md) to your Elastic Cloud Enterprise installation, [resize your deployment](resize-deployment.md), [upgrade to a newer Elasticsearch version](../../upgrade/deployment-or-cluster.md), and [add some plugins](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-add-plugins.html). +* [Configure ECE system deployments](system-deployments-configuration.md) to ensure a highly available and resilient setup. +* [Configure ECE for deployment templates](configure-deployment-templates.md) to indicate what kind of hardware you have available for Elastic Stack deployments. +* [Install your security certificates](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md) to enable TLS/SSL authentication for secure connections over HTTPS. +* [Add a snapshot repository](../../tools/snapshot-and-restore/cloud-enterprise.md) to enable regular backups of your Elasticsearch clusters. +* [Add more platform users](../../users-roles/cloud-enterprise-orchestrator/manage-users-roles.md) with role-based access control. +* Consider enabling encryption-at-rest (EAR) on your hosts. +* [Set up traffic filters](../../security/traffic-filtering.md) to restrict traffic to your deployment to only trusted IP addresses or VPCs. +* Learn how to work around host maintenance or a host failure by [moving nodes off of an allocator](../../maintenance/ece/move-nodes-instances-from-allocators.md). +* If you received a license from Elastic, [manage the licenses](../../license/manage-your-license-in-ece.md) for your Elastic Cloud Enterprise installation. + +::::{warning} +During installation, the system generates secrets that are placed into the `/mnt/data/elastic/bootstrap-state/bootstrap-secrets.json` secrets file, unless you passed in a different path with the --host-storage-path parameter. Keep the information in the `bootstrap-secrets.json` file secure by removing it from its default location and placing it into a secure storage location. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/prepare-environment.md b/deploy-manage/deploy/cloud-enterprise/prepare-environment.md new file mode 100644 index 000000000..3f30d671b --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/prepare-environment.md @@ -0,0 +1,33 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-prereqs.html +--- + +# Prepare your environment [ece-prereqs] + + +## Requirements [ece-prepare-requirements] + +::::{important} +These prerequisites are critical to establish a supported ECE configuration. Using unsupported combinations can cause a number of either intermediate or potentially permanent issues with your ECE environment, such as failures to create [system deployments](system-deployments-configuration.md), failures to upgrade workload deployments, proxy timeouts, data loss, and more. If upgrading ECE, read [upgrade your installation](../../upgrade/orchestrator/upgrade-cloud-enterprise.md) for guidance. +:::: + + +To prepare your hosts for their ECE installation, the following prerequisites **must** be met: + +* [Hardware prerequisites](ece-hardware-prereq.md) +* [Software prerequisites](ece-software-prereq.md) +* [Networking prerequisites](ece-networking-prereq.md) +* [Users and permissions prerequisites](ece-users-permissions.md) + + +## Best practices and recommendations [ece-prepare-recommendations] + +To prepare your hosts for ECE installation, the following best practices are recommended and should be considered: + +* [High availability](ece-ha.md) - For production and mission-critical systems, high availability **must** be considered +* [Separation of roles](ece-roles.md) - To group components on ECE and prevent conflicting workloads, consider role separation +* [Load balancers](ece-load-balancers.md) - Using a load balancer is **strongly recommended** +* [JVM heap sizes](ece-jvm.md) - Configure the proper JVM heap size based on your use cases +* [Wildcard DNS record](ece-wildcard-dns.md) - Configure your own wildcard DNS record for production systems +* [Manage installation capacity](ece-manage-capacity.md) - Configure your memory, CPU quotas, processors and storage properly diff --git a/deploy-manage/deploy/cloud-enterprise/resize-deployment.md b/deploy-manage/deploy/cloud-enterprise/resize-deployment.md new file mode 100644 index 000000000..ff437000d --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/resize-deployment.md @@ -0,0 +1,58 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-resize-deployment.html +--- + +# Resize deployment [ece-resize-deployment] + +Elasticsearch scales to whatever capacity you need and with as many nodes as the available resources can support. If you don’t have enough available resources, [add some capacity first](../../maintenance/ece/scale-out-installation.md). + +::::{tip} +You can also enable autoscaling on a deployment to have the available resources for components, such as data tiers and machine learning nodes, adjust automatically as the demands on the deployment change over time. Check [Deployment autoscaling](../../autoscaling.md) to learn more. +:::: + + +To resize a deployment: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From your deployment menu, go to the **Edit** page. +4. Change the deployment configuration: + + Fault tolerance + : If the initial deployment you created uses only one availability zone, it is not fault tolerant. On a production system, enable [high availability](ece-ha.md) by changing your deployment to use at least two availability zones, three for mission-critical deployments. The number of instances comes from the number of zones and the type of template. Having more nodes or instances lets you scale out horizontally by adding more processing capacity to your deployment. + + ::::{warning} + Deployments that use only one availability zone are not highly available and are at risk of data loss, if you do not [configure an external snapshot repository](../../tools/snapshot-and-restore/cloud-enterprise.md#ece-manage-repositories-add) to enable regular backups. To safeguard against data loss, you must use at least two data centers and configure an external repository for backups. + :::: + + + RAM per instance + : Node and instance capacity should be sufficient to sustain your search workload, even if you lose an availability zone. Currently, half of the memory is assigned to the JVM heap. For example, on an Elasticsearch cluster node with 32 GB RAM, 16 GB would be allotted to heap. Up to 64 GB RAM and 1 TB storage per node are supported. + + A summary of your sections for each instance and the entire deployment are available for you to review before finalizing your changes. + +5. Select **Save changes**. + + +## Example: From very small to very large [ece_example_from_very_small_to_very_large] + +This example shows you how to change an existing, very basic deployment to use high availability and to add capacity. + +To scale your deployment from very small to very large: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From your deployment menu, go to the **Edit** page. +4. Under **Fault tolerance**, select **3 zones** for mission critical environments*. +5. Under **RAM per instance**, select **64 GB memory / 2 TB storage**. +6. Select **Save changes**. + +There is no downtime when adding high availability. Deployments with high availability will continue to handle user requests, even if the configuration changes are applied. + diff --git a/deploy-manage/deploy/cloud-enterprise/resource-overrides.md b/deploy-manage/deploy/cloud-enterprise/resource-overrides.md new file mode 100644 index 000000000..58f293ba4 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/resource-overrides.md @@ -0,0 +1,16 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-resource-overrides.html +--- + +# Resource overrides [ece-resource-overrides] + +{{ecloud}} allocators allot {{es}} instance sizes based on RAM, where RAM is proportional to CPU and disk resources. As needed, you can temporarily override the allocated resources to stabilize the deployment. You should reset overrides as soon as possible, or make your the override permanent by [changing your configuration](working-with-deployments.md). + +The RAM to CPU proportions can’t be overridden per instance. + +You can override the RAM to disk storage capacity for an instance under **Override disk quota** from the instance’s drop-down menu. This can be helpful when troubleshooting [watermark errors](../../../troubleshoot/elasticsearch/fix-watermark-errors.md) that result in a red [cluster health](https://www.elastic.co/guide/en/elasticsearch/reference/current/_cluster_health.html) status, which blocks configuration changes. A **Reset system default** message appears while disk quota overrides are set. Overriding the disk storage capacity does not restart the {{es}} node. + +Alternatively, you can override all resource allocations by selecting **Override instance size** from the instance’s drop-down menu. This overrides the alloted RAM, maintaining a proportional CPU and disk size. This can be helpful if the {{es}} cluster is overwhelmed by requests. You should [resize the deployment](resize-deployment.md) when the volume of requests stabilizes. Overriding the instance size restarts the {{es}} node. + +When an instance within a deployment has resource overrides, it displays a warning banner reading **Elastic added temporary capacity to stabilize the deployment**. [Configuration changes](working-with-deployments.md) can still be safely submitted. diff --git a/deploy-manage/deploy/cloud-enterprise/search-filter-deployments.md b/deploy-manage/deploy/cloud-enterprise/search-filter-deployments.md new file mode 100644 index 000000000..65dec8edf --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/search-filter-deployments.md @@ -0,0 +1,25 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-find.html +--- + +# Search and filter deployments [ece-find] + +When you installed Elastic Cloud Enterprise and [logged into the Cloud UI](log-into-cloud-ui.md) for the first time, you were greeted by two deployments. We’ve also shown you how to [create your own first deployment](create-deployment.md), but that still only makes a few deployments. What if you had hundreds of deployments to look after or maybe even a thousand? How would you find the ones that need your attention? + +The **Deployments** page in the Cloud UI provides several ways to find deployments that might need your attention, whether that’s deployments that have a problem or deployments that are at a specific version level or really almost anything you might want to find on a complex production system: + +* Check the visual health indicators of deployments +* Search for partial or whole deployment names or IDs in the search text box +* Add filters to the **Deployments** view to filter for specific conditions: + + :::{image} ../../../images/cloud-enterprise-deployment-filter.png + :alt: Add a filter + ::: + + Looking for all deployments of a specific version, because you want to upgrade them? Easy. Or what about that deployments you noticed before lunch that seemed to be spending an awfully long time changing its configuration—​is it done? Just add a filter to find any ongoing configuration changes. + + + + + diff --git a/deploy-manage/deploy/cloud-enterprise/statistics-collected-by-cloud-enterprise.md b/deploy-manage/deploy/cloud-enterprise/statistics-collected-by-cloud-enterprise.md new file mode 100644 index 000000000..a61fd6031 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/statistics-collected-by-cloud-enterprise.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-phone-home.html +--- + +# Statistics collected by Elastic Cloud Enterprise [ece-phone-home] + +When you [log into the Cloud UI](log-into-cloud-ui.md) for the first time, you are asked to agree to the software license agreement and can opt out of sharing some basic usage statistics about Elastic Cloud Enterprise with Elastic. These statistics are never shared with anyone else. If you are unsure about opting out, the following information describes what we collect. + +For each Elastic Cloud Enterprise installation, we collect: + +* Installation ID +* License information +* The number of hosts in the installation +* The number of allocators +* The total capacity by provided by allocators +* The total RAM used by allocators +* The availability zone each allocator belongs to +* The total RAM available to and the total RAM used by each availability zone +* The number of Elasticsearch clusters + +For each Elasticsearch cluster, we collect: + +* Whether a cluster has a Kibana instance associated with it +* Whether monitoring is configured + +Sharing these statistics with us can help us understand how you use our product better and can help us improve the product. + +If you already agreed to statistics sharing and would prefer to opt out, you can follow these steps: + +1. [Log into the Cloud UI](log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Turn off the **Share usage statistics with Elastic** setting. + diff --git a/deploy-manage/deploy/cloud-enterprise/switch-from-apm-to-integrations-server-payload.md b/deploy-manage/deploy/cloud-enterprise/switch-from-apm-to-integrations-server-payload.md new file mode 100644 index 000000000..91addf380 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/switch-from-apm-to-integrations-server-payload.md @@ -0,0 +1,368 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-integrations-server-apm-switch.html +--- + +# Switch from APM to Integrations Server payload [ece-integrations-server-apm-switch] + +This example shows how to use the Elastic Cloud Enterprise RESTful API to switch from using [APM & Fleet Server](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-apm-and-fleet.html) to [Integrations Server](manage-integrations-server.md). + + +## Requirements [ece_requirements_5] + +Given a deployment that is using an APM & Fleet Server with Elastic Stack version 8.0 or later, it is possible to start using Integrations Server instead by updating the deployment with an Integrations Server payload. Switching from APM & Fleet Server to Integrations Server in this way ensures that the endpoints and credentials currently used by APM Server and Fleet Server remain the same after the switch. + +In order to start using the Integrations Server payload, you first need to enable the APM integration for Elastic Agent by following the steps in [Switch to the Elastic APM integration](https://www.elastic.co/guide/en/apm/guide/current/apm-integration-upgrade-steps-ess.html). + + +## API request example [ece_api_request_example_3] + +The example shows how to use the API to create a deployment with APM with version 8.0 and update the deployment to switch to Integrations Server. + + +### Create a deployment with APM [ece_create_a_deployment_with_apm] + +::::{note} +When creating a deployment with version 8.0 using an APM payload, the APM integration for Elastic Agent is enabled by default. +:::: + + +The following creates a deployment that uses the `default` deployment template in the `ece-region` + +```sh +curl -k -X POST -H "Authorization: ApiKey $ECE_API_KEY" https://$COORDINATOR_HOST:12443/api/v1/deployments -H 'content-type: application/json' -d ' +{ + "resources": { + "elasticsearch": [ + { + "ref_id": "main-elasticsearch", + "region": "ece-region", <1> + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "node_roles": [ + "master", + "ingest", + "transform", + "data_hot", + "remote_cluster_client", + "data_content" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "hot" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.default", + "size": { + "value": 4096, + "resource": "memory" + } + }, + { + "id": "warm", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "warm" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.highstorage", + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "cold", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.highstorage", + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "frozen", + "node_roles": [ + "data_frozen" + ], + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "data.frozen", + "size": { + "value": 0, + "resource": "memory" + } + }, + { + "id": "coordinating", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "zone_count": 1, + "instance_configuration_id": "coordinating", + "size": { + "value": 0, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "id": "master", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "zone_count": 1, + "instance_configuration_id": "master", + "size": { + "value": 0, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "id": "ml", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "zone_count": 1, + "instance_configuration_id": "ml", + "size": { + "value": 1024, + "resource": "memory" + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + } + ], + "elasticsearch": { + "version": "8.0.0" + }, + "autoscaling_enabled": false, + "deployment_template": { + "id": "default" <2> + } + }, + "settings": { + "dedicated_masters_threshold": 6, + "snapshot": { + "enabled": false + } + } + } + ], + "kibana": [ + { + "ref_id": "main-kibana", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "ece-region", + "plan": { + "zone_count": 1, + "cluster_topology": [ + { + "instance_configuration_id": "kibana", + "size": { + "value": 1024, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "kibana": { + "version": "8.0.0" + } + } + } + ], + "enterprise_search": [], + "apm": [ + { + "ref_id": "main-apm", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "apm", + "size": { + "value": 512, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "apm": { + "version": "8.0.0" + } + } + } + ] + }, + "name": "switch-to-integrations-server", + "metadata": { + "system_owned": false + } +} +' +``` + +1. The region where the deployment is created +2. The deployment template used by the deployment + + + +### Identify the instance configuration to use for Integrations Server [ece_identify_the_instance_configuration_to_use_for_integrations_server] + +Once the deployment is created, find the `instance_configuration_id` for the Integrations Server payload. It must be supported by the deployment template used by the deployment created in the previous step. + +In the example above, the deployment was created using the `default` deployment template in the `ece-region` region. + +To find the `instance_configuration_id`, fetch the deployment template using the template ID, the region, and the version used by the deployment (Integrations Server is supported on version 8.0 and higher). + +```sh +curl -XGET \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://$COORDINATOR_HOST:12443/api/v1/deployments/templates/default?region=ece-region&show_instance_configurations=false&stack_version=8.0.0" +``` + +This return a template like + +```json +{ + "id": "default", + "name": "Default", + "description": "Default deployment template for clusters", + "deployment_template": { + "resources": { + "elasticsearch": [ + ... + ], + "kibana": [ + ... + ], + "apm": [ + ... + ], + "enterprise_search": [ + ... + ], + "integrations_server": [ + { + "ref_id": "integrations_server-ref-id", + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "ece-region", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "integrations.server", <1> + "size": { + "value": 512, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "integrations_server": {} + } + } + ] + } + }, + "system_owned": true, + "metadata": [ + { + "key": "parent_solution", + "value": "stack" + } + ], + "order": 0, + "template_category_id": "default" +} +``` + +1. The instance configuration ID to use in the Integrations Server payload in the next step. + + + +### Update deployment using the Integrations Server payload [ece_update_deployment_using_the_integrations_server_payload] + +Finally, to switch to Integrations Server, update the deployment using the Integrations Server payload, setting `instance_configuration_id` to the value identified in the previous step. + +```sh +curl -XPUT \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://$COORDINATOR_HOST:12443/api/v1/deployments/" \ +-d ' +{ + "prune_orphans": false, <2> + "resources": { + "integrations_server": [ + { + "region": "ece-region", + "ref_id": "main-integrations_server", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "integrations.server", <1> + "size": { + "value": 512, + "resource": "memory" + }, + "zone_count": 1 + } + ], + "integrations_server": { + "version": "8.0.0" + }, + "transient": { + "strategy": { + "autodetect": {} + } + } + } + } + ] + } +} +' +``` + +1. Make sure to use the `instance_configuration_id` for Integrations Server from the deployment template. +2. Make sure `prune_orphans` is set to `false`. `prune_orphans` is an important parameter. It specifies how resources not included in the body of this PUT request should be handled. If `false`, those resources not included are kept intact. + + diff --git a/deploy-manage/deploy/cloud-enterprise/system-deployments-configuration.md b/deploy-manage/deploy/cloud-enterprise/system-deployments-configuration.md new file mode 100644 index 000000000..7c45c2c23 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/system-deployments-configuration.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-system-clusters-configuration.html +--- + +# System deployments configuration [ece-system-clusters-configuration] + +When installing ECE, you will notice that several Elasticsearch clusters get created as part of the installation process. Those are the *system deployments* which are part of the ECE control plane. You must make sure that they are configured and sized correctly to ensure you have a production-ready installation. + +We will review each cluster and provide recommendations to make sure that you are following best practices when starting your ECE journey. + +::::{note} +By default, the system deployments have a dedicated `system_owned` flag set to `true` to avoid mistakenly changing the configuration of those clusters. Most configuration changes suggested in this section do not require this flag to be set to `false`, but there are some cases where changing the flag might be required. If you do change this flag, always make sure to set it back to `true` once you have completed the changes. The flag can be set by navigating to the **Data** section in the **Advanced cluster configuration** page. +:::: + + + +## Overview of system deployments [ece_overview_of_system_deployments] + +Admin console - `admin-console-elasticsearch` +: Stores the state of your deployments, plans, and other operational data. If this cluster is not available, there will be several unexpected behaviors in the Cloud UI, such as stale or wrong status indicators for deployments, allocators, hosts, and more. + +Logging and metrics - `logging-and-metrics` +: As part of an ECE environment, a Beats sidecar with Filebeat and Metricbeat is installed on each ECE host. The logs and metrics collected by those beats are indexed in the `logging-and-metrics` cluster. This includes ECE service logs, such as proxy logs, director logs, and more. It also includes hosted deployments logs, security cluster audit logs, and metrics, such as CPU and disk usage. Data is collected from all hosts. This information is critical in order to be able to monitor ECE and troubleshoot issues. You can also use this data to configure watches to alert you in case of an issue, or machine learning jobs that can provide alerts based on anomalies or forecasting. + +Security - `security` +: When you enable the user management feature, you trigger the creation of a third system deployment named `security`. This cluster stores all security-related configurations, such as native users and the related native realm, integration with SAML or LDAP as external authentication providers and their role mapping, and the realm ordering. The health of this cluster is critical to provide access to the ECE Cloud UI and REST API. To learn more, check [Configure role-based access control](../../users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). Beginning with Elastic Cloud Enterprise 2.5.0 the `security` cluster is created automatically for you. It is recommended to use the [dedicated API](https://www.elastic.co/guide/en/cloud-enterprise/current/update-security-deployment.html) to manage the cluster. + + +## High availability [ece_high_availability] + +ECE supports the concept of [availability zones](ece-ha.md) and requires three availability zones to be configured for the best fault tolerance. + +The system deployments are created when you install ECE or enable the user management feature, at which point they are not yet configured for high availability. As soon as you finish the installation process, you should change the configuration to ensure your system deployments are highly available and deployed across two or three availability zones. To configure your system deployments to be highly available, navigate to the **Edit** page for the cluster and change the number of availability zones under **Fault tolerance**. + +For the `logging-and-metrics` cluster, you might want to also make sure that your Kibana instance and other components are deployed across multiple availability zones, since you will often access that cluster using Kibana. You can change the availability zones for Kibana on the same **Edit** page. + +::::{note} +For the `security` cluster, the number of zones must be set to 3 for high availability, otherwise you may encounter errors when trying to upgrade ECE versions. +:::: + + + +### Backup and restore [ece_backup_and_restore] + +ECE lets you manage snapshot repositories, so that you can back up and restore your clusters. This mechanism allows you to centrally manage your snapshot repositories, assigning them to deployments, and restoring snapshots to an existing or new deployment. Since the `admin-console-elasticsearch` and `security` clusters have a key role in making sure your ECE installation is operational, it’s important that you configure a snapshot repository after you complete your ECE installation and enable snapshots for both the `admin-console-elasticsearch` and `security` clusters, so that you can easily restore them if needed. + +As mentioned earlier, the `logging-and-metrics` cluster stores important information about your environment logs and metrics. There are also additional configurations provided out-of-the-box, such as data views (formerly *index patterns*), visualizations, and dashboards, that will require running an external script to recreate if you do not have a snapshot to restore from. We recommend that you also back up the `logging-and-metrics` cluster, though it is up to you to decide if that information should be available to be restored. + +To configure snapshot repositories, check [Add snapshot repository configurations](../../tools/snapshot-and-restore/cloud-enterprise.md#ece-manage-repositories-add). + + +### Sizing [ece_sizing] + +Both the `admin-console-elasticsearch` and `security` clusters require relatively small amounts of RAM and almost no disk space, so increasing their size to 4 GB or 8 GB RAM per data node should be sufficient. + +Undersizing the `logging-and-metrics` cluster can lead to saturation and degrade the health of that cluster, and eventually prevent you from monitoring your ECE installation and its hosted deployments. + +When sizing your `logging-and-metrics` cluster, consider: + +* the expected workload, which affects the daily ingest size. +* the number of ECE hosts, deployments, and log types you want to enable, such as slow logs or audit logs. +* the desired retention period for the data. As with any other time-series data, you must properly manage your indices and delete old indices based on that retention period. + + +### Access to system deployments [ece_access_to_system_deployments] + +In the case of the `admin-console-elasticsearch` and `security` system deployments, the team managing ECE and assigned to the platform admin role should have permission to change each system deployment configuration and also to access each cluster itself. + +The `logging-and-metrics` cluster is different since, as an ECE admin, you likely want to provide users with access to the cluster in order to troubleshoot issues without your assistance, for example. In order to manage access to that cluster, you can configure roles that will provide access to the relevant indices, map those to users, and manage access to Kibana by leveraging the Elastic security integration with your authentication provider, such as LDAP, SAML, or AD. To configure one of those security realms, check [LDAP](../../users-roles/cluster-or-deployment-auth/ldap.md), [Active Directory](../../users-roles/cluster-or-deployment-auth/active-directory.md) or [SAML](../../users-roles/cluster-or-deployment-auth/saml.md). + +::::{note} +The `logging-and-metrics` cluster is only intended for troubleshooting ECE deployment issues. If your use case involves modifying or normalizing logs from {{es}} or {{kib}}, use a separate [dedicated monitoring deployment](../../monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md) instead. +:::: + + +You can’t use ECE’s single sign-on (SSO) to access system deployments. + +::::{note} +Enabling integration with external authentication provider requires that you set the `system_owned` flag to `false` in order to change the elasticsearch.yaml configuration. Remember to set the flag back to `true` after you are done. +:::: + + diff --git a/deploy-manage/deploy/cloud-enterprise/tools-apis.md b/deploy-manage/deploy/cloud-enterprise/tools-apis.md new file mode 100644 index 000000000..6502ce5d4 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/tools-apis.md @@ -0,0 +1,5 @@ +# Tools and APIs + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/310 \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-enterprise/working-with-deployments.md b/deploy-manage/deploy/cloud-enterprise/working-with-deployments.md new file mode 100644 index 000000000..19f8a8738 --- /dev/null +++ b/deploy-manage/deploy/cloud-enterprise/working-with-deployments.md @@ -0,0 +1,24 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-stack-getting-started.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-deployments.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-change-deployment.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-monitoring-deployments.html +--- + +# Working with deployments + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/339 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-stack-getting-started.md +% Notes: 9 child and sub-child docs (some of them are about "adding data to Elasticsearch" which might fit better somewhere else. we need to analyze that. We are missing https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-deployments.html.... on purpose? +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-administering-deployments.md +% Notes: probably just a redirect +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-change-deployment.md +% Notes: another redirect +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-monitoring-deployments.md +% Notes: mostly redirect \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s.md b/deploy-manage/deploy/cloud-on-k8s.md new file mode 100644 index 000000000..dff4d8ffc --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s.md @@ -0,0 +1,23 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-overview.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-advanced-topics.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-supported.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_learn_more_about_eck.html +--- + +# Elastic Cloud on Kubernetes + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/357 + +% Scope notes: Maybe we can even leave it as it is. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-overview.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-advanced-topics.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-supported.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s_learn_more_about_eck.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/accessing-services.md b/deploy-manage/deploy/cloud-on-k8s/accessing-services.md new file mode 100644 index 000000000..7b6d059ee --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/accessing-services.md @@ -0,0 +1,28 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-accessing-elastic-services.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-request-elasticsearch-endpoint.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-services.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-security.html +--- + +# Accessing services + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/357 + +% Scope notes: Merge the selected docs into one: - First describe how to access Elasticsearch. - Describe the services that ECK creates for ES. - Provide the example and instructions + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-accessing-elastic-services.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-request-elasticsearch-endpoint.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-services.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-security.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$k8s-allow-public-access$$$ + +$$$k8s-setting-up-your-own-certificate$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/advanced-configuration-logstash.md b/deploy-manage/deploy/cloud-on-k8s/advanced-configuration-logstash.md new file mode 100644 index 000000000..6972733ee --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/advanced-configuration-logstash.md @@ -0,0 +1,81 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-logstash-advanced-configuration.html +--- + +# Advanced configuration [k8s-logstash-advanced-configuration] + +## Setting JVM options [k8s-logstash-jvm-options] + +You can change JVM settings by using the `LS_JAVA_OPTS` environment variable to override default settings in `jvm.options`. This approach ensures that expected settings from `jvm.options` are set, and only options that explicitly need to be overridden are. + +To do, this, set the `LS_JAVA_OPTS` environment variable in the container definition of your Logstash resource: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + podTemplate: + spec: + containers: + - name: logstash + env: + - name: LS_JAVA_OPTS <1> + value: "-Xmx2g -Xms2g" +``` + +1. This will change the maximum and minimum heap size of the JVM on each pod to 2GB + + + +## Setting keystore [k8s-logstash-keystore] + +You can specify sensitive settings with Kubernetes secrets. ECK automatically injects these settings into the keystore before it starts Logstash. The ECK operator continues to watch the secrets for changes and will restart Logstash Pods when it detects a change. + +The Logstash Keystore can be password protected by setting an environment variable called `LOGSTASH_KEYSTORE_PASS`. Check out [Logstash Keystore](https://www.elastic.co/guide/en/logstash/current/keystore.html#keystore-password) documentation for details. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: logstash-keystore-pass +stringData: + LOGSTASH_KEYSTORE_PASS: changed <1> + +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash-sample +spec: + version: 8.16.1 + count: 1 + pipelines: + - pipeline.id: main + config.string: |- + input { exec { command => 'uptime' interval => 10 } } + filter { + if ("${HELLO:}" != "") { <2> + mutate { add_tag => ["awesome"] } + } + } + secureSettings: + - secretName: logstash-secure-settings + podTemplate: + spec: + containers: + - name: logstash + env: + - name: LOGSTASH_KEYSTORE_PASS + valueFrom: + secretKeyRef: + name: logstash-keystore-pass + key: LOGSTASH_KEYSTORE_PASS +``` + +1. Value of password to protect the Logstash keystore +2. The syntax for referencing keys is identical to the syntax for environment variables + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/advanced-configuration-maps-server.md b/deploy-manage/deploy/cloud-on-k8s/advanced-configuration-maps-server.md new file mode 100644 index 000000000..7293fb67b --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/advanced-configuration-maps-server.md @@ -0,0 +1,65 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-maps-advanced-configuration.html +--- + +# Advanced configuration [k8s-maps-advanced-configuration] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +If you already looked at the [Elasticsearch on ECK](elasticsearch-configuration.md) documentation, some of these concepts might sound familiar to you. The resource definitions in ECK share the same philosophy when you want to: + +* Customize the Pod configuration +* Customize the product configuration +* Manage HTTP settings + +## Elastic Maps Server configuration [k8s-maps-configuration] + +You can add any valid Elastic Maps Server setting as documented on the [product](https://www.elastic.co/guide/en/kibana/current/maps-connect-to-ems.html#elastic-maps-server-configuration) page to the `spec.config` section. + +The following example demonstrates how to set the log level to `debug`: + +```yaml +apiVersion: maps.k8s.elastic.co/v1alpha1 +kind: ElasticMapsServer +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + config: + logging.level: debug +``` + +Alternatively, settings can be provided through a Secret specified in the `configRef` element: + +```yaml +apiVersion: maps.k8s.elastic.co/v1alpha1 +kind: ElasticMapsServer +metadata: + name: quickstart +spec: + version: 8.16.1 + configRef: + secretName: maps-config +--- +apiVersion: v1 +kind: Secret +metadata: + name: maps-config +stringData: + elastic-maps-server.yml: |- + logging.level: debug +``` + +Refer to [Set compute resources for Kibana, Enterprise Search, Elastic Maps Server, APM Server and Logstash](manage-compute-resources.md#k8s-compute-resources-kibana-and-apm) for adjusting compute resources for Elastic Maps Server. + + +## Scale out an Elastic Maps Server deployment [k8s-maps-scaling] + +To deploy more than one instance of maps, all the instances must mount the data volume containing the basemap read only. When this is the case, scaling out is just a matter of increasing the `count` attribute. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/advanced-configuration.md b/deploy-manage/deploy/cloud-on-k8s/advanced-configuration.md new file mode 100644 index 000000000..98f7b948e --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/advanced-configuration.md @@ -0,0 +1,173 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-apm-advanced-configuration.html +--- + +# Advanced configuration [k8s-apm-advanced-configuration] + +This section covers the following topics: + +* [Use APM Agent central configuration](#k8s-apm-agent-central-configuration) +* [Customize the APM Server configuration](#k8s-apm-customize-configuration) +* [Specify secure settings for your APM Server](#k8s-apm-secure-settings) +* [Reference an existing Elasticsearch cluster](#k8s-apm-existing-es) + +## Use APM Agent central configuration [k8s-apm-agent-central-configuration] + +[APM Agent configuration management](https://www.elastic.co/guide/en/kibana/current/agent-configuration.html) [7.5.1] allows you to configure your APM Agents centrally from the Kibana APM app. To use this feature, the APM Server needs to be configured with connection details of the Kibana instance. If Kibana is managed by ECK, you can simply add a `kibanaRef` attribute to the APM Server specification: + +```yaml +cat < + readOnlyRootFilesystem: true + runAsNonRoot: true + allowPrivilegeEscalation: false + runAsUser: 1000 <2> + volumeMounts: <3> + - name: search-tmp + mountPath: /usr/share/enterprise-search/tmp + - name: tmp + mountPath: /tmp + - name: filebeat-data + mountPath: /usr/share/enterprise-search/filebeat/data + - name: war-files + mountPath: /usr/share/enterprise-search/lib/war + resources: + requests: + cpu: 3 + memory: 8Gi + limits: + memory: 8Gi + env: <4> + - name: JAVA_OPTS + value: -Xms7500m -Xmx7500m + initContainers: <5> + - name: init-war-dir + image: docker.elastic.co/enterprise-search/enterprise-search:8.16.1 + command: ['sh', '-c', 'cp --verbose -r /usr/share/enterprise-search/lib/war/. /usr/share/enterprise-search-war-tmp'] + volumeMounts: + - name: war-files + mountPath: /usr/share/enterprise-search-war-tmp + volumes: <6> + - name: war-files + emptyDir: {} + - name: filebeat-data + emptyDir: {} + - name: search-tmp + emptyDir: + medium: Memory + - name: tmp + emptyDir: + medium: Memory +``` + +1. Adds a security context to define permissions and access control settings for the `enterprise-search` container. +2. Sets the user to random UID `1000` to run the container as a non-root user. +3. Adds volume mounts for `search-tmp`, `tmp`, `filebeat-data`, and `war-files` to the `enterprise-search` container. +4. Adds the variable `JAVA_OPTS` to pass options and configurations to the Java Virtual Machine (JVM). +5. Adds an init container to copy WAR files to a temporary location. +6. Adds volumes for WAR files and adds volumes with in-memory storage for `search-tmp` and `tmp`. + + + + +## Expose Enterprise Search [k8s-enterprise-search-expose] + +By default ECK manages self-signed TLS certificates to secure the connection to Enterprise Search. It also restricts the Kubernetes service to `ClusterIP` type that cannot be accessed publicly. + +Check [how to access Elastic Stack services](accessing-services.md) to customize TLS settings and expose the service. + +::::{note} +When exposed outside the scope of `localhost`, make sure to set both `ent_search.external_url`, and `kibana.host` accordingly in the Enterprise Search configuration. +:::: + + + +## Customize the connection to an Elasticsearch cluster [k8s-enterprise-search-connect-es] + +The `elasticsearchRef` element allows ECK to automatically configure Enterprise Search to establish a secured connection to a managed Elasticsearch cluster. By default it targets all nodes in your cluster. If you want to direct traffic to specific nodes of your Elasticsearch cluster, refer to [*Traffic Splitting*](requests-routing-to-elasticsearch-nodes.md) for more information and examples. + + +## Connect to an external Elasticsearch cluster [k8s-enterprise-search-connect-non-eck-es] + +### Automatically [k8s_automatically] + +Refer to [*Connect to external Elastic resources*](connect-to-external-elastic-resources.md) to automatically configure Enterprise Search using connection settings from a `Secret`. + + +### Manually [k8s_manually] + +If you do not want to use the `elasticsearchRef` mechanism you can manually configure Enterprise Search to access any available Elasticsearch cluster: + +```yaml +apiVersion: enterprisesearch.k8s.elastic.co/v1 +kind: EnterpriseSearch +metadata: + name: enterprise-search-quickstart +spec: + version: 8.16.1 + count: 1 + configRef: + secretName: elasticsearch-credentials +--- +kind: Secret +apiVersion: v1 +metadata: + name: elasticsearch-credentials +stringData: + enterprise-search.yml: |- + elasticsearch.host: [https://elasticsearch-url:9200](https://elasticsearch-url:9200) + elasticsearch.username: elastic + elasticsearch.password: my-password + elasticsearch.ssl.enabled: true +``` + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-examples-beats.md b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-beats.md new file mode 100644 index 000000000..50da9fa39 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-beats.md @@ -0,0 +1,104 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-beat-configuration-examples.html +--- + +# Configuration Examples [k8s-beat-configuration-examples] + +In this section you can find manifests that address a number of common use cases and can be your starting point in exploring Beats deployed with ECK. These manifests are self-contained and work out-of-the-box on any non-secured Kubernetes cluster. They all contain three-node Elasticsearch cluster and single Kibana instance. All Beat configurations set up Kibana dashboards if they are available for a given Beat and all required RBAC resources. + +::::{warning} +The examples in this section are purely descriptive and should not be considered to be production-ready. Some of these examples use the `node.store.allow_mmap: false` setting which has performance implications and should be tuned for production workloads, as described in [Virtual memory](virtual-memory.md). +:::: + + +## Metricbeat for Kubernetes monitoring [k8s_metricbeat_for_kubernetes_monitoring] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/metricbeat_hosts.yaml +``` + +Deploys Metricbeat as a DaemonSet that monitors the usage of the following resources: + +* Host: CPU, memory, network, filesystem. +* Kubernetes: Nodes, Pods, Containers, Volumes. + + +## Filebeat with autodiscover [k8s_filebeat_with_autodiscover] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/filebeat_autodiscover.yaml +``` + +Deploys Filebeat as a DaemonSet with the autodiscover feature enabled. It collects logs from Pods in every namespace and loads them to the connected Elasticsearch cluster. + + +## Filebeat with autodiscover for metadata [k8s_filebeat_with_autodiscover_for_metadata] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/filebeat_autodiscover_by_metadata.yaml +``` + +Deploys Filebeat as a DaemonSet with the autodiscover feature enabled. Logs from Pods that match the following criteria are shipped to the connected Elasticsearch cluster: + +* Pod is in `log-namespace` namespace +* Pod has `log-label: "true"` label + + +## Filebeat without autodiscover [k8s_filebeat_without_autodiscover] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/filebeat_no_autodiscover.yaml +``` + +Deploys Filebeat as a DaemonSet with the autodiscover feature disabled. Uses the entire logs directory on the host as the input source. This configuration does not require any RBAC resources as no Kubernetes APIs are used. + + +## Elasticsearch and Kibana Stack Monitoring [k8s_elasticsearch_and_kibana_stack_monitoring] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/stack_monitoring.yaml +``` + +Deploys Metricbeat configured for Elasticsearch and Kibana [Stack Monitoring](https://www.elastic.co/guide/en/kibana/current/xpack-monitoring.md) and Filebeat using autodiscover. Deploys one monitored Elasticsearch cluster and one monitoring Elasticsearch cluster. You can access the Stack Monitoring app in the monitoring cluster’s Kibana. + +::::{note} +In this example, TLS verification is disabled when Metricbeat communicates with the monitored cluster, which is not secure and should not be used in production. To solve this, use custom certificates and configure Metricbeat to verify them. +:::: + + + +## Heartbeat monitoring Elasticsearch and Kibana health [k8s_heartbeat_monitoring_elasticsearch_and_kibana_health] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/heartbeat_es_kb_health.yaml +``` + +Deploys Heartbeat as a single Pod deployment that monitors the health of Elasticsearch and Kibana by TCP probing their Service endpoints. Heartbeat expects that Elasticsearch and Kibana are deployed in the `default` namespace. + + +## Auditbeat [k8s_auditbeat] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/auditbeat_hosts.yaml +``` + +Deploys Auditbeat as a DaemonSet that checks file integrity and audits file operations on the host system. + + +## Packetbeat monitoring DNS and HTTP traffic [k8s_packetbeat_monitoring_dns_and_http_traffic] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/packetbeat_dns_http.yaml +``` + +Deploys Packetbeat as a DaemonSet that monitors DNS on port `53` and HTTP(S) traffic on ports `80`, `8000`, `8080` and `9200`. + + +## OpenShift monitoring [k8s_openshift_monitoring] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/beats/openshift_monitoring.yaml +``` + +Deploys Metricbeat as a DaemonSet that monitors the host resource usage (CPU, memory, network, filesystem), OpenShift resources (Nodes, Pods, Containers, Volumes), API Server and Filebeat using autodiscover. Deploys an Elasticsearch cluster and Kibana to centralize data collection. diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-examples-fleet.md b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-fleet.md new file mode 100644 index 000000000..fab24a105 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-fleet.md @@ -0,0 +1,62 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent-fleet-configuration-examples.html +--- + +# Configuration Examples [k8s-elastic-agent-fleet-configuration-examples] + +This section contains manifests that illustrate common use cases, and can be your starting point in exploring {{agent}} deployed with ECK. These manifests are self-contained and work out-of-the-box on any non-secured {{k8s}} cluster. They all contain a three-node {{es}} cluster, a single {{kib}} instance and a single {{fleet-server}} instance. + +::::{warning} +The examples in this section are for illustration purposes only and should not be considered to be production-ready. Some of these examples use the `node.store.allow_mmap: false` setting which has performance implications and should be tuned for production workloads, as described in [Virtual memory](virtual-memory.md). +:::: + + +## System and {{k8s}} {integrations} [k8s_system_and_k8s_integrations] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/fleet-kubernetes-integration.yaml +``` + +Deploys {{agent}} as a DaemonSet in {{fleet}} mode with System and {{k8s}} {integrations} enabled. System integration collects syslog logs, auth logs and system metrics (for CPU, I/O, filesystem, memory, network, process and others). {{k8s}} {integrations} collects API server, Container, Event, Node, Pod, Volume and system metrics. + + +## System and {{k8s}} {integrations} running as non-root [k8s_system_and_k8s_integrations_running_as_non_root] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/fleet-kubernetes-integration-nonroot.yaml +``` + +The provided example is functionally identical to the previous section but runs the {{agent}} processes (both the {{agent}} running as the {{fleet}} server and the {{agent}} connected to {{fleet}}) as a non-root user by utilizing a DaemonSet to ensure directory and file permissions. + +::::{note} +The DaemonSet itself must run as root to set up permissions and ECK >= 2.10.0 is required. +:::: + + + +## Custom logs integration with autodiscover [k8s_custom_logs_integration_with_autodiscover] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/fleet-custom-logs-integration.yaml +``` + +Deploys {{agent}} as a DaemonSet in {{fleet}} mode with Custom Logs integration enabled. Collects logs from all Pods in the `default` namespace using autodiscover feature. + + +## APM integration [k8s_apm_integration] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/fleet-apm-integration.yaml +``` + +Deploys single instance {{agent}} Deployment in {{fleet}} mode with APM integration enabled. + + +## Synthetic monitoring [k8s_synthetic_monitoring] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/synthetic-monitoring.yaml +``` + +Deploys an {{fleet}}-enrolled {{agent}} that can be used as for [Synthetic monitoring](https://www.elastic.co/guide/en/observability/current/monitor-uptime-synthetics.html). This {{agent}} uses the `elastic-agent-complete` image. The agent policy still needs to be [registered as private location](https://www.elastic.co/guide/en/observability/current/synthetics-private-location.html#synthetics-private-location-add) in {{kib}}. diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-examples-logstash.md b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-logstash.md new file mode 100644 index 000000000..1d7ca54ae --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-logstash.md @@ -0,0 +1,78 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-logstash-configuration-examples.html +--- + +# Configuration examples [k8s-logstash-configuration-examples] + +This section contains manifests that illustrate common use cases, and can be your starting point in exploring Logstash deployed with ECK. These manifests are self-contained and work out-of-the-box on any non-secured Kubernetes cluster. They all contain a three-node Elasticsearch cluster and a single Kibana instance. + +::::{warning} +The examples in this section are for illustration purposes only. They should not be considered production-ready. Some of these examples use the `node.store.allow_mmap: false` setting on {{es}} which has performance implications and should be tuned for production workloads, as described in [Virtual memory](virtual-memory.md). +:::: + + +## Single pipeline defined in CRD [k8s-logstash-configuration-single-pipeline-crd] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-eck.yaml +``` + +Deploys Logstash with a single pipeline defined in the CRD + + +## Single Pipeline defined in Secret [k8s-logstash-configuration-single-pipeline-secret] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-pipeline-as-secret.yaml +``` + +Deploys Logstash with a single pipeline defined in a secret, referenced by a `pipelineRef` + + +## Pipeline configuration in mounted volume [k8s-logstash-configuration-pipeline-volume] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-pipeline-as-volume.yaml +``` + +Deploys Logstash with a single pipeline defined in a secret, mounted as a volume, and referenced by `path.config` + + +## Writing to a custom Elasticsearch index [k8s-logstash-configuration-custom-index] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-es-role.yaml +``` + +Deploys Logstash and Elasticsearch, and creates an updated version of the `eck_logstash_user_role` to write to a user specified index. + + +## Creating persistent volumes for PQ and DLQ [k8s-logstash-configuration-pq-dlq] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-volumes.yaml +``` + +Deploys Logstash, Beats and Elasticsearch. Logstash is configured with two pipelines: + +* a main pipeline for reading from the {{beats}} instance, which will send to the DLQ if it is unable to write to Elasticsearch +* a second pipeline, that will read from the DLQ. In addition, persistent queues are set up. This example shows how to configure persistent volumes outside of the default `logstash-data` persistent volume. + + +## Elasticsearch and Kibana Stack Monitoring [k8s-logstash-configuration-stack-monitoring] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-monitored.yaml +``` + +Deploys an Elasticsearch and Kibana monitoring cluster, and a Logstash that will send its monitoring information to this cluster. You can view the stack monitoring information in the monitoring cluster’s Kibana + + +## Multiple pipelines/multiple Elasticsearch clusters [k8s-logstash-configuration-multiple-pipelines] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/logstash/logstash-multi.yaml +``` + +Deploys Elasticsearch in prod and qa configurations, running in separate namespaces. Logstash is configured with a multiple pipeline→pipeline configuration, with a source pipeline routing to `prod` and `qa` pipelines. diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-examples-standalone.md b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-standalone.md new file mode 100644 index 000000000..73f6d7f12 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-examples-standalone.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent-configuration-examples.html +--- + +# Configuration examples [k8s-elastic-agent-configuration-examples] + +This section contains manifests that illustrate common use cases, and can be your starting point in exploring Elastic Agent deployed with ECK. These manifests are self-contained and work out-of-the-box on any non-secured Kubernetes cluster. They all contain a three-node Elasticsearch cluster and a single Kibana instance. Add the corresponding integration package to Kibana to install the dashboards, visualizations and other assets for each of these examples as described in [the Elastic Agent documentation](https://www.elastic.co/guide/en/fleet/current/elastic-agent-installation.html). + +::::{warning} +The examples in this section are for illustration purposes only and should not be considered to be production-ready. Some of these examples use the `node.store.allow_mmap: false` setting which has performance implications and should be tuned for production workloads, as described in [Virtual memory](virtual-memory.md). +:::: + + +## System integration [k8s_system_integration] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/system-integration.yaml +``` + +Deploys Elastic Agent as a DaemonSet in standalone mode with system integration enabled. Collects syslog logs, auth logs and system metrics (for CPU, I/O, filesystem, memory, network, process and others). + + +## Kubernetes integration [k8s_kubernetes_integration] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/kubernetes-integration.yaml +``` + +Deploys Elastic Agent as a DaemonSet in standalone mode with Kubernetes integration enabled. Collects API server, Container, Event, Node, Pod, Volume and system metrics. + + +## Multiple Elasticsearch clusters output [k8s_multiple_elasticsearch_clusters_output] + +```sh +kubectl apply -f https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/config/recipes/elastic-agent/multi-output.yaml +``` + +Deploys two Elasticsearch clusters and two Kibana instances together with single Elastic Agent DaemonSet in standalone mode with System integration enabled. System metrics are sent to the `elasticsearch` cluster. Elastic Agent monitoring data is sent to `elasticsearch-mon` cluster. + + +## Storing local state in host path volume [k8s_storing_local_state_in_host_path_volume] + +{{agent}} managed by ECK stores local state in a host path volume by default. This ensures that {{integrations}} run by the agent can continue their work without duplicating work that has already been done after the Pod has been recreated for example because of a Pod configuration change. Multiple replicas of an agent, for example {{fleet}} Servers, can not be deployed on the same underlying {{k8s}} node as they would try to use the same host path. There are 2 options for managing this feature: + +1. If local state storage in `hostPath` volumes is not desired this can be turned off by configuring an `emptyDir` volume instead. +2. If local state storage is still desired but running the Agent container as root is not allowed, then you can run a `DaemonSet` that adjusts the permissions for the Agent local state on each Node prior to running {{agent}}. Note that this `DaemonSet` must be `runAsUser: 0` and possibly `privileged: true`. Also note the {{kib}} changes required to trust the {{es}} CA when running in fleet mode. + +Full configuration examples exist in [Running as a non-root user](configuration-fleet.md#k8s-elastic-agent-running-as-a-non-root-user). diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-fleet.md b/deploy-manage/deploy/cloud-on-k8s/configuration-fleet.md new file mode 100644 index 000000000..70a8e35ab --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-fleet.md @@ -0,0 +1,395 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent-fleet-configuration.html +--- + +# Configuration [k8s-elastic-agent-fleet-configuration] + +{{fleet}}-managed {{agents}} must connect to {{fleet-server}} to receive their configurations. You can deploy {{fleet-server}} instances using ECKs Agent CRD with the appropriate configuration, as shown in [Fleet mode and Fleet Server](#k8s-elastic-agent-fleet-configuration-fleet-mode-and-fleet-server). + +To know more about {{fleet}} architecture and related components, check the {{fleet}} [documentation](https://www.elastic.co/guide/en/fleet/current/fleet-server.html). + +## {{fleet}} mode and {{fleet-server}} [k8s-elastic-agent-fleet-configuration-fleet-mode-and-fleet-server] + +To run both {{fleet-server}} and {{agent}} in {{fleet}}-managed mode, set the `mode` configuration element to `fleet`. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent-sample +spec: + mode: fleet +``` + +To run {{fleet-server}}, set the `fleetServerEnabled` configuration element to `true`, as shown in this example: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server-sample +spec: + mode: fleet + fleetServerEnabled: true +``` + +You can leave the default value `false` for any other case. + + +## Configure {{kib}} [k8s-elastic-agent-fleet-configuration-required-kibana-configuration] + +To have {{fleet}} running properly, the following settings must be correctly set in the {{kib}} configuration: + +```yaml +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: kibana-sample +spec: + config: + xpack.fleet.agents.elasticsearch.hosts: ["https://elasticsearch-sample-es-http.default.svc:9200"] + xpack.fleet.agents.fleet_server.hosts: ["https://fleet-server-sample-agent-http.default.svc:8220"] + xpack.fleet.packages: + - name: system + version: latest + - name: elastic_agent + version: latest + - name: fleet_server + version: latest + xpack.fleet.agentPolicies: + - name: Fleet Server on ECK policy + id: eck-fleet-server + namespace: default + is_managed: true + monitoring_enabled: + - logs + - metrics + unenroll_timeout: 900 + package_policies: + - name: fleet_server-1 + id: fleet_server-1 + package: + name: fleet_server + - name: Elastic Agent on ECK policy + id: eck-agent + namespace: default + is_managed: true + monitoring_enabled: + - logs + - metrics + unenroll_timeout: 900 + is_default: true + package_policies: + - name: system-1 + id: system-1 + package: + name: system +``` + +* `xpack.fleet.agents.elasticsearch.hosts` must point to the {{es}} cluster where {{agents}} should send data. For ECK-managed {{es}} clusters ECK creates a Service accessible through `https://ES_RESOURCE_NAME-es-http.ES_RESOURCE_NAMESPACE.svc:9200` URL, where `ES_RESOURCE_NAME` is the name of {{es}} resource and `ES_RESOURCE_NAMESPACE` is the namespace it was deployed within. See [Storing local state in host path volume](configuration-examples-standalone.md#k8s_storing_local_state_in_host_path_volume) for details on adjusting this field when running agent as non-root as it becomes required. +* `xpack.fleet.agents.fleet_server.hosts` must point to {{fleet-server}} that {{agents}} should connect to. For ECK-managed {{fleet-server}} instances, ECK creates a Service accessible through `https://FS_RESOURCE_NAME-agent-http.FS_RESOURCE_NAMESPACE.svc:8220` URL, where `FS_RESOURCE_NAME` is the name of {{agent}} resource with {{fleet-server}} enabled and `FS_RESOURCE_NAMESPACE` is the namespace it was deployed in. +* `xpack.fleet.packages` are required packages to enable {{fleet-server}} and {{agents}} to enroll. +* `xpack.fleet.agentPolicies` policies are needed for {{fleet-server}} and {{agents}} to enroll to, check {{fleet-guide}}/agent-policy.html for more information. + + +## Set referenced resources [k8s-elastic-agent-fleet-configuration-setting-referenced-resources] + +Both {{fleet-server}} and {{agent}} in {{fleet}} mode can be automatically set up with {{fleet}} by ECK. The ECK operator can set up {{fleet}} in {{kib}} (which otherwise requires manual steps) and enroll {{fleet-server}} in the default {{fleet-server}} policy. {{agent}} can be automatically enrolled in the default {{agent}} policy. To allow ECK to set this up, provide a reference to a ECK-managed {{kib}} through the `kibanaRef` configuration element. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server-sample +spec: + kibanaRef: + name: kibana +``` + +ECK can also facilitate the connection between {{agents}} and a ECK-managed {{fleet-server}}. To allow ECK to set this up, provide a reference to {{fleet-server}} through the `fleetServerRef` configuration element. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent-sample +spec: + fleetServerRef: + name: fleet-server-sample +``` + +Set the `elasticsearchRefs` element in your {{fleet-server}} to point to the {{es}} cluster that will manage {{fleet}}. Leave `elasticsearchRefs` empty or unset it for any {{agent}} running in {{fleet}} mode as the {{es}} cluster to target will come from {{kib}}'s `xpack.fleet.agents.elasticsearch.hosts` configuration element. + +::::{note} +Currently, {{agent}} in {{fleet}} mode supports only a single output, so only a single {{es}} cluster can be referenced. +:::: + + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server-sample +spec: + elasticsearchRefs: + - name: elasticsearch-sample +``` + +By default, every reference targets all instances in your {{es}}, {{kib}} and {{fleet-server}} deployments, respectively. If you want to direct traffic to specific instances, refer to [*Traffic Splitting*](requests-routing-to-elasticsearch-nodes.md) for more information and examples. + + +## Customize {{agent}} configuration [k8s-elastic-agent-fleet-configuration-custom-configuration] + +In contrast to {{agents}} in standalone mode, the configuration is managed through {{fleet}}, and it cannot be defined through `config` or `configRef` elements. + + +## Upgrade the {{agent}} specification [k8s-elastic-agent-fleet-configuration-upgrade-specification] + +You can upgrade the {{agent}} version or change settings by editing the YAML specification file. ECK applies the changes by performing a rolling restart of the Agent’s Pods. Depending on the settings that you used, ECK will set up {{fleet}} in {{kib}}, enrolls the agent in {{fleet}}, or restarts {{agent}} on certificate rollover. + + +## Choose the deployment model [k8s-elastic-agent-fleet-configuration-chose-the-deployment-model] + +Depending on the use case, {{agent}} may need to be deployed as a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), or a [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulSet/). To choose how to deploy your {{agents}}, provide a `podTemplate` element under the `deployment` or the `daemonSet` element in the specification. If you choose the `deployment` option, you can additionally specify the [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) used to replace old Pods with new ones. + +Similarly, you can set the [update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/) when deploying as a DaemonSet. This allows you to control the rollout speed for new configuration by modifying the `maxUnavailable` setting: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent-sample +spec: + version: 8.16.1 + daemonSet: + strategy: + type: RollingUpdate + rollingUpdate: + maxUnavailable: 3 +... +``` + +Refer to [Set compute resources for Beats and Elastic Agent](manage-compute-resources.md#k8s-compute-resources-beats-agent) for more information on how to use the Pod template to adjust the resources given to {{agent}}. + + +## Role Based Access Control for {{agent}} [k8s-elastic-agent-fleet-configuration-role-based-access-control] + +Some {{agent}} features, such as the [{{k8s}} integration](https://epr.elastic.co/package/kubernetes/0.2.8/), require that Agent Pods interact with {{k8s}} APIs. This functionality requires specific permissions. Standard {{k8s}} [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) rules apply. For example, to allow API interactions: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent-sample +spec: + version: 8.16.1 + elasticsearchRefs: + - name: elasticsearch-sample + daemonSet: + podTemplate: + spec: + automountServiceAccountToken: true + serviceAccountName: elastic-agent +... + +apiVersion: v1 +kind: ServiceAccount +metadata: + name: elastic-agent + namespace: default +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: elastic-agent +subjects: +- kind: ServiceAccount + name: elastic-agent + namespace: default +roleRef: + kind: ClusterRole + name: elastic-agent + apiGroup: rbac.authorization.k8s.io +``` + + +## Deploy {{agent}} in secured clusters [k8s-elastic-agent-fleet-configuration-deploying-in-secured-clusters] + +To deploy {{agent}} in clusters with the Pod Security Policy admission controller enabled, or in [OpenShift](k8s-openshift-agent.md) clusters, you might need to grant additional permissions to the Service Account used by the {{agent}} Pods. Those Service Accounts must be bound to a Role or ClusterRole that has `use` permission for the required Pod Security Policy or Security Context Constraints. Different {{agent}} {integrations} might require different settings set in their PSP/[SCC](k8s-openshift-agent.md). + + +## Customize {{fleet-server}} Service [k8s-elastic-agent-fleet-configuration-customize-fleet-server-service] + +By default, ECK creates a Service for {{fleet-server}} that {{agents}} can connect through. You can customize it using the `http` configuration element. Check more information on how to [make changes](accessing-services.md) to the Service and [customize](tls-certificates.md) the TLS configuration. + + +## Control {{fleet}} policy selection [k8s-elastic-agent-control-fleet-policy-selection] + +ECK uses the default policy to enroll {{agents}} in {{fleet}} and the default {{fleet-server}} policy to enroll {{fleet-server}}. A different policy can be chosen by using the `policyID` attribute in the {{agent}} resource: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server-sample +spec: + policyID: my-custom-policy +... +``` + +Please note that the environment variables related to policy selection mentioned in the {{agent}} [docs](https://www.elastic.co/guide/en/fleet/current/agent-environment-variables.html) like `FLEET_SERVER_POLICY_ID` will be managed by the ECK operator. + + +## Running as a non-root user [k8s-elastic-agent-running-as-a-non-root-user] + +In order to run {{agent}} as a non-root user you must choose how you want to persist data to the Agent’s volume. + +1. Run {{agent}} with an `emptyDir` volume. This has the downside of not persisting data between restarts of the {{agent}} which can duplicate work done by the previous running Agent. +2. Run {{agent}} with a `hostPath` volume in addition to a `DaemonSet` running as `root` that sets up permissions for the `agent` user. + +In addition to these decisions, if you are running {{agent}} in {{fleet}} mode as a non-root user, you must configure `certificate_authorities.ssl` in each `xpack.fleet.outputs` to trust the CA of the {{es}} Cluster. + +To run {{agent}} with an `emptyDir` volume. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server +spec: + deployment: + podTemplate: + spec: + securityContext: <1> + fsGroup: 1000 + volumes: + - name: agent-data + emptyDir: {} +... +``` + +1. Gid 1000 is the default group at which the Agent container runs. Adjust as necessary if `runAsGroup` has been modified. + + +To run {{agent}} with a `hostPath` volume and a `DaemonSet` to maintain permissions. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server-sample + namespace: elastic-apps +spec: + mode: fleet + fleetServerEnabled: true + deployment: {} +... +--- +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent-sample + namespace: elastic-apps +spec: + daemonSet: {} +... +--- +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: manage-agent-hostpath-permissions + namespace: elastic-apps +spec: + selector: + matchLabels: + name: manage-agent-hostpath-permissions + template: + metadata: + labels: + name: manage-agent-hostpath-permissions + spec: + # serviceAccountName: elastic-agent <1> + volumes: + - hostPath: + path: /var/lib/elastic-agent + type: DirectoryOrCreate + name: "agent-data" + initContainers: + - name: manage-agent-hostpath-permissions + # image: registry.access.redhat.com/ubi9/ubi-minimal:latest <2> + image: docker.io/bash:5.2.15 + resources: + limits: + cpu: 100m + memory: 32Mi + securityContext: + # privileged: true <3> + runAsUser: 0 + volumeMounts: + - mountPath: /var/lib/elastic-agent + name: agent-data + command: + - 'bash' + - '-e' + - '-c' + - |- + # Adjust this with /var/lib/elastic-agent/YOUR-NAMESPACE/YOUR-AGENT-NAME/state + # Multiple directories are supported for the fleet-server + agent use case. + dirs=( + "/var/lib/elastic-agent/default/elastic-agent/state" + "/var/lib/elastic-agent/default/fleet-server/state" + ) + for dir in ${dirs[@]}; do + mkdir -p "${dir}" + # chcon is only required when running an an SELinux-enabled/OpenShift environment. + # chcon -Rt svirt_sandbox_file_t "${dir}" + chmod g+rw "${dir}" + # Gid 1000 is the default group at which the Agent container runs. Adjust as necessary if `runAsGroup` has been modified. + chgrp 1000 "${dir}" + if [ -n "$(ls -A ${dir} 2>/dev/null)" ] + then + # Gid 1000 is the default group at which the Agent container runs. Adjust as necessary if `runAsGroup` has been modified. + chgrp 1000 "${dir}"/* + chmod g+rw "${dir}"/* + fi + done + containers: + - name: sleep + image: gcr.io/google-containers/pause-amd64:3.2 +``` + +1. This is only required when running in an SElinux-enabled/OpenShift environment. Ensure this user has been added to the privileged security context constraints (SCC) in the correct namespace. `oc adm policy add-scc-to-user privileged -z elastic-agent -n elastic-apps` +2. UBI is only required when needing the `chcon` binary when running in an SELinux-enabled/OpenShift environment. If that is not required then the following smaller image can be used instead: `docker.io/bash:5.2.15` +3. Privileged is only required when running in an SElinux-enabled/OpenShift environment. + + +When running Agent in fleet mode as a non-root user {{kib}} must be configured in order to properly accept the CA of the {{es}} cluster. + +```yaml +--- +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: kibana-sample +spec: + config: + # xpack.fleet.agents.elasticsearch.hosts: <1> + xpack.fleet.agents.fleet_server.hosts: ["https://fleet-server-sample-agent-http.default.svc:8220"] + xpack.fleet.outputs: + - id: eck-fleet-agent-output-elasticsearch + is_default: true + name: eck-elasticsearch + type: elasticsearch + hosts: + - "https://elasticsearch-sample-es-http.default.svc:9200" <2> + ssl: + certificate_authorities: ["/mnt/elastic-internal/elasticsearch-association/default/elasticsearch-sample/certs/ca.crt"] <3> +``` + +1. This entry must not exist when running agent in fleet mode as a non-root user. +2. Note that the correct URL for {{es}} is `https://ELASTICSEARCH_NAME-es-http.YOUR-NAMESPACE.svc:9200` +3. Note that the correct path for {{es}} `certificate_authorities` is `/mnt/elastic-internal/elasticsearch-association/YOUR-NAMESPACE/ELASTICSEARCH-NAME/certs/ca.crt` + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-logstash.md b/deploy-manage/deploy/cloud-on-k8s/configuration-logstash.md new file mode 100644 index 000000000..87d1c9f18 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-logstash.md @@ -0,0 +1,586 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-logstash-configuration.html +--- + +# Configuration [k8s-logstash-configuration] + +## Upgrade the Logstash specification [k8s-logstash-upgrade-specification] + +You can upgrade the Logstash version or change settings by editing the YAML specification. ECK applies the changes by performing a rolling restart of Logstash Pods. + + +## Logstash configuration [k8s-logstash-configuring-logstash] + +Define the Logstash configuration (the ECK equivalent to `logstash.yml`) in the `spec.config` section: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - name: quickstart + clusterName: qs + config: <1> + pipeline.workers: 4 + log.level: debug +``` + +1. Customize Logstash configuration using `logstash.yml` settings here + + +Alternatively, you can provide the configuration through a Secret specified in the `spec.configRef` section. The Secret must have a `logstash.yml` entry with your settings: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - name: quickstart + clusterName: qs + configRef: + secretName: quickstart-config +--- +apiVersion: v1 +kind: Secret +metadata: + name: quickstart-config +stringData: + logstash.yml: |- + pipeline.workers: 4 + log.level: debug +``` + + +## Configuring Logstash pipelines [k8s-logstash-pipelines] + +Define Logstash pipelines in the `spec.pipelines` section (the ECK equivalent to `pipelines.yml`): + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - clusterName: qs + name: quickstart + pipelines: + - pipeline.id: main + config.string: | + input { + beats { + port => 5044 + } + } + output { + elasticsearch { + hosts => [ "${QS_ES_HOSTS}" ] + user => "${QS_ES_USER}" + password => "${QS_ES_PASSWORD}" + ssl_certificate_authorities => "${QS_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } +``` + +Alternatively, you can provide the pipelines configuration through a Secret specified in the `spec.pipelinesRef` field. The Secret must have a `pipelines.yml` entry with your configuration: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - clusterName: qs + name: quickstart + pipelinesRef: + secretName: quickstart-pipeline +--- +apiVersion: v1 +kind: Secret +metadata: + name: quickstart-pipeline +stringData: + pipelines.yml: |- + - pipeline.id: main + config.string: | + input { + beats { + port => 5044 + } + } + output { + elasticsearch { + hosts => [ "${QS_ES_HOSTS}" ] + user => "${QS_ES_USER}" + password => "${QS_ES_PASSWORD}" + ssl_certificate_authorities => "${QS_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } +``` + +Logstash on ECK supports all options present in `pipelines.yml`, including settings to update the number of workers, and the size of the batch that the pipeline will process. This also includes using `path.config` to point to volumes mounted on the Logstash container: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - clusterName: qs + name: quickstart + pipelines: + - pipeline.id: main + config.string: | + input { + beats { + port => 5044 + } + } + output { + elasticsearch { + hosts => [ "${QS_ES_HOSTS}" ] + user => "${QS_ES_USER}" + password => "${QS_ES_PASSWORD}" + ssl_certificate_authorities => "${QS_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } +``` + +::::{note} +Logstash persistent queues (PQs) and dead letter queues (DLQs) are not currently managed by the Logstash operator, and using them will require you to create and manage your own Volumes and VolumeMounts +:::: + + + +## Defining data volumes for Logstash [k8s-logstash-volumes] + +[2.9.0] + +::::{warning} +Volume support for Logstash is a breaking change to earlier versions of ECK and requires you to recreate your Logstash resources. +:::: + + + +## Specifying the volume claim settings [k8s-volume-claim-settings] + +A PersistentVolume called `logstash-data` is created by default. It maps to `/usr/share/logstash/data` for persistent storage, which is typically used for storage from plugins. + +By default, the `logstash-data` volume claim is a `1.5Gi` volume, using the standard StorageClass of your Kubernetes cluster. You can override the default by adding a `spec.volumeClaimTemplate` section named `logstash-data`. + +For production workloads, you should define your own volume claim template with the desired storage capacity and (optionally) the Kubernetes [storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) to associate with the persistent volume. To override this volume claim for `data` usages, the name of this volume claim must be `logstash-data`. + +This example updates the default data template to increase the storage to `2Gi` for the {{ls}} data folder: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash +spec: + # some configuration attributes omitted for brevity here + volumeClaimTemplates: + - metadata: + name: logstash-data # Do not change this name unless you set up a volume mount for the data path. + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi +``` + +The default volume size will likely be insufficient for production workloads, especially when you are using: + +* the persistent queue (PQ) feature +* dead letter queues (DLQ), or +* {{ls}} plugins that make heavy use of temporary storage. + +Increase the storage capacity, or consider creating separate volumes for these use cases. + +You can add separate storage by including an additional `spec.volumeClaimTemplate` along with a corresponding `spec.podTemplate.spec.containers.volumeMount` for each requested volume. + +This example shows how to setup separate storage for a PQ: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash +spec: + # some configuration attributes omitted for brevity here + volumeClaimTemplates: + - metadata: + name: pq <1> + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + podTemplate: + spec: + containers: + - name: logstash + volumeMounts: + - mountPath: /usr/share/logstash/pq <2> + name: pq <1> + readOnly: false + config: + log.level: info + queue.type: persisted + path.queue: /usr/share/logstash/pq <2> +``` + +1. The `name` values in the `volumeMount` for the container in the `podTemplate` section and the name of the `volumeClaimTemplate` must match. +2. Set the `path.queue` setting in the configuration to match the `mountPath` in the `volumeMount`. + + +This example shows how to configure {{ls}} with a Dead Letter Queue setup on the main pipeline, and a separate pipeline to read items from the DLQ. + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash +spec: + # some configuration attributes omitted for brevity here + podTemplate: + spec: + containers: + - name: logstash + volumeMounts: + - mountPath: /usr/share/logstash/dlq <2> + name: dlq <1> + readOnly: false + volumeClaimTemplates: + - metadata: + name: dlq <1> + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + pipelines: + - pipeline.id: beats + dead_letter_queue.enable: true + path.dead_letter_queue: /usr/share/logstash/dlq <2> + config.string: | + input { + beats { + port => 5044 + } + } + output { + elasticsearch { + hosts => [ "${ECK_ES_HOSTS}" ] + user => "${ECK_ES_USER}" + password => "${ECK_ES_PASSWORD}" + ssl_certificate_authorities => "${ECK_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } + - pipeline.id: dlq_read + dead_letter_queue.enable: false + config.string: | + input { + dead_letter_queue { + path => "/usr/share/logstash/dlq" <2> + commit_offsets => true + pipeline_id => "beats" + clean_consumed => true + } + } + filter { + mutate { + remove_field => "[geoip][location]" + } + } + output { + elasticsearch { + hosts => [ "${ECK_ES_HOSTS}" ] + user => "${ECK_ES_USER}" + password => "${ECK_ES_PASSWORD}" + ssl_certificate_authorities => "${ECK_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } +``` + +1. The `name` values in the `volumeMount` for the container in the `podTemplate` section and the name of the `volumeClaimTemplate` must match. +2. Set the `path.dead_letter_queue` setting in the pipeline config to match the `mountPath` in the `volumeMount` for pipelines that are writing to the Dead Letter Queue, and set the `path` setting of the `dead_letter_queue` plugin for the pipeline that will read from the Dead Letter Queue. + + + +## Updating the volume claim settings [k8s-volume-claim-settings-updates] + +If the storage class allows [volume expansion](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/), you can increase the storage requests size in `spec.volumeClaimTemplates`. ECK updates the existing PersistentVolumeClaims accordingly, and recreates the StatefulSet automatically. + +If the volume driver supports `ExpandInUsePersistentVolumes`, the filesystem is resized online. In this case, you do not need to restart the {{ls}} process or re-create the Pods. + +If the volume driver does not support `ExpandInUsePersistentVolumes`, you must manually delete Pods after the resize so that they can be recreated automatically with the expanded filesystem. + +Any other changes in the volumeClaimTemplates—​such as changing the storage class or decreasing the volume size—​are not allowed. To make changes such as these, you must fully delete the {{ls}} resource, delete and recreate or resize the volume, and create a new {{ls}} resource. + +Before you delete a persistent queue (PQ) volume, ensure that the queue is empty. We recommend setting `queue.drain: true` on the {{ls}} Pods to ensure that the queue is drained when Pods are shutdown. Note that you should also increase the `terminationGracePeriodSeconds` to a large enough value to allow the queue to drain. + +This example shows how to configure a {{ls}} resource to drain the queue and increase the termination grace period. + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash +spec: + # some configuration attributes omitted for brevity here + config: + queue.drain: true + podTemplate: + spec: + terminationGracePeriodSeconds: 604800 +``` + +::::{note} +A [{{k8s}} known issue](https://github.com/kubernetes/kubernetes/issues/94435): {{k8s}} may not honor `terminationGracePeriodSeconds` settings greater than 600. A queue of a terminated Pod may not be fully drained, even when `queue.drain: true` is set and a high `terminationGracePeriodSeconds` is configured. +:::: + + +::::{note} +In this technical preview, there is currently no way to drain a dead letter queue (DLQ) automatically before {{ls}} shuts down. To manually drain the queue, first stop sending data to it, by either disabling the DLQ feature, or disabling any pipelines that send to a DLQ. Then wait for events to stop flowing through any pipelines reading from the input. +:::: + + + +## EmptyDir [k8s-emptydir] + +If you are not concerned about data loss, you can use an `emptyDir` volume for Logstash data. + +::::{warning} +The use of `emptyDir` in a production environment may cause permanent data loss. Do not use with persistent queues (PQs), dead letter queues (DLQs), or with any plugin that requires persistent storage to keep track of state between restarts of {{ls}}. + +Plugins that require persistent storage include any plugin that stores state locally. These plugins typically have a configuration parameter that includes the name `path` or `directory`, not including paths to static content, such as certificates or keystores. Examples include the `sincedb_path` setting for the `file`, `dead_letter_queue` and `s3` inputs, the `last_run_metadata_path` for the `JDBC` input, `aggregate_maps_path` for the `aggregate` filter, and `temporary_directory` for the `s3` output, used to aggregate content before uploading to s3. + +:::: + + +```yaml +spec: + count: 5 + podTemplate: + spec: + volumes: + - name: logstash-data + emptyDir: {} +``` + + +## Using Elasticsearch in Logstash pipelines [k8s-logstash-pipelines-es] + +### `elasticsearchRefs` for establishing a secured connection [k8s-logstash-esref] + +The `spec.elasticsearchRefs` section provides a mechanism to help configure Logstash to establish a secured connection to one or more ECK managed Elasticsearch clusters. By default, each `elasticsearchRef` will target all nodes in its referenced Elasticsearch cluster. If you want to direct traffic to specific nodes of your Elasticsearch cluster, refer to [*Traffic Splitting*](requests-routing-to-elasticsearch-nodes.md) for more information and examples. + +When you use `elasticsearchRefs` in a Logstash pipeline, the Logstash operator creates the necessary resources from the associated Elasticsearch cluster, and provides environment variables to allow these resources to be accessed from the pipeline configuration. Environment variables are replaced at runtime with the appropriate values. The environment variables have a fixed naming convention: + +* `NORMALIZED_CLUSTERNAME_ES_HOSTS` +* `NORMALIZED_CLUSTERNAME_ES_USER` +* `NORMALIZED_CLUSTERNAME_ES_PASSWORD` +* `NORMALIZED_CLUSTERNAME_ES_SSL_CERTIFICATE_AUTHORITY` + +where NORMALIZED_CLUSTERNAME is the value taken from the `clusterName` field of the `elasticsearchRef` property, capitalized, with `-` transformed to `_`. That is, `prod-es` would become `PROD_ES`. + +::::{note} +* The `clusterName` value should be unique across all referenced {{es}} instances in the same {{ls}} spec. +* The {{ls}} ECK operator creates a user called `eck_logstash_user_role` when an `elasticsearchRef` is specified. This user has the following permissions: + + ``` + "cluster": ["monitor", "manage_ilm", "read_ilm", "manage_logstash_pipelines", "manage_index_templates", "cluster:admin/ingest/pipeline/get",] + "indices": [ + { + "names": [ "logstash", "logstash-*", "ecs-logstash", "ecs-logstash-*", "logs-*", "metrics-*", "synthetics-*", "traces-*" ], + "privileges": ["manage", "write", "create_index", "read", "view_index_metadata"] + } + ] + ``` + + You can [update user permissions](../../users-roles/cluster-or-deployment-auth/native.md) to include more indices if the Elasticsearch plugin is expected to use indices other than the default. Check out [Logstash configuration with a custom index](configuration-examples-logstash.md#k8s-logstash-configuration-custom-index) sample configuration that creates a user that writes to a custom index. + + +:::: + + +This example demonstrates how to create a Logstash deployment that connects to different Elasticsearch instances, one of which is in a separate namespace: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: <1> + - clusterName: prod-es <2> + name: prod + - clusterName: qa-es <3> + name: qa + namespace: qa + pipelines: + - pipeline.id: main + config.string: | + input { + beats { + port => 5044 + } + } + output { + elasticsearch { <4> + hosts => [ "${PROD_ES_ES_HOSTS}" ] + user => "${PROD_ES_ES_USER}" + password => "${PROD_ES_ES_PASSWORD}" + ssl_certificate_authorities => "${PROD_ES_ES_SSL_CERTIFICATE_AUTHORITY}" + } + elasticsearch { <4> + hosts => [ "${QA_ES_ES_HOSTS}" ] + user => "${QA_ES_ES_USER}" + password => "${QA_ES_ES_PASSWORD}" + ssl_certificate_authorities => "${QA_ES_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } +``` + +1. Define Elasticsearch references in the CRD. This will create the appropriate Secrets to store certificate details and the rest of the connection information, and create environment variables to allow them to be referred to in Logstash pipeline configurations. +2. This refers to an Elasticsearch cluster residing in the same namespace as the Logstash instances. +3. This refers to an Elasticsearch cluster residing in a different namespace to the Logstash instances. +4. Elasticsearch output definitions - use the environment variables created by the Logstash operator when specifying an `ElasticsearchRef`. Note the use of "normalized" versions of the `clusterName` in the environment variables used to populate the relevant fields. + + + +### Connect to an external Elasticsearch cluster [k8s-logstash-external-es] + +Logstash can connect to external Elasticsearch cluster that is not managed by ECK. You can reference a Secret instead of an Elasticsearch cluster in the `elasticsearchRefs` section through the `secretName` attribute: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: external-es-ref +stringData: + url: https://abcd-42.xyz.elastic-cloud.com:443 <1> + username: logstash_user <2> + password: REDACTED <3> + ca.crt: REDACTED <4> +--- +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - clusterName: prod-es + secretName: external-es-ref <5> + monitoring: + metrics: + elasticsearchRefs: + - secretName: external-es-ref <5> + logs: + elasticsearchRefs: + - secretName: external-es-ref <5> +``` + +1. The URL to reach the {{es}} cluster. +2. The username of the user to be authenticated to the {{es}} cluster. +3. The password of the user to be authenticated to the {{es}} cluster. +4. The CA certificate in PEM format to secure communication to the {{es}} cluster (optional). +5. The `secretName` and `name` attributes are mutually exclusive, you have to choose one or the other. + + +::::{tip} +Always specify the port in the URL when {{ls}} is connecting to an external {{es}} cluster. +:::: + + + + +## Expose services [k8s-logstash-expose-services] + +By default, the {{ls}} operator creates a headless Service for the metrics endpoint to enable metric collection by the Metricbeat sidecar for Stack Monitoring: + +```sh +kubectl get service quickstart-ls-api +``` + +```sh +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +quickstart-ls-api ClusterIP None 9600/TCP 48s +``` + +Additional services can be added in the `spec.services` section of the resource: + +```yaml +services: + - name: beats + service: + spec: + ports: + - port: 5044 + name: "winlogbeat" + protocol: TCP + - port: 5045 + name: "filebeat" + protocol: TCP +``` + + +## Pod configuration [k8s-logstash-pod-configuration] + +You can [customize the {{ls}} Pod](customize-pods.md) using a Pod template, defined in the `spec.podTemplate` section of the configuration. + +This example demonstrates how to create a {{ls}} deployment with increased heap size and resource limits. + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash-sample +spec: + version: 8.16.1 + count: 1 + elasticsearchRefs: + - name: "elasticsearch-sample" + clusterName: "sample" + podTemplate: + spec: + containers: + - name: logtash + env: + - name: LS_JAVA_OPTS + value: "-Xmx2g -Xms2g" + resources: + requests: + memory: 1Gi + cpu: 0.5 + limits: + memory: 4Gi + cpu: 2 +``` + +The name of the container in the Pod template must be `logstash`. diff --git a/deploy-manage/deploy/cloud-on-k8s/configuration-standalone.md b/deploy-manage/deploy/cloud-on-k8s/configuration-standalone.md new file mode 100644 index 000000000..0c2516d2c --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configuration-standalone.md @@ -0,0 +1,413 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent-configuration.html +--- + +# Configuration [k8s-elastic-agent-configuration] + +## Upgrade the Elastic Agent specification [k8s-elastic-agent-upgrade-specification] + +You can upgrade the Elastic Agent version or change settings by editing the YAML specification. ECK applies the changes by performing a rolling restart of the Agent’s Pods. Depending on the settings that you used, ECK will set the [outputs](#k8s-elastic-agent-set-output) part of the configuration, or restart Elastic Agent on certificate rollover. + + +## Customize the Elastic Agent configuration [k8s-elastic-agent-custom-configuration] + +The Elastic Agent configuration is defined in the `config` element: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: quickstart +spec: + version: 8.16.1 + elasticsearchRefs: + - name: quickstart + daemonSet: + podTemplate: + spec: + securityContext: + runAsUser: 0 <1> + config: + inputs: + - name: system-1 + revision: 1 + type: system/metrics + use_output: default + meta: + package: + name: system + version: 0.9.1 + data_stream: + namespace: default + streams: + - id: system/metrics-system.cpu + data_stream: + dataset: system.cpu + type: metrics + metricsets: + - cpu + cpu.metrics: + - percentages + - normalized_percentages + period: 10s +``` + +1. The root user is required to persist state in a `hostPath` volume. See [Storing local state in host path volume](configuration-examples-standalone.md#k8s_storing_local_state_in_host_path_volume) for options to not run the Agent container as root. + + +Alternatively, it can be provided through a Secret specified in the `configRef` element. The Secret must have an `agent.yml` entry with this configuration: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: quickstart +spec: + version: 8.16.1 + elasticsearchRefs: + - name: quickstart + daemonSet: + podTemplate: + spec: + securityContext: + runAsUser: 0 + configRef: + secretName: system-cpu-config +--- +apiVersion: v1 +kind: Secret +metadata: + name: system-cpu-config +stringData: + agent.yml: |- + inputs: + - name: system-1 + revision: 1 + type: system/metrics + use_output: default + meta: + package: + name: system + version: 0.9.1 + data_stream: + namespace: default + streams: + - id: system/metrics-system.cpu + data_stream: + dataset: system.cpu + type: metrics + metricsets: + - cpu + cpu.metrics: + - percentages + - normalized_percentages + period: 10s +``` + +You can use the Fleet application in Kibana to generate the configuration for Elastic Agent, even when running in standalone mode. Check the [Elastic Agent standalone](https://www.elastic.co/guide/en/fleet/current/install-standalone-elastic-agent.html) documentation. Adding the corresponding integration package to Kibana also adds the related dashboards and visualizations. + + +## Use multiple Elastic Agent outputs [k8s-elastic-agent-multi-output] + +Elastic Agent supports the use of multiple outputs. Therefore, the `elasticsearchRefs` element accepts multiple references to Elasticsearch clusters. ECK populates the outputs section of the Elastic Agent configuration based on those references. If you configure more than one output, you also have to specify a unique `outputName` attribute. + +To send Elastic Agent’s internal monitoring and log data to a different Elasticsearch cluster called `agent-monitoring` in the `elastic-monitoring` namespace, and the harvested metrics to our `quickstart` cluster, you have to define two `elasticsearchRefs` as shown in the following example: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: quickstart +spec: + version: 8.16.1 + daemonSet: + podTemplate: + spec: + securityContext: + runAsUser: 0 + elasticsearchRefs: + - name: quickstart + outputName: default + - name: agent-monitoring + namespace: elastic-monitoring + outputName: monitoring + config: + agent: + monitoring: + enabled: true + use_output: monitoring + logs: true + metrics: true + inputs: + - name: system-1 + revision: 1 + type: system/metrics + use_output: default +... +``` + + +## Customize the connection to an Elasticsearch cluster [k8s-elastic-agent-connect-es] + +The `elasticsearchRefs` element allows ECK to automatically configure Elastic Agent to establish a secured connection to one or more managed Elasticsearch clusters. By default, it targets all nodes in your cluster. If you want to direct traffic to specific nodes of your Elasticsearch cluster, refer to [*Traffic Splitting*](requests-routing-to-elasticsearch-nodes.md) for more information and examples. + + +## Set manually Elastic Agent outputs [k8s-elastic-agent-set-output] + +If the `elasticsearchRefs` element is specified, ECK populates the outputs section of the Elastic Agent configuration. ECK creates a user with appropriate roles and permissions and uses its credentials. If required, it also mounts the CA certificate in all Agent Pods, and recreates Pods when this certificate changes. Moreover, `elasticsearchRef` element can refer to an ECK-managed Elasticsearch cluster by filling the `name`, `namespace`, `serviceName` fields accordingly, as well as to a Kubernetes secret that contains the connection information to an Elasticsearch cluster not managed by it. In the latter case, for authenticating against the Elasticsearch cluster the secret must contain the fields of `url` and either the `username` with `password` or the `api-key`. Refer to [*Connect to external Elastic resources*](connect-to-external-elastic-resources.md) for additional details. + +The outputs can also be set manually. To do that, remove the `elasticsearchRefs` element from the specification and include an appropriate output configuration in the `config`, or indirectly through the `configRef` mechanism. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: quickstart +spec: + version: 8.16.1 + daemonSet: + podTemplate: + spec: + securityContext: + runAsUser: 0 + config: + outputs: + default: + type: elasticsearch + hosts: + - "https://my-custom-elasticsearch-cluster.cloud.elastic.co:9243" + password: ES_PASSWORD + username: ES_USER +... +``` + + +## Choose the deployment model [k8s-elastic-agent-chose-the-deployment-model] + +Depending on the use case, Elastic Agent may need to be deployed as a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), or a [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulSet/). Provide a `podTemplate` element under either the `deployment` or the `daemonSet` element in the specification to choose how your Elastic Agents should be deployed. When choosing the `deployment` option you can additionally specify the [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) used to replace old Pods with new ones. + +Similarly, you can set the [update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/) when deploying as a DaemonSet. This allows you to control the rollout speed for new configuration by modifying the `maxUnavailable` setting: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: quickstart +spec: + version: 8.16.1 + daemonSet: + podTemplate: + spec: + securityContext: + runAsUser: 0 + strategy: + type: RollingUpdate + rollingUpdate: + maxUnavailable: 3 +... +``` + +Check [Set compute resources for Beats and Elastic Agent](manage-compute-resources.md#k8s-compute-resources-beats-agent) for more information on how to use the Pod template to adjust the resources given to Elastic Agent. + + +## Role Based Access Control for Elastic Agent [k8s-elastic-agent-role-based-access-control] + +Some Elastic Agent features, such as the [Kubernetes integration](https://epr.elastic.co/package/kubernetes/0.2.8/), require that Agent Pods interact with Kubernetes APIs. This functionality requires specific permissions. The standard Kubernetes [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) rules apply. For example, to allow API interactions: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent +spec: + version: 8.16.1 + elasticsearchRefs: + - name: elasticsearch + daemonSet: + podTemplate: + spec: + automountServiceAccountToken: true + serviceAccountName: elastic-agent + securityContext: + runAsUser: 0 +... + +apiVersion: v1 +kind: ServiceAccount +metadata: + name: elastic-agent + namespace: default +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: elastic-agent +subjects: +- kind: ServiceAccount + name: elastic-agent + namespace: default +roleRef: + kind: ClusterRole + name: elastic-agent + apiGroup: rbac.authorization.k8s.io +``` + + +## Deploying Elastic Agent in secured clusters [k8s-elastic-agent-deploying-in-secured-clusters] + +To deploy Elastic Agent in clusters with the Pod Security Policy admission controller enabled, or in [OpenShift](k8s-openshift-agent.md) clusters, you might need to grant additional permissions to the Service Account used by the Elastic Agent Pods. Those Service Accounts must be bound to a Role or ClusterRole that has `use` permission for the required Pod Security Policy or Security Context Constraints. Different Elastic Agent integrations might require different settings set in their PSP/[SCC](k8s-openshift-agent.md). + + +## Running as a non-root user [k8s_running_as_a_non_root_user] + +In order to run {{agent}} as a non-root user you must choose how you want to persist data to the Agent’s volume. + +1. Run {{agent}} with an `emptyDir` volume. This has the downside of not persisting data between restarts of the {{agent}} which can duplicate work done by the previous running Agent. +2. Run {{agent}} with a `hostPath` volume in addition to a `DaemonSet` running as `root` that sets up permissions for the `agent` user. + +In addition to these decisions, if you are running {{agent}} in {{fleet}} mode as a non-root user, you must configure `certificate_authorities.ssl` in each `xpack.fleet.outputs` to trust the CA of the {{es}} Cluster. + +To run {{agent}} with an `emptyDir` volume. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server +spec: + deployment: + podTemplate: + spec: + securityContext: <1> + fsGroup: 1000 + volumes: + - name: agent-data + emptyDir: {} +... +``` + +1. Gid 1000 is the default group at which the Agent container runs. Adjust as necessary if `runAsGroup` has been modified. + + +To run {{agent}} with a `hostPath` volume and a `DaemonSet` to maintain permissions. + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: fleet-server-sample + namespace: elastic-apps +spec: + mode: fleet + fleetServerEnabled: true + deployment: {} +... +--- +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent-sample + namespace: elastic-apps +spec: + daemonSet: {} +... +--- +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: manage-agent-hostpath-permissions + namespace: elastic-apps +spec: + selector: + matchLabels: + name: manage-agent-hostpath-permissions + template: + metadata: + labels: + name: manage-agent-hostpath-permissions + spec: + # serviceAccountName: elastic-agent <1> + volumes: + - hostPath: + path: /var/lib/elastic-agent + type: DirectoryOrCreate + name: "agent-data" + initContainers: + - name: manage-agent-hostpath-permissions + # image: registry.access.redhat.com/ubi9/ubi-minimal:latest <2> + image: docker.io/bash:5.2.15 + resources: + limits: + cpu: 100m + memory: 32Mi + securityContext: + # privileged: true <3> + runAsUser: 0 + volumeMounts: + - mountPath: /var/lib/elastic-agent + name: agent-data + command: + - 'bash' + - '-e' + - '-c' + - |- + # Adjust this with /var/lib/elastic-agent/YOUR-NAMESPACE/YOUR-AGENT-NAME/state + # Multiple directories are supported for the fleet-server + agent use case. + dirs=( + "/var/lib/elastic-agent/default/elastic-agent/state" + "/var/lib/elastic-agent/default/fleet-server/state" + ) + for dir in ${dirs[@]}; do + mkdir -p "${dir}" + # chcon is only required when running an an SELinux-enabled/OpenShift environment. + # chcon -Rt svirt_sandbox_file_t "${dir}" + chmod g+rw "${dir}" + # Gid 1000 is the default group at which the Agent container runs. Adjust as necessary if `runAsGroup` has been modified. + chgrp 1000 "${dir}" + if [ -n "$(ls -A ${dir} 2>/dev/null)" ] + then + # Gid 1000 is the default group at which the Agent container runs. Adjust as necessary if `runAsGroup` has been modified. + chgrp 1000 "${dir}"/* + chmod g+rw "${dir}"/* + fi + done + containers: + - name: sleep + image: gcr.io/google-containers/pause-amd64:3.2 +``` + +1. This is only required when running in an SElinux-enabled/OpenShift environment. Ensure this user has been added to the privileged security context constraints (SCC) in the correct namespace. `oc adm policy add-scc-to-user privileged -z elastic-agent -n elastic-apps` +2. UBI is only required when needing the `chcon` binary when running in an SELinux-enabled/OpenShift environment. If that is not required then the following smaller image can be used instead: `docker.io/bash:5.2.15` +3. Privileged is only required when running in an SElinux-enabled/OpenShift environment. + + +When running Agent in fleet mode as a non-root user {{kib}} must be configured in order to properly accept the CA of the {{es}} cluster. + +```yaml +--- +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: kibana-sample +spec: + config: + # xpack.fleet.agents.elasticsearch.hosts: <1> + xpack.fleet.agents.fleet_server.hosts: ["https://fleet-server-sample-agent-http.default.svc:8220"] + xpack.fleet.outputs: + - id: eck-fleet-agent-output-elasticsearch + is_default: true + name: eck-elasticsearch + type: elasticsearch + hosts: + - "https://elasticsearch-sample-es-http.default.svc:9200" <2> + ssl: + certificate_authorities: ["/mnt/elastic-internal/elasticsearch-association/default/elasticsearch-sample/certs/ca.crt"] <3> +``` + +1. This entry must not exist when running agent in fleet mode as a non-root user. +2. Note that the correct URL for {{es}} is `https://ELASTICSEARCH_NAME-es-http.YOUR-NAMESPACE.svc:9200` +3. Note that the correct path for {{es}} `certificate_authorities` is `/mnt/elastic-internal/elasticsearch-association/YOUR-NAMESPACE/ELASTICSEARCH-NAME/certs/ca.crt` + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/configure-deployments.md b/deploy-manage/deploy/cloud-on-k8s/configure-deployments.md new file mode 100644 index 000000000..7122ba6ad --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configure-deployments.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-orchestrating-elastic-stack-applications.html +--- + +# Configure deployments [k8s-orchestrating-elastic-stack-applications] + +* [*Run Elasticsearch on ECK*](elasticsearch-configuration.md) +* [*Run {{kib}} on ECK*](kibana-configuration.md) +* [*Run APM Server on ECK*](apm-server.md) +* [*Run standalone Elastic Agent on ECK*](standalone-elastic-agent.md) +* [*Run {{fleet}}-managed {{agent}} on ECK*](fleet-managed-elastic-agent.md) +* [*Run Elastic Maps Server on ECK*](elastic-maps-server.md) +* [*Run Enterprise Search on ECK*](enterprise-search.md) +* [*Run Beats on ECK*](beats.md) +* [*Run {{ls}} on ECK*](logstash.md) +* [*Elastic Stack Helm Chart*](managing-deployments-using-helm-chart.md) +* [*Recipes*](recipes.md) +* [*Secure the Elastic Stack*](../../security.md) +* [*Access Elastic Stack services*](accessing-services.md) +* [*Customize Pods*](customize-pods.md) +* [*Manage compute resources*](manage-compute-resources.md) +* [*Autoscaling stateless applications*](../../autoscaling/autoscaling-stateless-applications-on-eck.md) +* [*Elastic Stack configuration policies*](elastic-stack-configuration-policies.md) +* [*Upgrade the Elastic Stack version*](../../upgrade/deployment-or-cluster.md) +* [*Connect to external Elastic resources*](connect-to-external-elastic-resources.md) + diff --git a/deploy-manage/deploy/cloud-on-k8s/configure-eck.md b/deploy-manage/deploy/cloud-on-k8s/configure-eck.md new file mode 100644 index 000000000..18c796e46 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configure-eck.md @@ -0,0 +1,142 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-operator-config.html +--- + +# Configure ECK [k8s-operator-config] + +ECK can be configured using either command line flags or environment variables. + +| Flag | Default | Description | +| --- | --- | --- | +| `ca-cert-rotate-before` | `24h` | Duration representing how long before expiration CA certificates should be re-issued. | +| `ca-cert-validity` | `8760h` | Duration representing the validity period of a generated CA certificate. | +| `ca-dir` | `""` | Path to a directory containing a CA certificate (tls.crt) and its associated private key (tls.key) to be used for all managed resources. Effectively disables the CA rotation and validity options. | +| `cert-rotate-before` | `24h` | Duration representing how long before expiration TLS certificates should be re-issued. | +| `cert-validity` | `8760h` | Duration representing the validity period of a generated TLS certificate. | +| `config` | `""` | Path to a file containing the operator configuration. | +| `container-registry` | `docker.elastic.co` | Container registry to use for pulling Elastic Stack container images. | +| `container-repository` | `""` | Container repository to use for pulling Elastic Stack container images. | +| `container-suffix` | `""` | Suffix to be appended to container images by default. Cannot be combined with `--ubi-only` flag. | +| `disable-config-watch` | `false` | Watch the configuration file for changes and restart to apply them. Only effective when the `--config` flag is used to set the configuration file. | +| `disable-telemetry` | `false` | Disable periodically updating ECK telemetry data for Kibana to consume. | +| `elasticsearch-client-timeout` | `180s` | Default timeout for requests made by the Elasticsearch client. | +| `enable-leader-election` | `true` | Enable leader election. Must be set to true if using multiple replicas of the operator | +| `enable-tracing` | `false` | Enable APM tracing in the operator process. Use environment variables to configure APM server URL, credentials, and so on. Check [Apm Go Agent reference](https://www.elastic.co/guide/en/apm/agent/go/1.x/configuration.html) for details. | +| `enable-webhook` | `false` | Enables a validating webhook server in the operator process. | +| `enforce-rbac-on-refs` | `false` | Enables restrictions on cross-namespace resource association through RBAC. | +| `exposed-node-labels` | `""` | List of Kubernetes node labels which are allowed to be copied as annotations on the Elasticsearch Pods. Check [Topology spread constraints and availability zone awareness](advanced-elasticsearch-node-scheduling.md#k8s-availability-zone-awareness) for more details. | +| `ip-family` | `""` | Set the IP family to use. Possible values: IPv4, IPv6, "" (= auto-detect) | +| `kube-client-qps` | `0` | Set the maximum number of queries per second to the Kubernetes API. Default value is inherited from the [Go client](https://github.com/kubernetes/client-go/blob/e6538dd42b4fe55b6c754e41c66b43133ba41a59/rest/config.go#L44). | +| `kube-client-timeout` | `60s` | Set the request timeout for Kubernetes API calls made by the operator. | +| `log-verbosity` | `0` | Verbosity level of logs. `-2`=Error, `-1`=Warn, `0`=Info, `0` and above=Debug. | +| `manage-webhook-certs` | `true` | Enables automatic webhook certificate management. | +| `max-concurrent-reconciles` | `3` | Maximum number of concurrent reconciles per controller (Elasticsearch, Kibana, APM Server). Affects the ability of the operator to process changes concurrently. | +| `metrics-cert-dir` | `"{{TempDir}}/k8s-metrics-server/serving-certs"` | Location of TLS certs for the metrics server. Directory needs to contain tls.key and tls.crt. If empty self-signed certificates are used. Only effective when combined with metrics-port and metrics-secure. | +| `metrics-host` | `0.0.0.0` | The host to which the operator should bind to serve metrics in the Prometheus format. Will be combined with metrics-port. | +| `metrics-port` | `0` | Prometheus metrics port. Set to 0 to disable the metrics endpoint. | +| `metrics-secure` | `false` | Enables TLS for the metrics server. Only effective combined with metrics-port. | +| `namespaces` | `""` | Namespaces in which this operator should manage resources. Accepts multiple comma-separated values. Defaults to all namespaces if empty or unspecified. | +| `operator-namespace` | `""` | Namespace the operator runs in. Required. | +| `password-hash-cache-size` | `5 x max-concurrent-reconciles` | Sets the size of the password hash cache. Caching is disabled if explicitly set to 0 or any negative value. | +| `set-default-security-context` | `auto-detect` | Enables adding a default Pod Security Context to Elasticsearch Pods in Elasticsearch `8.0.0` and later. `fsGroup` is set to `1000` by default to match Elasticsearch container default UID. This behavior might not be appropriate for OpenShift and PSP-secured Kubernetes clusters, so it can be disabled. | +| `ubi-only` | `false` | Use only UBI container images to deploy Elastic Stack applications. UBI images are only available from 7.10.0 onward. Cannot be combined with `--container-suffix` flag. | +| `validate-storage-class` | `true` | Specifies whether the operator should retrieve storage classes to verify volume expansion support. Can be disabled if cluster-wide storage class RBAC access is not available. | +| `webhook-cert-dir` | `"{{TempDir}}/k8s-webhook-server/serving-certs"` | Path to the directory that contains the webhook server key and certificate. | +| `webhook-name` | `"elastic-webhook.k8s.elastic.co"` | Name of the Kubernetes ValidatingWebhookConfiguration resource. Only used when `enable-webhook` is true. | +| `webhook-secret` | `""` | K8s secret mounted into the path designated by webhook-cert-dir to be used for webhook certificates. | +| `webhook-port` | `9443` | Port to listen for incoming validation requests. | + +Unless noted otherwise, environment variables can be used instead of flags to configure the operator as well. Simply convert the flag name to upper case and replace any dashes (`-`) with underscores (`_`). For example, the `log-verbosity` flag can be set by an environment variable named `LOG_VERBOSITY`. + +Duration values should be specified as numeric values suffixed by the time unit. For example, a duration of 10 hours should be specified as `10h`. Acceptable time unit suffixes are: + +| Suffix | Unit | +| --- | --- | +| `ms` | Milliseconds | +| `s` | Seconds | +| `m` | Minutes | +| `h` | Hours | + +If you have a large number of configuration options to specify, use the `--config` flag to point to a file containing those options. For example, assume you have a file named `eck-config.yaml` with the following content: + +```yaml +log-verbosity: 2 +metrics-port: 6060 +namespaces: [ns1, ns2, ns3] +``` + +The operator can be started using any of the following methods to achieve the same end result: + +```sh +./elastic-operator manager --config=eck-config.yaml +``` + +```sh +./elastic-operator manager --log-verbosity=2 --metrics-port=6060 --namespaces=ns1,ns2,ns3 +``` + +```sh +LOG_VERBOSITY=2 METRICS_PORT=6060 NAMESPACES="ns1,ns2,ns3" ./elastic-operator manager +``` + +If you use a combination of all or some of the these methods, the descending order of precedence in case of a conflict is as follows: + +* Flag +* Environment variable +* File + +You can edit the `elastic-operator` ConfigMap to change the operator configuration. Unless the `--disable-config-watch` flag is set, the operator should restart automatically to apply the new changes. Alternatively, you can edit the `elastic-operator` StatefulSet and add flags to the `args` section — which will trigger an automatic restart of the operator pod by the StatefulSet controller. + + +## Configure ECK under Operator Lifecycle Manager [k8s-operator-config-olm] + +If you use [Operator Lifecycle Manager (OLM)](https://github.com/operator-framework/operator-lifecycle-manager) to install and run ECK, follow these steps to configure the operator: + +* Create a new ConfigMap in the same namespace as the operator. It should contain a key named `eck.yaml` pointing to the desired configuration values. + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: elastic-operator + namespace: openshift-operators + data: + eck.yaml: |- + log-verbosity: 0 + metrics-port: 6060 + container-registry: docker.elastic.co + max-concurrent-reconciles: 3 + ca-cert-validity: 8760h + ca-cert-rotate-before: 24h + cert-validity: 8760h + cert-rotate-before: 24h + ``` + +* Update your [Subscription](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md) to mount the ConfigMap under `/conf`. + + ```yaml + apiVersion: operators.coreos.com/v1alpha1 + kind: Subscription + metadata: + name: elastic-cloud-eck + namespace: openshift-operators + spec: + channel: stable + installPlanApproval: Automatic + name: elastic-cloud-eck + source: elastic-operators + sourceNamespace: openshift-marketplace + startingCSV: elastic-cloud-eck.v2.16.1 + config: + volumes: + - name: config + configMap: + name: elastic-operator + volumeMounts: + - name: config + mountPath: /conf + readOnly: true + ``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/configure-validating-webhook.md b/deploy-manage/deploy/cloud-on-k8s/configure-validating-webhook.md new file mode 100644 index 000000000..4389a45d6 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configure-validating-webhook.md @@ -0,0 +1,234 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-webhook.html +--- + +# Configure the validating webhook [k8s-webhook] + +ECK can be configured to provide a [validating webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) that validates Elastic custom resources (Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash) before they are created or updated. Validating webhooks provide immediate feedback if a submitted manifest contains invalid or illegal configuration — which can help you catch errors early and save time that would otherwise be spent on troubleshooting. + +Validating webhooks are defined using a `ValidatingWebhookConfiguration` object that defines the following: + +* Type of resource to validate (Elasticsearch, Kibana and so on) +* Type of actions to validate (create, update, delete) +* Connection details to the webhook + + * Kubernetes service name and namespace + * Request path + * CA certificate for verifying the server + +* Failure policy if the webhook is unavailable (block the operation or continue without validation) + + +## Defaults provided by ECK [k8s-webhook-defaults] + +When using the default `operator.yaml` manifest, ECK is installed with a `ValidatingWebhookConfiguration` configured as follows: + +* Validate all known Elastic custom resources (Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash) on create and update. +* The operator itself is the webhook server — which is exposed through a service named `elastic-webhook-server` in the `elastic-system` namespace. +* The operator generates a certificate for the webhook and stores it in a secret named `elastic-webhook-server-cert` in the `elastic-system` namespace. This certificate is automatically rotated by the operator when it is due to expire. + + +## Manual configuration [k8s-webhook-manual-config] + +If you installed ECK without the webhook and want to enable it later on, or if you want to customise the configuration such as providing your own certificates, this section describes the options available to you. + + +### Configuration options [k8s-webhook-config-options] + +You can customise almost all aspects of the webhook setup by changing the [operator configuration](configure-eck.md). + +| Configuration option | Default value | Description | +| --- | --- | --- | +| `enable-webhook` | false | This must be set to `true` to enable the webhook server. | +| `manage-webhook-certs` | true | Set to `false` to disable auto-generating the certificate for the webhook. If disabled, you must provide your own certificates using one of the methods described later in this document. | +| `webhook-cert-dir` | /tmp/k8s-webhook-server/serving-certs | Path to mount the certificate. | +| `webhook-name` | elastic-webhook.k8s.elastic.co | Name of the `ValidatingWebhookConfiguration` resource. | +| `webhook-secret` | elastic-webhook-server-cert | Name of the secret containing the certificate for the webhook server. | +| `webhook-port` | 9443 | Port to listen for incoming validation requests. | + + +### Using your own certificates [k8s-webhook-existing-certs] + +This section describes how you can use your own certificates for the webhook instead of letting the operator manage them automatically. There are a few important things to be aware of when going down this route: + +* You have to keep track of the expiry dates and manage the certificate rotation yourself. Expired certificates may stop the webhook from working. +* The secret containing the custom certificate must be available when the operator starts. +* You must update the `caBundle` fields in the `ValidatingWebhookConfiguration` yourself. This must be done at the beginning and whenever the certificate is rotated. + + +#### Use a certificate signed by your own CA [k8s-webhook-own-ca] + +* The certificate must have a Subject Alternative Name (SAN) of the form `..svc` (for example `elastic-webhook-server.elastic-system.svc`). A typical OpenSSL command to generate such a certificate would be as follows: + + ```sh + openssl req -x509 -sha256 -nodes -newkey rsa:4096 -days 365 -subj "/CN=elastic-webhook-server" -addext "subjectAltName=DNS:elastic-webhook-server.elastic-system.svc" -keyout tls.key -out tls.crt + ``` + +* Create a secret in the namespace the operator would be deployed to. This secret must contain the certificate under the `tls.crt` key and the private key under the `tls.key` key. + + ```sh + kubectl create secret -n elastic-system generic elastic-webhook-server-custom-cert --from-file=tls.crt=tls.crt --from-file=tls.key=tls.key + ``` + +* Encode your CA trust chain as base64 and set it as the value of the `caBundle` fields in the `ValidatingWebhookConfiguration`. Note that there are multiple `caBundle` fields in the webhook configuration. +* Install the operator with the following options: + + * Set `manage-webhook-certs` to `false` + * Set `webhook-secret` to the name of the secret you have just created (`elastic-webhook-server-custom-cert`) + + +::::{note} +If you are using the [Helm chart installation method](install-using-helm-chart.md), you can install the operator by running this command: + +```sh +helm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace \ + --set=webhook.manageCerts=false \ + --set=webhook.certsSecret=elastic-webhook-server-custom-cert \ + --set=webhook.caBundle=$(base64 -w 0 ca.crt) +``` + +:::: + + + +#### Use a certificate from cert-manager [k8s-webhook-cert-manager] + +This section describes how to use [cert-manager](https://cert-manager.io/) to manage the webhook certificate. It assumes that there is a `ClusterIssuer` named `self-signing-issuer` available. + +* Create a new certificate + + ```yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: elastic-webhook-server-cert + namespace: elastic-system + spec: + dnsNames: + - elastic-webhook-server.elastic-system.svc + issuerRef: + kind: ClusterIssuer + name: self-signing-issuer + secretName: elastic-webhook-server-cert + subject: + organizations: + - example + ``` + +* Annotate the `ValidatingWebhookConfiguration` to inject the CA bundle: + + ```yaml + apiVersion: admissionregistration.k8s.io/v1 + kind: ValidatingWebhookConfiguration + metadata: + annotations: + cert-manager.io/inject-ca-from: elastic-system/elastic-webhook-server-cert + name: elastic-webhook.k8s.elastic.co + webhooks: + [...] + ``` + +* Install the operator with the following options: + + * Set `manage-webhook-certs` to `false` + * Set `webhook-secret` to the name of the certificate secret (`elastic-webhook-server-cert`) + + +::::{note} +If you are using the [Helm chart installation method](install-using-helm-chart.md), you can install the operator by running the following command: + +```sh +helm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace \ + --set=webhook.manageCerts=false \ + --set=webhook.certsSecret=elastic-webhook-server-cert \ + --set=webhook.certManagerCert=elastic-webhook-server-cert +``` + +:::: + + + +## Disable the webhook [k8s-disable-webhook] + +To disable the webhook, set the [`enable-webhook`](configure-eck.md) operator configuration flag to `false` and remove the `ValidatingWebhookConfiguration` named `elastic-webhook.k8s.elastic.co`: + +```sh +kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io elastic-webhook.k8s.elastic.co +``` + + +## Troubleshooting [k8s-webhook-troubleshooting] + +You might get errors in your Kubernetes API server logs indicating that it cannot reach the operator service (`elastic-webhook-server`). This could be because no operator pods are available to handle request or because a network policy or a firewall rule is preventing the control plane from accessing the service. To help with troubleshooting, you can change the [`failurePolicy`](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#failure-policy) of the webhook configuration to `Fail`. This will cause create or update operations to fail if there is an error contacting the webhook. Usually the error message will contain helpful information about the failure that will allow you to diagnose the root cause. + + +### Resource creation taking too long or timing out [k8s-webhook-troubleshooting-timeouts] + +Webhooks require network connectivity between the Kubernetes API server and the operator. If the creation of an Elasticsearch resource times out with an error message similar to the following, then the Kubernetes API server might be unable to connect to the webhook to validate the manifest. + +``` +Error from server (Timeout): error when creating "elasticsearch.yaml": Timeout: request did not complete within requested timeout 30s +``` +If you get this error, try re-running the command with a higher request timeout as follows: + +```sh +kubectl --request-timeout=1m apply -f elasticsearch.yaml +``` + +As the default [`failurePolicy`](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#failure-policy) of the webhook is `Ignore`, this command should succeed after about 30 seconds. This is an indication that the API server cannot contact the webhook server and has foregone validation when creating the resource. + +On [GKE private clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/private-cluster-concept), you may have to add a firewall rule allowing access to port 9443 from the API server so that it can contact the webhook. Check the [GKE documentation on firewall rules](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules) and the [Kubernetes issue](https://github.com/kubernetes/kubernetes/issues/79739) for more details. + +It is possible that a [network policy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) is blocking any incoming requests to the webhook server. Consult your system administrator to determine whether that is the case, and create an appropriate policy to allow communication between the Kubernetes API server and the webhook server. For example, the following network policy simply opens up the webhook port to the world: + +```yaml +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + name: allow-webhook-access-from-any + namespace: elastic-system +spec: + podSelector: + matchLabels: + control-plane: elastic-operator + ingress: + - from: [] + ports: + - port: 9443 +``` + +If you want to restrict the webhook access only to the Kubernetes API server, you must know the IP address of the API server, that you can obtain through this command: + +```sh +kubectl cluster-info | grep master +``` + +Assuming that the API server IP address is `10.1.0.1`, the following policy restricts webhook access to just the API server. + +```yaml +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + name: allow-webhook-access-from-apiserver + namespace: elastic-system +spec: + podSelector: + matchLabels: + control-plane: elastic-operator + ingress: + - from: + - ipBlock: + cidr: 10.1.0.1/32 + ports: + - port: 9443 +``` + + +### Updates failing due to validation errors [k8s-webhook-troubleshooting-validation-failure] + +If your attempts to update a resource fail with an error message similar to the following, you can force the webhook to ignore it by removing the `kubectl.kubernetes.io/last-applied-configuration` annotation from your resource. + +``` +admission webhook "elastic-es-validation-v1.k8s.elastic.co" denied the request: Elasticsearch.elasticsearch.k8s.elastic.co "quickstart" is invalid: some-misspelled-field: Invalid value: "some-misspelled-field": some-misspelled-field field found in the kubectl.kubernetes.io/last-applied-configuration annotation is unknown +``` diff --git a/deploy-manage/deploy/cloud-on-k8s/configure.md b/deploy-manage/deploy/cloud-on-k8s/configure.md new file mode 100644 index 000000000..dd31d9655 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/configure.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-operating-eck.html +--- + +# Configure [k8s-operating-eck] + +* [*Configure ECK*](configure-eck.md) +* [*Required RBAC permissions*](required-rbac-permissions.md) +* [*Configure the validating webhook*](configure-validating-webhook.md) +* [*Configure the metrics endpoint*](../../monitor/orchestrators/eck-metrics-configuration.md) +* [*Restrict cross-namespace resource associations*](restrict-cross-namespace-resource-associations.md) +* [*Manage licenses in ECK*](../../license/manage-your-license-in-eck.md) +* [*Install ECK*](install.md) +* [*Upgrade ECK*](../../upgrade/orchestrator/upgrade-cloud-on-k8s.md) +* [*Uninstall ECK*](../../uninstall/uninstall-elastic-cloud-on-kubernetes.md) +* [*Running in air-gapped environments*](air-gapped-install.md) + diff --git a/deploy-manage/deploy/cloud-on-k8s/connect-to-apm-server.md b/deploy-manage/deploy/cloud-on-k8s/connect-to-apm-server.md new file mode 100644 index 000000000..a67608d3e --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/connect-to-apm-server.md @@ -0,0 +1,47 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-apm-connecting.html +--- + +# Connect to the APM Server [k8s-apm-connecting] + +This section covers the following topics: + +* [APM Server service](#k8s-apm-service) +* [APM Server secret token](#k8s-apm-secret-token) +* [APM Server API keys](#k8s-apm-api-keys) + +## APM Server service [k8s-apm-service] + +The APM Server is exposed with a Service. For information on accessing it, check [How to access Elastic Stack services](accessing-services.md). + +To retrieve the list of all the APM Services, use the following command: + +```sh +kubectl get service --selector='common.k8s.elastic.co/type=apm-server' +``` + +```sh +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +apm-server-quickstart-apm-http ClusterIP 10.0.1.252 8200/TCP 154m +``` + + +## APM Server secret token [k8s-apm-secret-token] + +The operator generates an authorization token that agents must send to authenticate themselves to the APM Server. + +This token is stored in a secret named `{{APM-server-name}}-apm-token` and can be retrieved with the following command: + +```sh +kubectl get secret/apm-server-quickstart-apm-token -o go-template='{{index .data "secret-token" | base64decode}}' +``` + +For more information, check [APM Server Reference](https://www.elastic.co/guide/en/apm/server/current/index.html). + + +## APM Server API keys [k8s-apm-api-keys] + +If you want to configure API keys to authorize requests to the APM Server, instead of using the APM Server CLI, you have to create API keys using the Elasticsearch [create API key API](https://www.elastic.co/guide/en/elasticsearch/reference/7.14/security-api-create-api-key.html), check the [APM Server documentation](https://www.elastic.co/guide/en/apm/server/current/api-key.html#create-api-key-workflow-es). + + diff --git a/deploy-manage/deploy/cloud-on-k8s/connect-to-external-elastic-resources.md b/deploy-manage/deploy/cloud-on-k8s/connect-to-external-elastic-resources.md new file mode 100644 index 000000000..4353ef8e6 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/connect-to-external-elastic-resources.md @@ -0,0 +1,73 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-connect-to-unmanaged-resources.html +--- + +# Connect to external Elastic resources [k8s-connect-to-unmanaged-resources] + +Fields like `elasticsearchRef` or `kibanaRef` are useful to automatically establish connections between applications managed by the same ECK operator instance. It is however also possible to connect to applications managed by a different ECK operator instance, or to applications not managed by ECK, for example an Elastic Cloud deployment. This can be done by providing connection details and credentials in a `Secret` through the `secretName` attribute: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: external-es-ref +stringData: + url: https://sample.gcp.elastic-cloud.com + username: "elastic" + password: REDACTED +--- +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: kibana-sample +spec: + version: 8.14.0 + count: 1 + elasticsearchRef: + secretName: external-es-ref +``` + +In the case of Elastic Agent you can also specify several named references: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: external-es-ref +stringData: + url: https://abcd-42.xyz.elastic-cloud.com:443 + username: "" + password: "" + api-key: REDACTED + ca.crt: REDACTED + +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: quickstart +spec: + version: 8.16.1 + elasticsearchRefs: + - outputName: default + secretName: external-es-ref + - outputName: monitoring + secretName: external-es-ref2 +``` + +The following fields are expected to be set in the referenced `Secret`: + +* `url` (required): URL to be used to access the external resource. +* `username` (required): The username of the user to be authenticated to the Elastic resource. +* `password` (required): The password for the provided user. +* `ca.crt` (optional): The certificate authority to be used to connect to the external resource. + +In the case of Agent and Beats resources the following field can also be used to connect to Elasticsearch: + +* `api-key`: An API key to authenticate against the Elastic resource. + +::::{note} +The operator must be able to connect to the external resources to check version compatibility. +:::: + + diff --git a/deploy-manage/deploy/cloud-on-k8s/create-custom-images.md b/deploy-manage/deploy/cloud-on-k8s/create-custom-images.md new file mode 100644 index 000000000..3710c0afb --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/create-custom-images.md @@ -0,0 +1,55 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-custom-images.html +--- + +# Create custom images [k8s-custom-images] + +You can create your own custom application images (Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash) instead of using the base images provided by Elastic. You might want to do this to have a canonical image with all the necessary plugins pre-loaded rather than [installing them through an init container](init-containers-for-plugin-downloads.md) each time a Pod starts. You must use the official image as the base for custom images. For example, if you want to create an Elasticsearch 8.16.1 image with the [ICU Analysis Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-icu.html), you can do the following: + +1. Create a `Dockerfile` containing: + + ``` + FROM docker.elastic.co/elasticsearch/elasticsearch:8.16.1 + RUN bin/elasticsearch-plugin install --batch analysis-icu + ``` + +2. Build the image with: + + ``` + docker build --tag elasticsearch-icu:8.16.1 + ``` + + +There are various hosting options for your images. If you use Google Kubernetes Engine, it is automatically configured to use the Google Container Registry. Check [Using Container Registry with Google Cloud](https://cloud.google.com/container-registry/docs/using-with-google-cloud-platform#google-kubernetes-engine) for more information. To use the image, you can then [push to the registry](https://cloud.google.com/container-registry/docs/pushing-and-pulling#pushing_an_image_to_a_registry) with: + +``` +docker tag elasticsearch-icu:8.16.1 gcr.io/$PROJECT-ID/elasticsearch-icu:8.16.1 +docker push gcr.io/$PROJECT-ID/elasticsearch-icu:8.16.1 +``` + +Configure your Elasticsearch specification to use the newly pushed image, for example: + +```yaml +spec: + version: 8.16.1 + image: gcr.io/$PROJECT-ID/elasticsearch-icu:8.16.1 +``` + +::::{note} +Providing the correct version is always required as ECK reasons about APIs and capabilities available to it based on the version field. +:::: + + +The steps are similar for [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/tutorial-kubernetes-prepare-acr) and [AWS Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-basics.md#use-ecr). + +If your custom images follow the naming convention adopted by the official images, and you only want to use your custom images, you can also simply [override the container registry](air-gapped-install.md#k8s-container-registry-override). + +For more information, check the following references: + +* [Elasticsearch documentation on Using custom Docker images](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#_c_customized_image) +* [Google Container Registry](https://cloud.google.com/container-registry/docs/how-to) +* [Azure Container Registry](https://docs.microsoft.com/en-us/azure/container-registry/) +* [Amazon Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.md) +* [OpenShift Container Platform registry](https://docs.openshift.com/container-platform/4.12/registry/index.md) + diff --git a/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md b/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md new file mode 100644 index 000000000..20d08630c --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md @@ -0,0 +1,108 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-bundles-plugins.html +--- + +# Custom configuration files and plugins [k8s-bundles-plugins] + +To run Elasticsearch with specific plugins or configuration files installed on ECK, you have two options. Each option has its own pros and cons. + +1. Create a custom container image with the required plugins and configuration files. + + * **Pros** + + * Deployment is reproducible and reusable. + * Does not require internet access at runtime. + * Saves bandwidth and is quicker to start. + + * **Cons** + + * Requires a container registry and build infrastructure to build and host the custom image. + * Version upgrades require building a new container image. + +2. Use init containers to install plugins and configuration files. + + * **Pros** + + * Easier to get started and upgrade versions. + + * **Cons** + + * Requires pods to have internet access. **Check [the note about using Istio](#istio-note)**. + * Adding new Elasticsearch nodes could randomly fail due to network issues or bad configuration. + * Each Elasticsearch node needs to repeat the download, wasting bandwidth and slowing startup. + * Deployment manifests are more complicated. + + +Refer to [Creating custom images](create-custom-images.md) for instructions on how to build custom Docker images based on the official Elastic images. + +The following example describes option 2, using a repository plugin. To install the plugin before the Elasticsearch nodes start, use an init container to run the [plugin installation tool](https://www.elastic.co/guide/en/elasticsearch/plugins/current/installation.html). + +```yaml +spec: + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + initContainers: + - name: install-plugins + command: + - sh + - -c + - | + bin/elasticsearch-plugin remove --purge repository-azure + bin/elasticsearch-plugin install --batch repository-azure +``` + +To install custom configuration files you can use volumes and volume mounts. + +The next example shows how to add a synonyms file for the [synonym token filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-tokenfilter.html) in Elasticsearch. But you can use the same approach for any kind of file you want to mount into the configuration directory of Elasticsearch. + +```yaml +spec: + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + containers: + - name: elasticsearch <1> + volumeMounts: + - name: synonyms + mountPath: /usr/share/elasticsearch/config/dictionaries + volumes: + - name: synonyms + configMap: + name: synonyms <2> +``` + +1. Elasticsearch runs by convention in a container called *elasticsearch*. +2. Assuming you have created a config map in the same namespace as Elasticsearch with the name *synonyms* containing the synonyms file(s). + + +$$$istio-note$$$ +**Note when using Istio** + +When using Istio, init containers do **not** have network access, as the Envoy sidecar that provides network connectivity is not started yet. In this scenario, custom containers are the best option. If custom containers are simply not a viable option, then it is possible to adjust the startup command for the elasticsearch container itself to run the plugin installation before starting Elasticsearch, as the following example describes. Note that this approach will require updating the startup command if it changes in the Elasticsearch image, which could potentially cause failures during upgrades. + +```yaml +spec: + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + containers: + - name: elasticsearch + command: + - /usr/bin/env + - bash + - -c + - | + #!/usr/bin/env bash + set -e + bin/elasticsearch-plugin remove --purge repository-s3 || true + bin/elasticsearch-plugin install --batch repository-s3 + /bin/tini -- /usr/local/bin/docker-entrypoint.sh +``` diff --git a/deploy-manage/deploy/cloud-on-k8s/customize-pods.md b/deploy-manage/deploy/cloud-on-k8s/customize-pods.md new file mode 100644 index 000000000..83d489834 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/customize-pods.md @@ -0,0 +1,100 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-customize-pods.html +--- + +# Customize pods [k8s-customize-pods] + +You can customize the Pods created for each Elastic stack application by modifying the respective `podTemplate` field in the manifest. Pod templates allow you to define labels, annotations, environment variables, volume mounts, and other custom configuration settings that are then merged with the default Pod configuration generated by ECK to produce the final Pod definition that gets deployed to the Kubernetes cluster. + +The following example illustrates how to add a custom label, annotation, and an environment variable using the `podTemplate` field. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + podTemplate: + metadata: + labels: + my.custom.domain/label: "label-value" + annotations: + my.custom.domain/annotation: "annotation-value" + spec: + containers: + - name: elasticsearch + env: + - name: ES_JAVA_OPTS + value: "-Xms4g -Xmx4g" +``` + +```yaml +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + podTemplate: + metadata: + labels: + my.custom.domain/label: "label-value" + annotations: + my.custom.domain/annotation: "annotation-value" + spec: + containers: + - name: kibana + env: + - name: NODE_OPTIONS + value: "--max-old-space-size=2048" +``` + +::::{note} +Configuration for other Elastic stack applications, like APM Server, Enterprise Search or Beats, is identical to the Kibana configuration except for the `apiVersion` and `kind` fields. +:::: + + +The following example shows how it’s also possible to customize the init containers created as part of the Pods to initialize the filesystem or to manage the keystores. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + initContainers: + - name: elastic-internal-init-keystore + resources: # override the default resources set by the operator + limits: + cpu: 1000m + memory: 368Mi + requests: + cpu: 1000m + memory: 368Mi + secureSettings: + - secretName: es-secret +``` + + +## More examples [k8s_more_examples_2] + +* [Init containers for plugin downloads](init-containers-for-plugin-downloads.md) +* [*Manage compute resources*](manage-compute-resources.md) + +For further information: + +* [Pod templates overview](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) +* [Pod template spec API reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#podtemplatespec-v1-core) + diff --git a/deploy-manage/deploy/cloud-on-k8s/deploy-an-orchestrator.md b/deploy-manage/deploy/cloud-on-k8s/deploy-an-orchestrator.md new file mode 100644 index 000000000..d942cbfa4 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/deploy-an-orchestrator.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-quickstart.html +--- + +# Deploy an orchestrator [k8s-quickstart] + +With Elastic Cloud on Kubernetes (ECK) you can extend the basic Kubernetes orchestration capabilities to easily deploy, secure, upgrade your {{es}} cluster, and much more. + +Eager to get started? This quickstart guide shows you how to: + +* [Deploy ECK in your Kubernetes cluster](install-using-yaml-manifest-quickstart.md) +* [Deploy an {{es}} cluster](elasticsearch-deployment-quickstart.md) +* [Deploy a {{kib}} instance](kibana-instance-quickstart.md) +* [Update your deployment](update-deployments.md) + +Afterwards, you can find further sample resources [in the project repository](https://github.com/elastic/cloud-on-k8s/tree/2.16/config/samples) or by checking out [our recipes](recipes.md). + diff --git a/deploy-manage/deploy/cloud-on-k8s/deploy-eck-on-gke-autopilot.md b/deploy-manage/deploy/cloud-on-k8s/deploy-eck-on-gke-autopilot.md new file mode 100644 index 000000000..b3f6bb82f --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/deploy-eck-on-gke-autopilot.md @@ -0,0 +1,24 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-autopilot.html +--- + +# Deploy ECK on GKE Autopilot [k8s-autopilot] + +This page shows how to run ECK on GKE Autopilot. + +1. It is recommended that each Kubernetes host’s virtual memory kernel settings be modified. Refer to [Virtual memory](virtual-memory.md). +2. It is recommended that Elasticsearch Pods have an `initContainer` that waits for virtual memory settings to be in place. Refer to [Deploy an Elasticsearch instance](k8s-autopilot-deploy-elasticsearch.md). +3. For Elastic Agent/Beats there are storage limitations to be considered. Refer to [Deploy a standalone Elastic Agent and/or Beats](k8s-autopilot-deploy-agent-beats.md) +4. Ensure you are using a node class that is applicable for your workload by adding a `cloud.google.com/compute-class` label in a `nodeSelector`. Refer to [GKE Autopilot documentation.](https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-compute-classes) + + * [Ensuring virtual memory kernel settings](k8s-autopilot-setting-virtual-memory.md) + * [Installing the ECK Operator](k8s-autopilot-deploy-operator.md) + * [Deploy an Elasticsearch instance](k8s-autopilot-deploy-elasticsearch.md) + * [Deploy a standalone Elastic Agent and/or Beats](k8s-autopilot-deploy-agent-beats.md) + + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/deploy-eck-on-openshift.md b/deploy-manage/deploy/cloud-on-k8s/deploy-eck-on-openshift.md new file mode 100644 index 000000000..721093722 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/deploy-eck-on-openshift.md @@ -0,0 +1,41 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-openshift.html +--- + +# Deploy ECK on Openshift [k8s-openshift] + +This page shows how to run ECK on OpenShift. + +* [Before you begin](#k8s-openshift-before-you-begin) +* [Deploy the operator](k8s-openshift-deploy-operator.md) +* [Deploy an Elasticsearch instance with a route](k8s-openshift-deploy-elasticsearch.md) +* [Deploy a Kibana instance with a route](k8s-openshift-deploy-kibana.md) +* [Deploy Docker images with `anyuid` SCC](k8s-openshift-anyuid-workaround.md) +* [Grant privileged permissions to Beats](k8s-openshift-beats.md) +* [Grant host access permission to Elastic Agent](k8s-openshift-agent.md) + +::::{warning} +Some Docker images are incompatible with the `restricted` SCC. This is the case for the **APM Server before 7.9** and for **Enterprise Search 7.9 and 7.10**. You can use this [workaround](k8s-openshift-anyuid-workaround.md) to run those images with the `anyuid` SCC. +:::: + + + +## Before you begin [k8s-openshift-before-you-begin] + +1. To run the instructions on this page, you must be a `system:admin` user or a user with the privileges to create Projects, CRDs, and RBAC resources at the cluster level. +2. Set virtual memory settings on the Kubernetes nodes. + + Before deploying an Elasticsearch cluster with ECK, make sure that the Kubernetes nodes in your cluster have the correct `vm.max_map_count` sysctl setting applied. By default, Pods created by ECK are likely to run with the `restricted` [Security Context Constraint](https://docs.openshift.com/container-platform/4.12/authentication/managing-security-context-constraints.md) (SCC) which restricts privileged access required to change this setting in the underlying Kubernetes nodes. + + Alternatively, you can opt for setting `node.store.allow_mmap: false` at the [Elasticsearch node configuration](node-configuration.md) level. This has performance implications and is not recommended for production workloads. + + For more information, check [Virtual memory](virtual-memory.md). + + + + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/deploy-elastic-maps-server.md b/deploy-manage/deploy/cloud-on-k8s/deploy-elastic-maps-server.md new file mode 100644 index 000000000..41140b7aa --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/deploy-elastic-maps-server.md @@ -0,0 +1,48 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-maps-es.html +--- + +# Deploy Elastic Maps Server [k8s-maps-es] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +Deploying Elastic Maps Server can be done with a simple manifest: + +```yaml +apiVersion: maps.k8s.elastic.co/v1alpha1 +kind: ElasticMapsServer +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 +``` + +Versions of Elastic Maps Server prior to 7.14 need a connection to Elasticseach to verify the installed license. You define the connection with the `elasticsearchRef` attribute: + +```yaml +apiVersion: maps.k8s.elastic.co/v1alpha1 +kind: ElasticMapsServer +metadata: + name: quickstart +spec: + version: 7.13 + count: 1 + elasticsearchRef: + name: quickstart + namespace: default +``` + +The use of `namespace` is optional if the Elasticsearch cluster is running in the same namespace as Elastic Maps Server. + +::::{note} +Any Elastic Maps Server can reference (and thus access) any Elasticsearch instance as long as they are both in namespaces that are watched by the same ECK instance. ECK will copy the required Secret from Elasticsearch to the Elastic Maps Server namespace. Elastic Maps Server cannot automatically connect to Elasticsearch (through `elasticsearchRef`) in a namespace managed by a different ECK instance. For more information, check [Restrict cross-namespace resource associations](restrict-cross-namespace-resource-associations.md). +:::: + + +The Elastic Maps Server configuration file is automatically setup by ECK to establish a secure connection to Elasticsearch. + diff --git a/deploy-manage/deploy/cloud-on-k8s/deploy-fips-compatible-version-of-eck.md b/deploy-manage/deploy/cloud-on-k8s/deploy-fips-compatible-version-of-eck.md new file mode 100644 index 000000000..19ec55a2c --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/deploy-fips-compatible-version-of-eck.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-fips.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_installation.html +--- + +# Deploy a FIPS compatible version of ECK + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/357 + +% Scope notes: Merge both docs into 1 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-fips.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s_installation.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/elastic-maps-server.md b/deploy-manage/deploy/cloud-on-k8s/elastic-maps-server.md new file mode 100644 index 000000000..7b1e3febe --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/elastic-maps-server.md @@ -0,0 +1,39 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-maps.html +--- + +# Elastic Maps Server [k8s-maps] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +If you cannot connect to Elastic Maps Service from the Kibana server or browser clients, and you are running ECK with an Enterprise license, you can opt to host the service on your Kubernetes cluster. Check also the [Elastic Maps Server documentation.](https://www.elastic.co/guide/en/kibana/current/maps-connect-to-ems.html#elastic-maps-server) + +The following sections describe how to customize an Elastic Maps Server deployment to suit your requirements. + +* [Deploy Elastic Maps Server](deploy-elastic-maps-server.md) +* [Map data](map-data.md) + + * [Basemap Download](map-data.md#k8s-maps-basemap-download) + * [Pod Configuration](map-data.md#k8s-maps-pod-configuration) + +* [Advanced configuration](advanced-configuration-maps-server.md) + + * [Elastic Maps Server configuration](advanced-configuration-maps-server.md#k8s-maps-configuration) + * [Scale out an Elastic Maps Server deployment](advanced-configuration-maps-server.md#k8s-maps-scaling) + +* [HTTP Configuration](http-configuration.md) + + * [Load balancer settings and TLS SANs](http-configuration.md#k8s-maps-http-publish) + * [Provide your own certificate](http-configuration.md#k8s-maps-http-custom-tls) + * [Disable TLS](http-configuration.md#k8s-maps-http-disable-tls) + * [Ingress and Kibana configuration](http-configuration.md#k8s-maps-ingress) + + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/elastic-stack-configuration-policies.md b/deploy-manage/deploy/cloud-on-k8s/elastic-stack-configuration-policies.md new file mode 100644 index 000000000..d78f90c84 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/elastic-stack-configuration-policies.md @@ -0,0 +1,328 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-stack-config-policy.html +--- + +# Elastic Stack configuration policies [k8s-stack-config-policy] + +::::{warning} +We have identified an issue with Elasticsearch 8.15.1 and 8.15.2 that prevents security role mappings configured via Stack configuration policies to work correctly. Avoid these versions and upgrade to 8.16.0 to remedy this issue if you are affected. +:::: + + +::::{note} +This requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +Starting from ECK `2.6.1` and Elasticsearch `8.6.1`, Elastic Stack configuration policies allow you to configure the following settings for Elasticsearch: + +* [Cluster Settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html#dynamic-cluster-setting) +* [Snapshot Repositories](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html) +* [Snapshot Lifecycle Policies](https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put-policy.html) +* [Ingest pipelines](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-pipeline-api.html) +* [Index Lifecycle Policies](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-put-lifecycle.html) +* [Index templates](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-template.html) +* [Components templates](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-component-template.html) +* [Role mappings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html) +* [Elasticsearch Configuration](https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html) (configuration settings for Elasticsearch that will go into `elasticsearch.yml`) [ECK 2.11.0] +* [Elasticsearch Secure Settings](../../security/secure-settings.md) [ECK 2.11.0] +* [Secret Mounts](#k8s-stack-config-policy-specifics-secret-mounts) [ECK 2.11.0] + +Additionally with ECK `2.11.0` it is possible to configure Kibana as well using Elastic Stack configuration policies, the following settings can be configured for Kibana: + +* [Kibana Configuration](https://www.elastic.co/guide/en/kibana/current/settings.html) (configuration settings for Kibana that will go into `kibana.yml`) +* [Kibana Secure Settings](k8s-kibana-secure-settings.md) + +A policy can be applied to one or more Elasticsearch clusters or Kibana instances in any namespace managed by the ECK operator. Configuration policy settings applied by the ECK operator are immutable through the Elasticsearch REST API. It is currently not allowed to configure an Elasticsearch cluster or Kibana instance with more than one policy. + + +## Define Elastic Stack configuration policies [k8s-stack-config-policy-definition] + +Elastic Stack configuration policies can be defined in a `StackConfigPolicy` resource. Each `StackConfigPolicy` must have the following field: + +* `name` is a unique name used to identify the policy. + +At least one of `spec.elasticsearch` or `spec.kibana` needs to be defined with at least one of its attributes. + +* `spec.elasticsearch` describes the settings to configure for Elasticsearch. Each of the following fields except `clusterSettings` is an associative array where keys are arbitrary names and values are definitions: + + * `clusterSettings` are dynamic settings that can be set on a running cluster like with the Cluster Update Settings API. + * `snapshotRepositories` are snapshot repositories for defining an off-cluster storage location for your snapshots. Check [Specifics for snapshot repositories](#k8s-stack-config-policy-specifics-snap-repo) for more information. + * `snapshotLifecyclePolicies` are snapshot lifecycle policies, to automatically take snapshots and control how long they are retained. + * `securityRoleMappings` are role mappings, to define which roles are assigned to each user by identifying them through rules. + * `ingestPipelines` are ingest pipelines, to perform common transformations on your data before indexing. + * `indexLifecyclePolicies` are index lifecycle policies, to automatically manage the index lifecycle. + * `indexTemplates.componentTemplates` are component templates that are building blocks for constructing index templates that specify index mappings, settings, and aliases. + * `indexTemplates.composableIndexTemplates` are index templates to define settings, mappings, and aliases that can be applied automatically to new indices. + * `config` are the settings that go into the `elasticsearch.yml` file. + * `secretMounts` are the additional user created secrets that need to be mounted to the Elasticsearch Pods. + * `secureSettings` is a list of Secrets containing Secure Settings to inject into the keystore(s) of the Elasticsearch cluster(s) to which this policy applies, similar to the [Elasticsearch Secure Settings](../../security/secure-settings.md). + +* `spec.kibana` describes the settings to configure for Kibana. + + * `config` are the settings that go into the `kibana.yml` file. + * `secureSettings` is a list of Secrets containing Secure Settings to inject into the keystore(s) of the Kibana instance(s) to which this policy applies, similar to the [Kibana Secure Settings](k8s-kibana-secure-settings.md). + + +The following fields are optional: + +* `namespace` is the namespace of the `StackConfigPolicy` resource and used to identify the Elasticsearch clusters to which this policy applies. If it equals to the operator namespace, the policy applies to all namespaces managed by the operator, otherwise the policy only applies to the namespace of the policy. +* `resourceSelector` is a [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to identify the Elasticsearch clusters to which this policy applies in combination with the namespace(s). No `resourceSelector` means all Elasticsearch clusters in the namespace(s). + +Example of applying a policy that configures snapshot repository, SLM Policies, and cluster settings: + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy + # namespace: elastic-system or test-namespace +spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + clusterSettings: + indices.recovery.max_bytes_per_sec: "100mb" + secureSettings: + - secretName: "my-secure-settings" + snapshotRepositories: + test-repo: + type: gcs + settings: + bucket: my-bucket + snapshotLifecyclePolicies: + test-slm: + schedule: "0 1 2 3 4 ?" + name: "" + repository: test-repo + config: + indices: ["*"] + ignore_unavailable: true + include_global_state: false + retention: + expire_after: "7d" + min_count: 1 + max_count: 20 +``` + +Another example of configuring role mappings, ingest pipelines, ILM and index templates: + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy +spec: + elasticsearch: + securityRoleMappings: + everyone-kibana: + enabled: true + metadata: + _foo: something + uuid: b9a59ba9-6b92-4be2-bb8d-02bb270cb3a7 + roles: + - kibana_user + rules: + field: + username: '*' + ingestPipelines: + test-pipeline: + description: "optional description" + processors: + - set: + field: my-keyword-field + value: foo + test-2-pipeline: + description: "optional description" + processors: + - set: + field: my-keyword-field + value: foo + indexLifecyclePolicies: + test-ilm: + phases: + delete: + actions: + delete: {} + min_age: 30d + warm: + actions: + forcemerge: + max_num_segments: 1 + min_age: 10d + indexTemplates: + componentTemplates: + test-component-template: + template: + mappings: + properties: + '@timestamp': + type: date + test-runtime-component-template-test: + template: + mappings: + runtime: + day_of_week: + type: keyword + composableIndexTemplates: + test-template: + composed_of: + - test-component-template + - test-runtime-component-template-test + index_patterns: + - test* + - bar* + priority: 500 + template: + aliases: + mydata: {} + mappings: + _source: + enabled: true + properties: + created_at: + format: EEE MMM dd HH:mm:ss Z yyyy + type: date + host_name: + type: keyword + settings: + number_of_shards: 1 + version: 1 +``` + +Example of configuring Elasticsearch and Kibana using an Elastic Stack configuration policy: + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy +spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + secureSettings: + - secretName: shared-secret + securityRoleMappings: + jwt1-elastic-agent: + roles: [ "remote_monitoring_collector" ] + rules: + all: + - field: { realm.name: "jwt1" } + - field: { username: "elastic-agent" } + enabled: true + config: + logger.org.elasticsearch.discovery: DEBUG + xpack.security.authc.realms.jwt.jwt1: + order: -98 + token_type: id_token + client_authentication.type: shared_secret + allowed_issuer: "https://es.credentials.controller.k8s.elastic.co" + allowed_audiences: [ "elasticsearch" ] + allowed_subjects: ["elastic-agent"] + allowed_signature_algorithms: [RS512] + pkc_jwkset_path: jwks/jwkset.json + claims.principal: sub + secretMounts: + - secretName: "testMountSecret" + mountPath: "/usr/share/testmount" + - secretName: jwks-secret + mountPath: "/usr/share/elasticsearch/config/jwks" + kibana: + config: + "xpack.canvas.enabled": true + secureSettings: + - secretName: kibana-shared-secret +``` + + +## Monitor Elastic Stack configuration policies [k8s-stack-config-policy-monitoring] + +In addition to the logs generated by the operator, a config policy status is maintained in the `StackConfigPolicy` resource. This status gives information in which phase the policy is ("Applying", "Ready", "Error") and it indicates the number of resources for which the policy could be applied. + +```sh +kubectl get stackconfigpolicy +``` + +```sh +NAME READY PHASE AGE +test-stack-config-policy 1/1 Ready 1m42s +test-err-stack-config-policy 0/1 Error 1m42s +``` + +When not all resources are ready, you can get more information about the reason by reading the full status: + +```sh +kubectl get -n b scp test-err-stack-config-policy -o jsonpath="{.status}" | jq . +``` + +```json +{ + "errors": 1, + "observedGeneration": 3, + "phase": "Error", + "readyCount": "1/2", + "resources": 2, + "details": { + "elasticsearch": { + "b/banana-staging": { + "currentVersion": 1670342369361604600, + "error": { + "message": "Error processing slm state change: java.lang.IllegalArgumentException: Error on validating SLM requests\n\tSuppressed: java.lang.IllegalArgumentException: no such repository [es-snapshots]", + "version": 1670342482739637500 + }, + "expectedVersion": 1670342482739637500, + "phase": "Error" + } + }, + "kibana": { + "b/banana-kb-staging": { + "error": {}, + "phase": "Ready" + } + } + } +} +``` + +Important events are also reported through Kubernetes events, such as when two config policies conflict or you don’t have the appropriate license: + +```sh +54s Warning Unexpected stackconfigpolicy/config-test conflict: resource Elasticsearch ns1/cluster-a already configured by StackConfigpolicy default/config-test-2 +``` + +```sh +17s Warning ReconciliationError stackconfigpolicy/config-test StackConfigPolicy is an enterprise feature. Enterprise features are disabled +``` + + +## Specifics for snapshot repositories [k8s-stack-config-policy-specifics-snap-repo] + +In order to avoid a conflict between multiple Elasticsearch clusters writing their snapshots to the same location, ECK automatically: + +* sets the `base_path` to `snapshots/-` when it is not provided, for Azure, GCS and S3 repositories +* appends `-` to `location` for a FS repository +* appends `-` to `path` for an HDFS repository + + +## Specifics for secret mounts [k8s-stack-config-policy-specifics-secret-mounts] + +ECK `2.11.0` introduces `spec.elasticsearch.secretMounts` as a new field. This field allows users to specify a user created secret and a mountPath to indicate where this secret should be mounted in the Elasticsearch Pods that are managed by the Elastic Stack configuration policy. This field can be used to add additional secrets to the Elasticsearch Pods that may be needed for example for sensitive files required to configure Elasticsearch security realms. The secret should be created by the user in the same namespace as the Elastic Stack configuration policy. The operator reads this secret and copies it over to the namespace of Elasticsearch so that it can be mounted by the Elasticsearch Pods. Example of configuring secret mounts in the Elastic Stack configuration policy: + +```yaml +secretMounts: + - secretName: jwks-secret <1> + mountPath: "/usr/share/elasticsearch/config/jwks" <2> +``` + +1. name of the secret created by the user in the Elastic Stack configuration policy namespace. +2. mount path where the secret must be mounted to inside the Elasticsearch Pod. + + + +## Configuring authentication policies using Elastic Stack configuration policy [k8s-stack-config-policy-configuring-authentication-policies] + +Elastic Stack configuration policy can be used to configure authentication for Elasticsearch clusters. Check [Managing authentication for multiple stacks using Elastic Stack configuration policy](../../users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md) for some examples of the various authentication configurations that can be used. diff --git a/deploy-manage/deploy/cloud-on-k8s/elasticsearch-configuration.md b/deploy-manage/deploy/cloud-on-k8s/elasticsearch-configuration.md new file mode 100644 index 000000000..de7f0dbdb --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/elasticsearch-configuration.md @@ -0,0 +1,39 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elasticsearch-specification.html +--- + +# Elasticsearch configuration [k8s-elasticsearch-specification] + +Before you deploy and run ECK, take some time to look at the basic and advanced settings available on this page. These settings are related both to Elasticsearch and Kubernetes. + +**Basic settings** + +* [Node configuration](node-configuration.md) +* [Volume claim templates](volume-claim-templates.md) +* [Storage recommendations](storage-recommendations.md) +* [Transport settings](transport-settings.md) + +**Advanced settings** + +::::{note} +Snapshots are essential for recovering Elasticsearch indices in case of accidental deletion or for migrating data between clusters. +:::: + + +* [Virtual memory](virtual-memory.md) +* [Settings managed by ECK](settings-managed-by-eck.md) +* [Secure settings](../../security/secure-settings.md) +* [Custom configuration files and plugins](custom-configuration-files-plugins.md) +* [Init containers for plugin downloads](init-containers-for-plugin-downloads.md) +* [Update strategy](update-strategy.md) +* [Pod disruption budget](pod-disruption-budget.md) +* [Advanced Elasticsearch node scheduling](advanced-elasticsearch-node-scheduling.md) +* [Nodes orchestration](nodes-orchestration.md) +* [Create automated snapshots](../../tools/snapshot-and-restore/cloud-on-k8s.md) +* [Remote clusters](../../remote-clusters/eck-remote-clusters.md) +* [Readiness probe](readiness-probe.md) +* [Pod PreStop hook](pod-prestop-hook.md) +* [Elasticsearch autoscaling](../../autoscaling/deployments-autoscaling-on-eck.md) +* [JVM heap dumps](../../../troubleshoot/deployments/cloud-on-k8s/jvm-heap-dumps.md) +* [Security Context](security-context.md) diff --git a/deploy-manage/deploy/cloud-on-k8s/elasticsearch-deployment-quickstart.md b/deploy-manage/deploy/cloud-on-k8s/elasticsearch-deployment-quickstart.md new file mode 100644 index 000000000..241e58734 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/elasticsearch-deployment-quickstart.md @@ -0,0 +1,140 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-deploy-elasticsearch.html +--- + +# Elasticsearch deployment quickstart [k8s-deploy-elasticsearch] + +To deploy a simple [{es](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html)}] cluster specification, with one {{es}} node: + +```yaml +cat < 9200/TCP 34m +``` + +In order to make requests to the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html): + +1. Get the credentials. + + By default, a user named `elastic` is created with the password stored inside a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/). This default user can be disabled if desired, refer to [Users and roles](../../users-roles/cluster-or-deployment-auth/native.md) for more information. + + ```sh + PASSWORD=$(kubectl get secret quickstart-es-elastic-user -o go-template='{{.data.elastic | base64decode}}') + ``` + +2. Request the [{{es}} root API](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-api-root.html). You can do so from inside the Kubernetes cluster or from your local workstation. For demonstration purposes, certificate verification is disabled using the `-k` curl flag; however, this is not recommended outside of testing purposes. Refer to [Setup your own certificate](tls-certificates.md#k8s-setting-up-your-own-certificate) for more information. + + * From inside the Kubernetes cluster: + + ```sh + curl -u "elastic:$PASSWORD" -k "https://quickstart-es-http:9200" + ``` + + * From your local workstation: + + 1. Use the following command in a separate terminal: + + ```sh + kubectl port-forward service/quickstart-es-http 9200 + ``` + + 2. Request `localhost`: + + ```sh + curl -u "elastic:$PASSWORD" -k "https://localhost:9200" + ``` + + +This completes the quickstart of deploying an {{es}} cluster. We recommend continuing to [Deploy a {{kib}} instance](kibana-instance-quickstart.md) but for more configuration options as needed, navigate to [Running {{es}} on ECK](elasticsearch-configuration.md). diff --git a/deploy-manage/deploy/cloud-on-k8s/enterprise-search.md b/deploy-manage/deploy/cloud-on-k8s/enterprise-search.md new file mode 100644 index 000000000..dcdc00478 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/enterprise-search.md @@ -0,0 +1,16 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-enterprise-search.html +--- + +# Enterprise Search [k8s-enterprise-search] + +This section describes how to deploy, configure and access Enterprise Search with ECK. + +* [Quickstart](quickstart-enterprise-search.md) +* [Configuration](configuration-enterprise-search.md) +* [Troubleshooting](troubleshooting-enterprise-search.md) + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/fleet-managed-elastic-agent.md b/deploy-manage/deploy/cloud-on-k8s/fleet-managed-elastic-agent.md new file mode 100644 index 000000000..ba34d038e --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/fleet-managed-elastic-agent.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent-fleet.html +--- + +# Fleet-managed Elastic Agent [k8s-elastic-agent-fleet] + +This section describes how to configure and deploy {{agent}} in [{{fleet}}-managed](https://www.elastic.co/guide/en/fleet/current/elastic-agent-installation.html) mode with ECK. Check the [Standalone section](standalone-elastic-agent.md) if you want to run {{agent}} in the [standalone mode](https://www.elastic.co/guide/en/fleet/current/install-standalone-elastic-agent.html). + +* [Quickstart](quickstart-fleet.md) +* [Configuration](configuration-fleet.md) +* [Configuration Examples](configuration-examples-fleet.md) +* [Known Limitations](known-limitations.md) + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/http-configuration.md b/deploy-manage/deploy/cloud-on-k8s/http-configuration.md new file mode 100644 index 000000000..ae08bd4ef --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/http-configuration.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-maps-http-configuration.html +--- + +# HTTP configuration [k8s-maps-http-configuration] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +## Load balancer settings and TLS SANs [k8s-maps-http-publish] + +By default a `ClusterIP` [service](https://kubernetes.io/docs/concepts/services-networking/service/) is created and associated with the Elastic Maps Server deployment. If you want to expose maps externally with a [load balancer](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer), it is recommended to include a custom DNS name or IP in the self-generated certificate. + +Refer to [Reserve static IP and custom domain](tls-certificates.md#k8s-static-ip-custom-domain) for more details. + + +## Provide your own certificate [k8s-maps-http-custom-tls] + +If you want to use your own certificate, the required configuration is identical to Elasticsearch. Check [Custom HTTP certificate](../../security/secure-http-communications.md). + + +## Disable TLS [k8s-maps-http-disable-tls] + +You can disable the generation of the self-signed certificate and hence disable TLS. Check [Disable TLS](tls-certificates.md#k8s-disable-tls). + +### Ingress and Kibana configuration [k8s-maps-ingress] + +To use Elastic Maps Server from your Kibana instances, you need to configure Kibana to fetch maps from your Elastic Maps Server instance by using the [`map.emsUrl`](https://www.elastic.co/guide/en/kibana/current/maps-connect-to-ems.html#elastic-maps-server-kibana) configuration key. The value of this setting needs to be the URL where the Elastic Maps Server instance is reachable from your browser. The certificates presented by Elastic Maps Server need to be trusted by the browser, and the URL must have the same origin as the URL where your Kibana is hosted to avoid cross origin resource issues. Check the [recipe section](https://github.com/elastic/cloud-on-k8s/tree/2.16/config/recipes/) for an example on how to set this up using an Ingress resource. + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/init-containers-for-plugin-downloads.md b/deploy-manage/deploy/cloud-on-k8s/init-containers-for-plugin-downloads.md new file mode 100644 index 000000000..c0fba17fb --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/init-containers-for-plugin-downloads.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-init-containers-plugin-downloads.html +--- + +# Init containers for plugin downloads [k8s-init-containers-plugin-downloads] + +You can install custom plugins before the Elasticsearch container starts with an `initContainer`. For example: + +```yaml +spec: + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + initContainers: + - name: install-plugins + command: + - sh + - -c + - | + bin/elasticsearch-plugin remove --purge analysis-icu + bin/elasticsearch-plugin install --batch analysis-icu +``` + +You can also override the Elasticsearch container image to use your own image with the plugins already installed, as described in [custom images](create-custom-images.md). For more information on both these options, you can check the [Create automated snapshots](../../tools/snapshot-and-restore/cloud-on-k8s.md) section and the Kubernetes documentation on [init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/). + +The init container inherits: + +* The image of the main container image, if one is not explicitly set. +* The volume mounts from the main container unless a volume mount with the same name and mount path is present in the init container definition +* The Pod name and IP address environment variables. + diff --git a/deploy-manage/deploy/cloud-on-k8s/install-using-helm-chart.md b/deploy-manage/deploy/cloud-on-k8s/install-using-helm-chart.md new file mode 100644 index 000000000..bf79932a5 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/install-using-helm-chart.md @@ -0,0 +1,119 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-install-helm.html +--- + +# Install using a Helm chart [k8s-install-helm] + +Starting from ECK 1.3.0, a Helm chart is available to install ECK. It is available from the Elastic Helm repository and can be added to your Helm repository list by running the following command: + +```sh +helm repo add elastic https://helm.elastic.co +helm repo update +``` + +::::{note} +The minimum supported version of Helm is 3.2.0. +:::: + + + +## Cluster-wide (global) installation [k8s-install-helm-global] + +This is the default mode of installation and is equivalent to [installing ECK using the stand-alone YAML manifests](install-using-yaml-manifest-quickstart.md). + +```sh +helm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace +``` + + +## Restricted installation [k8s-install-helm-restricted] + +This mode avoids installing any cluster-scoped resources and restricts the operator to manage only a set of pre-defined namespaces. + +Since CRDs are global resources, they still need to be installed by an administrator. This can be achieved by: + +```sh +helm install elastic-operator-crds elastic/eck-operator-crds +``` + +The operator can be installed by any user who has full access to the set of namespaces they wish to manage. The following example installs the operator to `elastic-system` namespace and configures it to manage only `namespace-a` and `namespace-b`: + +```sh +helm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace \ + --set=installCRDs=false \ + --set=managedNamespaces='{namespace-a, namespace-b}' \ + --set=createClusterScopedResources=false \ + --set=webhook.enabled=false \ + --set=config.validateStorageClass=false +``` + +::::{note} +The `eck-operator` chart contains several pre-defined profiles to help you install the operator in different configurations. These profiles can be found in the root of the chart directory, prefixed with `profile-`. For example, the restricted configuration illustrated in the previous code extract is defined in the `profile-restricted.yaml` file, and can be used as follows: + +```sh +helm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace \ + --values="${CHART_DIR}/profile-restricted.yaml" \ + --set=managedNamespaces='{namespace-a, namespace-b}' +``` + +You can find the profile files in the Helm cache directory or from the [ECK source repository](https://github.com/elastic/cloud-on-k8s/tree/2.16/deploy/eck-operator). + +:::: + + + +## View available configuration options [k8s-install-helm-show-values] + +You can view all configurable values by running the following: + +```sh +helm show values elastic/eck-operator +``` + + +## Migrate an existing installation to Helm [k8s-migrate-to-helm] + +::::{warning} +Migrating an existing installation to Helm is essentially an upgrade operation and any [caveats associated with normal operator upgrades](../../upgrade/orchestrator/upgrade-cloud-on-k8s.md#k8s-beta-to-ga-rolling-restart) are applicable. Check the [upgrade documentation](../../upgrade/orchestrator/upgrade-cloud-on-k8s.md#k8s-ga-upgrade) before proceeding. +:::: + + +You can migrate an existing operator installation to Helm by adding the `meta.helm.sh/release-name`, `meta.helm.sh/release-namespace` annotations and the `app.kubernetes.io/managed-by` label to all the resources you want to be adopted by Helm. You *must* do this for the Elastic Custom Resource Definitions (CRD) because deleting them would trigger the deletion of all deployed Elastic applications as well. All other resources are optional and can be deleted. + +::::{note} +A shell script is available in the [ECK source repository](https://github.com/elastic/cloud-on-k8s/blob/2.16/deploy/helm-migrate.sh) to demonstrate how to migrate from version 1.7.1 to Helm. You can modify it to suit your own environment. +:::: + + +For example, an ECK 1.2.1 installation deployed using the [quickstart guide](https://www.elastic.co/guide/en/cloud-on-k8s/1.2/k8s-quickstart.html) can be migrated to Helm as follows: + +1. Annotate and label all the ECK CRDs with the appropriate Helm annotations and labels. CRDs need to be preserved to retain any existing Elastic applications deployed using the operator. + + ```sh + for CRD in $(kubectl get crds --no-headers -o custom-columns=NAME:.metadata.name | grep k8s.elastic.co); do + kubectl annotate crd "$CRD" meta.helm.sh/release-name="$RELEASE_NAME" + kubectl annotate crd "$CRD" meta.helm.sh/release-namespace="$RELEASE_NAMESPACE" + kubectl label crd "$CRD" app.kubernetes.io/managed-by=Helm + done + ``` + +2. Uninstall the current ECK operator. You can do this by taking the `operator.yaml` file you used to install the operator and running `kubectl delete -f operator.yaml`. Alternatively, you could delete each resource individually. + + ```sh + kubectl delete -n elastic-system \ + serviceaccount/elastic-operator \ + secret/elastic-webhook-server-cert \ + clusterrole.rbac.authorization.k8s.io/elastic-operator \ + clusterrole.rbac.authorization.k8s.io/elastic-operator-view \ + clusterrole.rbac.authorization.k8s.io/elastic-operator-edit \ + clusterrolebinding.rbac.authorization.k8s.io/elastic-operator \ + service/elastic-webhook-server \ + configmap/elastic-operator \ <1> + statefulset.apps/elastic-operator \ + validatingwebhookconfiguration.admissionregistration.k8s.io/elastic-webhook.k8s.elastic.co + ``` + + 1. If you have previously customized the operator configuration in this ConfigMap, you will have to repeat the configuration once the operator has been reinstalled in the next step. + +3. Install the ECK operator using the Helm chart as described in [Install ECK using the Helm chart](). diff --git a/deploy-manage/deploy/cloud-on-k8s/install-using-yaml-manifest-quickstart.md b/deploy-manage/deploy/cloud-on-k8s/install-using-yaml-manifest-quickstart.md new file mode 100644 index 000000000..c0fb74b0b --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/install-using-yaml-manifest-quickstart.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-install-yaml-manifests.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-deploy-eck.html +--- + +# Install using YAML manifest (quickstart) + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/357 + +% Scope notes: Work with the quickstart and the small "yaml manifest installation" doc to create a single doc. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-install-yaml-manifests.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-deploy-eck.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/install.md b/deploy-manage/deploy/cloud-on-k8s/install.md new file mode 100644 index 000000000..54412c726 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/install.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-installing-eck.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-supported.html +--- + +# Install + +% What needs to be done: Lift-and-shift + +% Scope notes: Entry point, i think the current page is valid. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-installing-eck.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-supported.md \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-autopilot-deploy-agent-beats.md b/deploy-manage/deploy/cloud-on-k8s/k8s-autopilot-deploy-agent-beats.md new file mode 100644 index 000000000..63dcf74e1 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-autopilot-deploy-agent-beats.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-autopilot-deploy-agent-beats.html +--- + +# Deploy a standalone Elastic Agent and/or Beats [k8s-autopilot-deploy-agent-beats] + +When running Elastic Agent and Beats within GKE Autopilot there are storage constraints to be considered. No `HostPath` volumes are allowed, which the ECK operator defaults to when unset for both `Deployments` and `Daemonsets`. Instead use [Kubernetes ephemeral volumes](https://kubernetes.io/docs/concepts/storage/ephemeral-volumes). + +Refer to [Recipes to deploy Elasticsearch, Kibana, Elastic Fleet Server and Elastic Agent and/or Beats within GKE Autopilot](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/autopilot). + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-autopilot-deploy-elasticsearch.md b/deploy-manage/deploy/cloud-on-k8s/k8s-autopilot-deploy-elasticsearch.md new file mode 100644 index 000000000..0ca5a527b --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-autopilot-deploy-elasticsearch.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-autopilot-deploy-elasticsearch.html +--- + +# Deploy an Elasticsearch instance [k8s-autopilot-deploy-elasticsearch] + +Create an Elasticsearch cluster. If you are using the `Daemonset` described in the [Virtual memory](virtual-memory.md) section to set `max_map_count` you can add the `initContainer` below is also used to ensure the setting is set prior to starting Elasticsearch. + +```shell +cat <[-].) + tls: + termination: passthrough # the APM Server is the TLS endpoint + insecureEdgeTerminationPolicy: Redirect + to: + kind: Service + name: apm-server-sample-apm-http + EOF + ``` + + To check that the Pod of the APM Server is using the correct SCC, use the following command: + + ```shell + oc get pod -o go-template='{{range .items}}{{$scc := index .metadata.annotations "openshift.io/scc"}}{{.metadata.name}}{{" scc:"}}{{range .spec.containers}}{{$scc}}{{" "}}{{"\n"}}{{end}}{{end}}' + ``` + + ```shell + apm-server-sample-apm-server-86bfc5c95c-96lbx scc:anyuid + elasticsearch-sample-es-5tsqghmm79 scc:restricted + elasticsearch-sample-es-6qk52mz5jk scc:restricted + elasticsearch-sample-es-dg4vvpm2mr scc:restricted + kibana-sample-kb-97c6b6b8d-lqfd2 scc:restricted + ``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-beats.md b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-beats.md new file mode 100644 index 000000000..25e6be76a --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-beats.md @@ -0,0 +1,104 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-openshift-beats.html +--- + +# Grant privileged permissions to Beats [k8s-openshift-beats] + +Deploying Beats on Openshift may require some privileged permissions. This section describes how to create a ServiceAccount, add the ServiceAccount to the `privileged` SCC, and use it to run Beats. + +The following example assumes that Beats is deployed in the Namespace `elastic` with the ServiceAccount `heartbeat`. You can replace these values according to your environment. + +::::{note} +If you used the examples from the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/2.16/config/recipes/beats), the ServiceAccount may already exist. +:::: + + +1. Create a dedicated ServiceAccount: + + ```shell + oc create serviceaccount heartbeat -n elastic + ``` + +2. Add the ServiceAccount to the required SCC: + + ```shell + oc adm policy add-scc-to-user privileged -z heartbeat -n elastic + ``` + +3. Update the Beat manifest to use the new ServiceAccount, for example: + + ```yaml + apiVersion: beat.k8s.elastic.co/v1beta1 + kind: Beat + metadata: + name: heartbeat + spec: + type: heartbeat + version: 8.16.1 + elasticsearchRef: + name: elasticsearch + config: + heartbeat.monitors: + - type: tcp + schedule: '@every 5s' + hosts: ["elasticsearch-es-http.default.svc:9200"] + - type: tcp + schedule: '@every 5s' + hosts: ["kibana-kb-http.default.svc:5601"] + deployment: + replicas: 1 + podTemplate: + spec: + serviceAccountName: heartbeat + securityContext: + runAsUser: 0 + ``` + + +If SELinux is enabled, the Beat Pod might fail with the following message: + +```shell +Exiting: Failed to create Beat meta file: open /usr/share/heartbeat/data/meta.json.new: permission denied +``` + +To fix this error, apply the label `svirt_sandbox_file_t` to the directory `/var/lib/elastic/heartbeat/heartbeat-data/` on the Kubernetes node: + +```shell +chcon -Rt svirt_sandbox_file_t /var/lib/elastic/heartbeat/heartbeat-data/ +``` + +Repeat this step on all the hosts where the heartbeat Pod can be deployed. + +Some Beats may require additional permissions. For example, `Filebeat` needs additional privileges to read other container logs on the host. In this case, you can use the `privileged` field in the security context of the container spec: + +```yaml +apiVersion: beat.k8s.elastic.co/v1beta1 +kind: Beat +metadata: + name: filebeat +spec: + type: filebeat +... + daemonSet: + podTemplate: + spec: + serviceAccountName: filebeat + automountServiceAccountToken: true +... + containers: + - name: filebeat + securityContext: + runAsUser: 0 + privileged: true # This is required to access other containers logs + volumeMounts: + - name: varlibdockercontainers + mountPath: /var/lib/docker/containers + volumes: + - name: varlibdockercontainers + hostPath: + path: /var/lib/docker/containers +``` + +Check the complete examples in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/2.16/config/recipes/beats). + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-elasticsearch.md b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-elasticsearch.md new file mode 100644 index 000000000..85f25ed65 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-elasticsearch.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-openshift-deploy-elasticsearch.html +--- + +# Deploy an Elasticsearch instance with a route [k8s-openshift-deploy-elasticsearch] + +Use the following code to create an Elasticsearch cluster `elasticsearch-sample` and a "passthrough" route to access it: + +::::{note} +A namespace other than the default namespaces (default, kube-system, kube-**, openshift-**, etc) is required such that default [Security Context Constraint](https://docs.openshift.com/container-platform/4.12/authentication/managing-security-context-constraints.md) (SCC) permissions are applied automatically. Elastic resources will not work properly in any of the default namespaces. +:::: + + +```shell +cat <[-].) + tls: + termination: passthrough # Elasticsearch is the TLS endpoint + insecureEdgeTerminationPolicy: Redirect + to: + kind: Service + name: elasticsearch-sample-es-http +EOF +``` + +## Elasticsearch plugins [k8s-openshift-es-plugins] + +Elasticsearch plugins cannot be installed at runtime in most OpenShift environments. This is because the plugin installer must run as root, but Elasticsearch is restricted from running as root. To add plugins to Elasticsearch, you can use custom images as described in [*Create custom images*](create-custom-images.md). + + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-kibana.md b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-kibana.md new file mode 100644 index 000000000..ee112a0b3 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-kibana.md @@ -0,0 +1,50 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-openshift-deploy-kibana.html +--- + +# Deploy a Kibana instance with a route [k8s-openshift-deploy-kibana] + +Use the following code to create a Kibana instance and a "passthrough" route to access it: + +```shell +cat <[-].) + tls: + termination: passthrough # Kibana is the TLS endpoint + insecureEdgeTerminationPolicy: Redirect + to: + kind: Service + name: kibana-sample-kb-http +EOF +``` + +Use the following command to get the hosts of each `Route`: + +```shell +oc get route -n elastic +``` + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-operator.md b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-operator.md new file mode 100644 index 000000000..026c7fdb6 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-openshift-deploy-operator.md @@ -0,0 +1,40 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-openshift-deploy-the-operator.html +--- + +# Deploy the operator [k8s-openshift-deploy-the-operator] + +1. Apply the all-in-one template, as described in the [quickstart](deploy-an-orchestrator.md). + + ```shell + oc create -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml + oc apply -f https://download.elastic.co/downloads/eck/2.16.1/operator.yaml + ``` + +2. [Optional] If the Software Defined Network is configured with the `ovs-multitenant` plug-in, you must allow the `elastic-system` namespace to access other Pods and Services in the cluster: + + ```shell + oc adm pod-network make-projects-global elastic-system + ``` + +3. Create a namespace to hold the Elastic resources (Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash): + + ::::{note} + A namespace other than the default namespaces (default, kube-**, openshift-**, etc) is required such that default [Security Context Constraint](https://docs.openshift.com/container-platform/4.12/authentication/managing-security-context-constraints.md) (SCC) permissions are applied automatically. Elastic resources will not work properly in any of the default namespaces. + :::: + + +```shell +oc new-project elastic # creates the elastic project +``` + +1. [Optional] Allow another user or a group of users to manage the Elastic resources: + + ```shell + oc adm policy add-role-to-user elastic-operator developer -n elastic + ``` + + In this example the user `developer` is allowed to manage Elastic resources in the namespace `elastic`. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-istio.md b/deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-istio.md new file mode 100644 index 000000000..870171d4a --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-istio.md @@ -0,0 +1,221 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-service-mesh-istio.html +--- + +# Istio [k8s-service-mesh-istio] + +The instructions in this section describe how to connect the operator and managed resources to the Istio service mesh and assume that Istio is already installed and configured on your Kubernetes cluster. To know more about Istio and how to install it, check the [product documentation](https://istio.io). + +These instructions have been tested with Istio 1.6.1. Older or newer versions of Istio might require additional configuration steps not documented here. + +::::{warning} +Some Elastic Stack features such as [Kibana alerting and actions](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html#alerting-getting-started) rely on the Elasticsearch API keys feature which requires TLS to be enabled at the application level. If you want to use these features, you should not disable the self-signed certificate on the Elasticsearch resource and enable `PERMISSIVE` mode for the Elasticsearch service through a `DestinationRule` or `PeerAuthentication` resource. Strict mTLS mode is currently not compatible with Elastic Stack features requiring TLS to be enabled for the Elasticsearch HTTP layer. +:::: + + +::::{important} +If you use a Kubernetes distribution like Minikube, which does not have support for issuing third-party security tokens, you should explicitly set `automountServiceAccountToken` field to `true` in the Pod templates to allow Istio to fallback to default service account tokens. Refer to [Istio security best practices](https://istio.io/docs/ops/best-practices/security/#configure-third-party-service-account-tokens) for more information. +:::: + + +## Connect the operator to the Istio service mesh [k8s-service-mesh-istio-operator-connection] + +The operator itself must be connected to the service mesh to deploy and manage Elastic Stack resources that you wish to connect to the service mesh. This is achieved by injecting an Istio sidecar to the ECK operator Pods. The following instructions assume that [automatic sidecar injection](https://istio.io/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) is enabled on your cluster through a mutating admissions webhook. Refer to [Istio injection documentation](https://istio.io/docs/setup/additional-setup/sidecar-injection/#injection) if you prefer a different method of injection. + +1. Create the `elastic-system` namespace and enable sidecar injection: + + ```sh + kubectl create namespace elastic-system + kubectl label namespace elastic-system istio-injection=enabled + ``` + +2. Install ECK: + + ```sh + kubectl create -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml + kubectl apply -f https://download.elastic.co/downloads/eck/2.16.1/operator.yaml + ``` + +3. Check the configuration and make sure the installation has been successful: + + ```sh + kubectl get pod elastic-operator-0 -n elastic-system -o=jsonpath='{range .spec.containers[*]}{.name}{"\n"}' + ``` + + +If the output of the above command contains both `manager` and `istio-proxy`, ECK was successfully installed with the Istio sidecar injected. + +To make the [validating webhook](configure-validating-webhook.md) work under Istio, you need to exclude the inbound port 9443 from being proxied. This can be done by editing the template definition of the `elastic-operator` StatefulSet to add the following annotations to the operator Pod: + +```yaml +[...] +spec: + template: + metadata: + annotations: + traffic.sidecar.istio.io/excludeInboundPorts: "9443" + traffic.sidecar.istio.io/includeInboundPorts: '*' +[...] +``` + +As the default `failurePolicy` of the webhook is `Ignore`, the operator continues to function even if the above annotations are not present. The downside is that you are still able to submit an invalid manifest using `kubectl` without receiving any immediate feedback. + +ECK has a fallback validation mechanism that reports validation failures as events associated with the relevant resource (Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash) that must be manually discovered by running `kubectl describe`. For example, to find the validation errors in an Elasticsearch resource named `quickstart`, you can run `kubectl describe elasticsearch quickstart`. + + +## Connect Elastic Stack applications to the Istio service mesh [k8s-service-mesh-istio-stack-connection] + +This section assumes that you are deploying ECK custom resources to a namespace that has [automatic sidecar injection](https://istio.io/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) enabled. + +If you have configured Istio in [permissive mode](https://istio.io/docs/concepts/security/#permissive-mode), examples defined elsewhere in the ECK documentation will continue to work without requiring any modifications. However, if you have enabled strict mutual TLS authentication between services either through global (`MeshPolicy`) or namespace-level (`Policy`) configuration, the following modifications to the resource manifests are necessary for correct operation. + +### Elasticsearch [k8s-service-mesh-istio-elasticsearch] + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elastic-istio +spec: + version: 8.16.1 + http: + tls: <1> + selfSignedCertificate: + disabled: true + nodeSets: + - name: default + count: 3 + podTemplate: + metadata: + annotations: + traffic.sidecar.istio.io/includeInboundPorts: "*" + traffic.sidecar.istio.io/excludeOutboundPorts: "9300" <2> + traffic.sidecar.istio.io/excludeInboundPorts: "9300" + spec: + automountServiceAccountToken: true <3> +``` + +1. Disable the default self-signed certificate generated by the operator and allow TLS to be managed by Istio. Disabling the self-signed certificate might interfere with some features such as Kibana Alerting and Actions. +2. Exclude the transport port (port 9300) from being proxied. Currently ECK does not support switching off X-Pack security and TLS for the Elasticsearch transport port. If Istio is allowed to proxy the transport port, the traffic is encrypted twice and communication between Elasticsearch nodes is disrupted. +3. Optional. Only set `automountServiceAccountToken` to `true` if your Kubernetes cluster does not have support for issuing third-party security tokens. + + +If you do not have [automatic mutual TLS](https://istio.io/latest/docs/tasks/security/authentication/mtls-migration/) enabled, you may need to create a [Destination Rule](https://istio.io/docs/reference/config/networking/destination-rule/) to allow the operator to communicate with the Elasticsearch cluster. A communication issue between the operator and the managed Elasticsearch cluster can be detected by looking at the operator logs to check if there are any errors reported with the text `503 Service Unavailable`. + +```sh +kubectl logs -f -n elastic-system -c manager statefulset.apps/elastic-operator +``` + +If the operator logs indicate a communications problem, create a `DestinationRule` to enable mutual TLS between the operator and the affected Elasticsearch cluster. For example, the following rule enables mutual TLS for a specific Elasticsearch cluster named `elastic-istio` deployed to the `default` namespace. + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: DestinationRule +metadata: + name: elastic-istio +spec: + host: "elastic-istio-es-http.default.svc.cluster.local" + trafficPolicy: + tls: + mode: ISTIO_MUTUAL +``` + +Refer to the [Istio documentation](https://istio.io/docs/tasks/security/authentication/mtls-migration/) for more information about other configuration options affecting authentication between services. + +#### Using init containers with Istio CNI [k8s-service-mesh-istio-cni] + +There are [known issues with init containers](https://istio.io/docs/setup/additional-setup/cni/#compatibility-with-application-init-containers) when Istio CNI is configured. If you use init containers to [install Elasticsearch plugins](init-containers-for-plugin-downloads.md) or perform other initialization tasks that require network access, they may fail due to outbound traffic being blocked by the CNI plugin. To work around this issue, explicitly allow the external ports used by the init containers. + +To install plugins using an init container, use a manifest similar to the following: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elastic-istio +spec: + version: 8.16.1 + http: + tls: + selfSignedCertificate: + disabled: true + nodeSets: + - name: default + count: 3 + podTemplate: + metadata: + annotations: + traffic.sidecar.istio.io/includeInboundPorts: "*" + traffic.sidecar.istio.io/excludeOutboundPorts: "9300,443" <1> + traffic.sidecar.istio.io/excludeInboundPorts: "9300" + spec: + automountServiceAccountToken: true + initContainers: + - name: install-plugins + command: + - sh + - -c + - | + bin/elasticsearch-plugin remove --purge analysis-icu + bin/elasticsearch-plugin install --batch analysis-icu +``` + +1. Plugins are downloaded over the HTTPS port (443) and needs to be allowed when Istio CNI is installed. + + + + +### Kibana [k8s-service-mesh-istio-kibana] + +```yaml +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: elastic-istio +spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: elastic-istio + http: + tls: <1> + selfSignedCertificate: + disabled: true + podTemplate: + spec: + automountServiceAccountToken: true <2> +``` + +1. Disable the default self-signed certificate generated by the operator and allow TLS to be managed by Istio. +2. Optional. Only set `automountServiceAccountToken` to `true` if your Kubernetes cluster does not have support for issuing third-party security tokens. + + + +### APM Server [k8s-service-mesh-istio-apm] + +```yaml +apiVersion: apm.k8s.elastic.co/v1 +kind: ApmServer +metadata: + name: elastic-istio +spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: elastic-istio + http: + tls: <1> + selfSignedCertificate: + disabled: true + podTemplate: + metadata: + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" <2> + spec: + automountServiceAccountToken: true <3> +``` + +1. Disable the default self-signed certificate generated by the operator and allow TLS to be managed by Istio. +2. Automatically re-write the health checks to go through the proxy. +3. Optional. Only set `automountServiceAccountToken` to `true` if your Kubernetes cluster does not have support for issuing third-party security tokens. diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-linkerd.md b/deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-linkerd.md new file mode 100644 index 000000000..28fcdabbb --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-linkerd.md @@ -0,0 +1,118 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-service-mesh-linkerd.html +--- + +# Linkerd [k8s-service-mesh-linkerd] + +The following sections describe how to connect the operator and managed resources to the Linkerd service mesh. It is assumed that Linkerd is already installed and configured on your Kubernetes cluster. If you are new to Linkerd, refer to the [product documentation](https://linkerd.io) for more information and installation instructions. + +::::{note} +These instructions have been tested with Linkerd 2.7.0. +:::: + + +## Connect the operator to the Linkerd service mesh [k8s-service-mesh-linkerd-operator-connection] + +In order to connect the operator to the service mesh, Linkerd sidecar must be injected into the ECK deployment. This can be done during installation as follows: + +```sh +kubectl create -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml +linkerd inject https://download.elastic.co/downloads/eck/2.16.1/operator.yaml | kubectl apply -f - +``` + +Confirm that the operator is now meshed: + +```sh +linkerd stat sts/elastic-operator -n elastic-system +``` + +If the installation was successful, the output of the above command should show `1/1` under the `MESHED` column. + + +## Connect Elastic Stack applications to the Linkerd service mesh [k8s-service-mesh-linkerd-stack-connection] + +The easiest way to connect applications to the service mesh is by adding the `linkerd.io/inject: enabled` annotation to the deployment namespace. For example, if you are planning to deploy Elastic Stack applications to a namespace named `elastic-stack`, annotate it as follows to enable [automatic Linkerd sidecar injection](https://linkerd.io/2/features/proxy-injection/). + +```sh +kubectl annotate namespace elastic-stack linkerd.io/inject=enabled +``` + +Any Elasticsearch, Kibana, or APM Server resources deployed to a namespace with the above annotation will automatically join the mesh. + +Alternatively, if you only want specific resources to join the mesh, add the `linkerd.io/inject: enabled` annotation to the `podTemplate` (check [API documentation](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-api-reference.html)) of the resource as follows: + +```yaml +podTemplate: + metadata: + annotations: + linkerd.io/inject: enabled +``` + +If automatic sidecar injection is enabled and [auto mounting of service account tokens](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#use-the-default-service-account-to-access-the-api-server) is not disabled on your Kubernetes cluster, examples defined elsewhere in the ECK documentation will continue to work under Linkerd without requiring any modifications. However, as the default behaviour of ECK is to enable TLS for Elasticsearch, Kibana and APM Server resources, you will not be able to view detailed traffic information from Linkerd dashboards and command-line utilities. The following sections illustrate the optional configuration necessary to enhance the integration of Elastic Stack applications with Linkerd. + +### Elasticsearch [k8s-service-mesh-linkerd-elasticsearch] + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elastic-linkerd +spec: + version: 8.16.1 + http: + tls: <1> + selfSignedCertificate: + disabled: true + nodeSets: + - name: default + count: 3 + config: + node.store.allow_mmap: false + podTemplate: + metadata: + annotations: + linkerd.io/inject: enabled <2> + spec: + automountServiceAccountToken: true <3> +``` + +1. Disable automatic TLS to allow Linkerd to gather more statistics about connections (optional). +2. Explicitly enable sidecar injection (optional if the namespace is already annotated). +3. Enable service account token mounting to provide service identity (only required to enable mTLS if service account auto-mounting is disabled). + + + +### Kibana and APM Server [k8s-service-mesh-linkerd-kibana-apm] + +The configuration is almost identical for Kibana and APM Server resources. + +```yaml +apiVersion: ... +kind: ... +metadata: + name: elastic-linkerd +spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: elastic-linkerd + http: + tls: <1> + selfSignedCertificate: + disabled: true + podTemplate: + metadata: + annotations: + linkerd.io/inject: enabled <2> + spec: + automountServiceAccountToken: true <3> +``` + +1. Disable automatic TLS to allow Linkerd to gather more statistics about connections (optional). +2. Explicitly enable sidecar injection (optional if the namespace is already annotated). +3. Enable service account token mounting to provide service identity (only required to enable mTLS if service account auto-mounting is disabled). + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/k8s_prerequisites.md b/deploy-manage/deploy/cloud-on-k8s/k8s_prerequisites.md new file mode 100644 index 000000000..3521f49c1 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/k8s_prerequisites.md @@ -0,0 +1,460 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_prerequisites.html +--- + +# Prerequisites [k8s_prerequisites] + +To set up the network policies correctly you must know the operator Pod selector and the Kubernetes API server IP. They may vary depending on your environment and how the operator has been installed. + +## Operator Pod selector [k8s_operator_pod_selector] + +The operator Pod label depends on how the operator has been installed. Check the following table to know which label name is used in the network policies. + +| Installation method | Pod selector | +| --- | --- | +| YAML manifests | `control-plane: elastic-operator`
| +| Helm Charts | `app.kubernetes.io/name: elastic-operator`
| + +::::{note} +The examples in this section assume that the ECK operator has been installed using the Helm chart. +:::: + + + +## Kubernetes API server IP [k8s_kubernetes_api_server_ip] + +Run `kubectl get endpoints kubernetes -n default` to obtain the API server IP address for your cluster. + +::::{note} +The following examples assume that the Kubernetes API server IP address is `10.0.0.1`. +:::: + + + +## Isolating the operator [k8s-network-policies-operator-isolation] + +The minimal set of permissions required are as follows: + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 443 of the Kubernetes API server.
* UDP port 53 for DNS lookup.
* TCP port 9200 of {{es}} nodes on managed namespace.
| +| Ingress (incoming) | * TCP port 9443 for webhook requests from the Kubernetes API server.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: elastic-operator + namespace: elastic-system +spec: + egress: + - ports: + - port: 53 + protocol: UDP + - ports: + - port: 443 + protocol: TCP + to: + - ipBlock: + cidr: 10.0.0.1/32 + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchExpressions: + - key: eck.k8s.elastic.co/tenant + operator: In + values: + - team-a + - team-b + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + ingress: + - from: + - ipBlock: + cidr: 10.0.0.1/32 + ports: + - port: 9443 + protocol: TCP + podSelector: + matchLabels: + app.kubernetes.io/name: elastic-operator +``` + + +## Isolating {{es}} [k8s-network-policies-elasticsearch-isolation] + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9300 to other {{es}} nodes in the namespace (transport port).
* UDP port 53 for DNS lookup.
| +| Ingress (incoming) | * TCP port 9200 from the operator and other pods in the namespace.
* TCP port 9300 from other {{es}} nodes in the namespace (transport port).
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-elasticsearch + namespace: team-a +spec: + egress: + - ports: + - port: 9300 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + - ports: + - port: 53 + protocol: UDP + ingress: + - from: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/operator-name: elastic-operator + podSelector: + matchLabels: + app.kubernetes.io/name: elastic-operator + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + # [Optional] Allow ingress controller pods from the ingress-nginx namespace. + #- namespaceSelector: + # matchLabels: + # name: ingress-nginx + ports: + - port: 9200 + protocol: TCP + - from: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + ports: + - port: 9300 + protocol: TCP + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch +``` + + +## Isolating {{kib}} [k8s-network-policies-kibana-isolation] + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9200 to {{es}} nodes in the namespace.
* UDP port 53 for DNS lookup.
| +| Ingress (incoming) | * TCP port 5601 from other pods in the namespace.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-kibana + namespace: team-a +spec: + egress: + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + # [Optional] Restrict to a single {es} cluster named hulk. + # elasticsearch.k8s.elastic.co/cluster-name=hulk + - ports: + - port: 53 + protocol: UDP + # [Optional] If Agent is deployed, this is to allow Kibana to access the Elastic Package Registry (https://epr.elastic.co). + # - port: 443 + # protocol: TCP + ingress: + - from: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + # [Optional] Allow ingress controller pods from the ingress-nginx namespace. + #- namespaceSelector: + # matchLabels: + # name: ingress-nginx + ports: + - port: 5601 + protocol: TCP + podSelector: + matchLabels: + common.k8s.elastic.co/type: kibana +``` + + +## Isolating APM Server [k8s-network-policies-apm-server-isolation] + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9200 to {{es}} nodes in the namespace.
* TCP port 5601 to {{kib}} instances in the namespace.
* UDP port 53 for DNS lookup.
| +| Ingress (incoming) | * TCP port 8200 from other pods in the namespace.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-apm-server + namespace: team-a +spec: + egress: + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + - ports: + - port: 5601 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: kibana + - ports: + - port: 53 + protocol: UDP + ingress: + - from: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + # [Optional] Allow ingress controller pods from the ingress-nginx namespace. + #- namespaceSelector: + # matchLabels: + # name: ingress-nginx + ports: + - port: 8200 + protocol: TCP + podSelector: + matchLabels: + common.k8s.elastic.co/type: apm-server +``` + + +## Isolating Enterprise Search [k8s-network-policies-enterprise-search-isolation] + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9200 to {{es}} nodes in the namespace.
* UDP port 53 for DNS lookup.
| +| Ingress (incoming) | * TCP port 3002 from other pods in the namespace.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-enterprise-search + namespace: team-a +spec: + egress: + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + - ports: + - port: 53 + protocol: UDP + ingress: + - from: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + # [Optional] Allow ingress controller pods from the ingress-nginx namespace. + #- namespaceSelector: + # matchLabels: + # name: ingress-nginx + ports: + - port: 3002 + protocol: TCP + podSelector: + matchLabels: + common.k8s.elastic.co/type: enterprise-search +``` + + +## Isolating {{beats}} [k8s-network-policies-beats-isolation] + +::::{note} +Some {{beats}} may require additional access rules than what is listed here. For example, {{heartbeat}} will require a rule to allow access to the endpoint it is monitoring. +:::: + + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9200 to {{es}} nodes in the namespace.
* TCP port 5601 to {{kib}} instances in the namespace.
* UDP port 53 for DNS lookup.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-beats + namespace: team-a +spec: + egress: + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + - ports: + - port: 5601 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: kibana + - ports: + - port: 53 + protocol: UDP + podSelector: + matchLabels: + common.k8s.elastic.co/type: beat +``` + + +## Isolating {{agent}} and {{fleet}} [k8s-network-policies-agent-isolation] + +::::{note} +Some {{agent}} policies may require additional access rules other than those listed here. +:::: + + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9200 to {{es}} nodes in the namespace.
* TCP port 5601 to {{kib}} instances in the namespace.
* TCP port 8220 to {{fleet}} instances in the namespace.
* UDP port 53 for DNS lookup.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-agent + namespace: team-a +spec: + egress: + - ports: + - port: 8220 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: agent + - ports: + - port: 5601 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: kibana + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + - ports: + - port: 53 + protocol: UDP + - ports: + - port: 443 + protocol: TCP + to: + - ipBlock: + cidr: 10.0.0.1/32 + ingress: + - from: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + ports: + - port: 8220 + protocol: TCP + podSelector: + matchLabels: + common.k8s.elastic.co/type: agent +``` + + +## Isolating {{ls}} [k8s-network-policies-logstash-isolation] + +::::{note} +{{ls}} may require additional access rules than those listed here, depending on plugin usage. +:::: + + +| | | +| --- | --- | +| Egress (outgoing) | * TCP port 9200 to {{es}} nodes in the namespace.
* UDP port 53 for DNS lookup.
| + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: eck-logstash + namespace: team-a +spec: + egress: + - ports: + - port: 9200 + protocol: TCP + to: + - namespaceSelector: + matchLabels: + eck.k8s.elastic.co/tenant: team-a + podSelector: + matchLabels: + common.k8s.elastic.co/type: elasticsearch + - ports: + - port: 53 + protocol: UDP + podSelector: + matchLabels: + common.k8s.elastic.co/type: logstash +``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/kibana-configuration.md b/deploy-manage/deploy/cloud-on-k8s/kibana-configuration.md new file mode 100644 index 000000000..af59b323a --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/kibana-configuration.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-kibana.html +--- + +# Kibana configuration [k8s-kibana] + +The [quickstart](kibana-instance-quickstart.md) is a good starting point to quickly setup a {{kib}} instance with ECK. The following sections describe how to customize a {{kib}} deployment to suit your requirements. + +* [Connect to an {{es}} cluster](k8s-kibana-es.md) + + * [Connect to an {{es}} cluster managed by ECK](k8s-kibana-es.md#k8s-kibana-eck-managed-es) + * [Connect to an {{es}} cluster not managed by ECK](k8s-kibana-es.md#k8s-kibana-external-es) + +* [Advanced configuration](k8s-kibana-advanced-configuration.md) + + * [Pod Configuration](k8s-kibana-advanced-configuration.md#k8s-kibana-pod-configuration) + * [{{kib}} Configuration](k8s-kibana-advanced-configuration.md#k8s-kibana-configuration) + * [Scaling out a {{kib}} deployment](k8s-kibana-advanced-configuration.md#k8s-kibana-scaling) + +* [Secure settings](k8s-kibana-secure-settings.md) +* [HTTP Configuration](k8s-kibana-http-configuration.md) + + * [Load balancer settings and TLS SANs](k8s-kibana-http-configuration.md#k8s-kibana-http-publish) + * [Provide your own certificate](k8s-kibana-http-configuration.md#k8s-kibana-http-custom-tls) + * [Disable TLS](k8s-kibana-http-configuration.md#k8s-kibana-http-disable-tls) + * [Install {{kib}} plugins](k8s-kibana-plugins.md) + + + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/kibana-instance-quickstart.md b/deploy-manage/deploy/cloud-on-k8s/kibana-instance-quickstart.md new file mode 100644 index 000000000..795f2c115 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/kibana-instance-quickstart.md @@ -0,0 +1,72 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-deploy-kibana.html +--- + +# Kibana instance quickstart [k8s-deploy-kibana] + +To deploy a simple [{{kib}}](https://www.elastic.co/guide/en/kibana/current/introduction.html#introduction) specification, with one {{kib}} instance: + +1. Specify a {{kib}} instance and associate it with your {{es}} `quickstart` cluster created previously under [Deploying an {{es}} cluster](elasticsearch-deployment-quickstart.md): + + ```yaml + cat < 8443 + ssl_certificate => "/usr/share/logstash/data/logstash.crt" + ssl_key => "/usr/share/logstash/data/logstash.key" + } + } +``` + +**Static read-only files** + +Some plugins require or allow access to small static read-only files. You can use these for a variety of reasons. Examples include adding custom `grok` patterns for [`logstash-filter-grok`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-grok.html) to use for lookup, source code for [`logstash-filter-ruby`], a dictionary for [`logstash-filter-translate`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-translate.html) or the location of a SQL statement for [`logstash-input-jdbc`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-jdbc.html). Make these files available to the {{ls}} resource in your manifest. + +::::{tip} +In the plugin documentation, these plugin settings are typically identified by `path` or an `array` of `paths`. +:::: + + +To use these in your manifest, create a ConfigMap or Secret representing the asset, a Volume in your `podTemplate.spec` containing the ConfigMap or Secret, and mount that Volume with a VolumeMount in your `podTemplateSpec.container` section of your {{ls}} resource. + +This example illustrates configuring a ConfigMap from a ruby source file, and including it in a [`logstash-filter-ruby`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-ruby.html) plugin. + +First, create the ConfigMap. + +```bash +kubectl create configmap ruby --from-file=drop_some.rb +``` + +Then, create your Logstash resource. + +```yaml +spec: + podTemplate: + spec: + volumes: + - name: ruby_drop + configMap: + name: ruby + containers: + - name: logstash + volumeMounts: + - name: ruby_drop + mountPath: "/usr/share/logstash/data/drop_percentage.rb" + readOnly: true + pipelines: + - pipeline.id: main + config.string: | + input { + beats { + port => 5044 + } + } + filter { + ruby { + path => "/usr/share/logstash/data/drop_percentage.rb" + script_params => { "percentage" => 0.9 } + } + } +``` + + + +### Larger read-only assets (1 MiB+) [k8s-logstash-working-with-plugins-large-ro] + +Some plugins require or allow access to static read-only files that exceed the 1 MiB (mebibyte) limit imposed by ConfigMap and Secret. For example, you may need JAR files to load drivers when using a JDBC or JMS plugin, or a large [`logstash-filter-translate`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-translate.html) dictionary. + +You can add files using: + +* **[PersistentVolume populated by an initContainer](#k8s-logstash-ic).** Add a volumeClaimTemplate and a volumeMount to your {{ls}} resource and upload data to that volume, either using an `initContainer`, or direct upload if your Kubernetes provider supports it. You can use the default `logstash-data` volumeClaimTemplate , or a custom one depending on your storage needs. +* **[Custom Docker image](#k8s-logstash-custom-images).** Use a custom docker image that includes the static content that your Logstash pods will need. + +Check out [Custom configuration files and plugins](custom-configuration-files-plugins.md) for more details on which option might be most suitable for you. + +#### Add files using PersistentVolume populated by an initContainer [k8s-logstash-ic] + +This example creates a volumeClaimTemplate called `workdir`, with volumeMounts referring to this mounted to the main container and an initContainer. The initContainer initiates a download of a PostgreSQL JDBC driver JAR file, and stored it the volumeMount, which is then used in the JDBC input in the pipeline configuration. + +```yaml +spec: + podTemplate: + spec: + initContainers: + - name: download-postgres + command: ["/bin/sh"] + args: ["-c", "curl -o /data/postgresql.jar -L https://jdbc.postgresql.org/download/postgresql-42.6.0.jar"] + volumeMounts: + - name: workdir + mountPath: /data + containers: + - name: logstash + volumeMounts: + - name: workdir + mountPath: /usr/share/logstash/jars <1> + volumeClaimTemplates: + - metadata: + name: workdir + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 50Mi + pipelines: + - pipeline.id: main + config.string: | + input { + jdbc { + jdbc_driver_library => "/usr/share/logstash/jars/postgresql.jar" + jdbc_driver_class => "org.postgresql.Driver" + <2> + } + } +``` + +1. Should match the `mountPath` of the `container` +2. Remainder of plugin configuration goes here + + + +#### Add files using a custom Docker image [k8s-logstash-custom-images] + +This example downloads the same `postgres` JDBC driver, and adds it to the {{ls}} classpath in the Docker image. + +First, create a Dockerfile based on the {{ls}} Docker image. Download the JDBC driver, and save it alongside the other JAR files in the {{ls}} classpath: + +```shell +FROM docker.elastic.co/logstash/logstash:8.16.1 +RUN curl -o /usr/share/logstash/logstash-core/lib/jars/postgresql.jar -L https://jdbc.postgresql.org/download/postgresql-42.6.0.jar <1> +``` + +1. Placing the JAR file in the `/usr/share/logstash/logstash-core/lib/jars` folder adds it to the {{ls}} classpath. + + +After you build and deploy the custom image, include it in the {{ls}} manifest. Check out [*Create custom images*](create-custom-images.md) for more details. + +```yaml + count: 1 + version: {version} <1> + image: + pipelines: + - pipeline.id: main + config.string: | + input { + jdbc { + <2> + jdbc_driver_class => "org.postgresql.Driver" + <3> + } + } +``` + +1. The correct version is required as ECK reasons about available APIs and capabilities based on the version field. +2. Note that when you place the JAR file on the {{ls}} classpath, you do not need to specify the `jdbc_driver_library` location in the plugin configuration. +3. Remainder of plugin configuration goes here + + + + +### Writable storage [k8s-logstash-working-with-plugins-writable] + +Some {{ls}} plugins need access to writable storage. This could be for checkpointing to keep track of events already processed, a place to temporarily write events before sending a batch of events, or just to actually write events to disk in the case of [`logstash-output-file`](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-file.html). + +{{ls}} on ECK by default supplies a small 1.5 GiB (gibibyte) default persistent volume to each pod. This volume is called `logstash-data` and is located at `/usr/logstash/data`, and is typically the default location for most plugin use cases. This volume is stable across restarts of {{ls}} pods and is suitable for many use cases. + +::::{note} +When plugins use writable storage, each plugin must store its data a dedicated folder or file to avoid overwriting data. +:::: + + +#### Checkpointing [k8s-logstash-working-with-plugins-writable-checkpointing] + +Some {{ls}} plugins need to write "checkpoints" to local storage in order to keep track of events that have already been processed. Plugins that retrieve data from external sources need to do this if the external source does not provide any mechanism to track state internally. + +Not all external data sources have mechanisms to track state internally, and {{ls}} checkpoints can help persist data. + +In the plugin documentation, look for configurations that call for a `path` with a settings like `sincedb`, `sincedb_path`, `sequence_path`, or `last_run_metadata_path`. Check out specific plugin documentation in the [Logstash Reference](https://www.elastic.co/guide/en/logstash/current) for details. + +```yaml +spec: + pipelines: + - pipeline.id: main + config.string: | + input { + jdbc { + jdbc_driver_library => "/usr/share/logstash/jars/postgresql.jar" + jdbc_driver_class => "org.postgresql.Driver" + last_metadata_path => "/usr/share/logstash/data/main/logstash_jdbc_last_run <1> + } + } +``` + +1. If you are using more than one plugin of the same type, specify a unique location for each plugin to use. + + +If the default `logstash-data` volume is insufficient for your needs, see the volume section for details on how to add additional volumes. + + +#### Writable staging or temporary data [k8s-logstash-working-with-plugins-writable-temp] + +Some {{ls}} plugins write data to a staging directory or file before processing for input, or outputting to their final destination. Often these staging folders can be persisted across restarts to avoid duplicating processing of data. + +In the plugin documentation, look for names such as `tmp_directory`, `temporary_directory`, `staging_directory`. + +To persist data across pod restarts, set this value to point to the default `logstash-data` volume or your own PersistentVolumeClaim. + +```yaml +spec: + pipelines: + - pipeline.id: main + config.string: | + output { + s3 { + id => "main_s3_output" + temporary_directory => "/usr/share/logstash/data/main/main_s3_output<1> + } + } +``` + +1. If you are using more than one plugin of the same type, specify a unique location for each plugin to use. + + + + + +## Scaling {{ls}} on ECK [k8s-logstash-working-with-plugins-scaling] + +::::{important} +The use of autoscalers, such as the HorizontalPodAutoscaler or the VerticalPodAutoscaler, with {{ls}} on ECK is not yet supported. +:::: + + +{{ls}} scalability is highly dependent on the plugins in your pipelines. Some plugins can restrict how you can scale out your Logstash deployment, based on the way that the plugins gather or enrich data. + +Plugin categories that require special considerations are: + +* [Filter plugins: aggregating filters](#k8s-logstash-agg-filters) +* [Input plugins: events pushed to {{ls}}](#k8s-logstash-inputs-data-pushed) +* [Input plugins: {{ls}} maintains state](#k8s-logstash-inputs-local-checkpoints) +* [Input plugins: external source stores state](#k8s-logstash-inputs-external-state) + +If the pipeline *does not* contain any plugins from these categories, you can increase the number of {{ls}} instances by setting the `count` property in the {{ls}} resource: + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 3 +``` + +::::{admonition} Horizontal scaling for {{ls}} plugins +* Not all {{ls}} deployments can be scaled horizontally by increasing the number of {{ls}} Pods defined in the {{ls}} resource. Depending on the types of plugins in a {{ls}} installation, increasing the number of pods may cause data duplication, data loss, incorrect data, or may waste resources with pods unable to be utilized correctly. +* The ability of a {{ls}} installation to scale horizontally is bound by its most restrictive plugin(s). Even if all pipelines are using [`logstash-input-elastic_agent`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-elastic_agent.html) or [`logstash-input-beats`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-beats.html) which should enable full horizontal scaling, introducing a more restrictive input or filter plugin forces the restrictions for pod scaling associated with that plugin. + +:::: + + +### Filter plugins: aggregating filters [k8s-logstash-agg-filters] + +{{ls}} installations that use aggregating filters should be treated with particular care: + +* They **must** specify `pipeline.workers=1` for any pipelines that use them. +* The number of pods cannot be scaled above 1. + +Examples of aggregating filters include [`logstash-filter-aggregate`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-aggregate.html), [`logstash-filter-csv`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-csv.html) when `autodetect_column_names` set to `true`, and any [`logstash-filter-ruby`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-ruby.html) implementations that perform aggregations. + + +### Input plugins: events pushed to {{ls}} [k8s-logstash-inputs-data-pushed] + +{{ls}} installations with inputs that enable {{ls}} to receive data should be able to scale freely and have load spread across them horizontally. These plugins include [`logstash-input-beats`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-beats.html), [`logstash-input-elastic_agent`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-elastic_agent.html), [`logstash-input-tcp`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-tcp.html), and [`logstash-input-http`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-http.html). + + +### Input plugins: {{ls}} maintains state [k8s-logstash-inputs-local-checkpoints] + +{{ls}} installations that use input plugins that retrieve data from an external source, and **maintain local checkpoint state**, or would require some level of co-ordination between nodes to split up work can specify `pipeline.workers` freely, but should keep the pod count at 1 for each {{ls}} installation. + +Note that plugins that retrieve data from external sources, and require some level of coordination between nodes to split up work, are not good candidates for scaling horizontally, and would likely produce some data duplication. + +Input plugins that include configuration settings such as `sincedb`, `checkpoint` or `sql_last_run_metadata` may fall into this category. + +Examples of these plugins include [`logstash-input-jdbc`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-jdbc.html) (which has no automatic way to split queries across {{ls}} instances), [`logstash-input-s3`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-s3.html) (which has no way to split which buckets to read across {{ls}} instances), or [`logstash-input-file`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-file.html). + + +### Input plugins: external source stores state [k8s-logstash-inputs-external-state] + +{{ls}} installations that use input plugins that retrieve data from an external source, and **rely on the external source to store state** can scale based on the parameters of the external source. + +For example, a {{ls}} installation that uses a [`logstash-input-kafka`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-kafka.html) plugin to retrieve data can scale the number of pods up to the number of partitions used, as a partition can have at most one consumer belonging to the same consumer group. Any pods created beyond that threshold cannot be scheduled to receive data. + +Examples of these plugins include [`logstash-input-kafka`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-kafka.html), [`logstash-input-azure_event_hubs`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-azure_event_hubs.html), and [`logstash-input-kinesis`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-kinesis.html). + + + +## Plugin-specific considerations [k8s-logstash-working-with-plugin-considerations] + +Some plugins have additional requirements and guidelines for optimal performance in a {{ls}} ECK environment. + +* [{{ls}} integration plugin](#k8s-logstash-plugin-considerations-ls-integration) +* [Elasticsearch output plugin](#k8s-logstash-plugin-considerations-es-output) +* [Elastic_integration filter plugin](#k8s-logstash-plugin-considerations-integration-filter) +* [Elastic Agent input and Beats input plugins](#k8s-logstash-plugin-considerations-agent-beats) + +::::{tip} +Use these guidelines *in addition* to the general guidelines provided in [Scaling {{ls}} on ECK](#k8s-logstash-working-with-plugins-scaling). +:::: + + +### {{ls}} integration plugin [k8s-logstash-plugin-considerations-ls-integration] + +When your pipeline uses the [`Logstash integration`](https://www.elastic.co/guide/en/logstash/current/plugins-integrations-logstash.html) plugin, add `keepalive=>false` to the [logstash-output](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-logstash.html) definition to ensure that load balancing works correctly rather than keeping affinity to the same pod. + + +### Elasticsearch output plugin [k8s-logstash-plugin-considerations-es-output] + +The [`elasticsearch output`](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-elasticsearch.html) plugin requires certain roles to be configured in order to enable {{ls}} to communicate with {{es}}. + +You can customize roles in {{es}}. Check out [creating custom roles](../../users-roles/cluster-or-deployment-auth/native.md) + +```logstash +kind: Secret +apiVersion: v1 +metadata: + name: my-roles-secret +stringData: + roles.yml: |- + eck_logstash_user_role: + "cluster": ["monitor", "manage_ilm", "read_ilm", "manage_logstash_pipelines", "manage_index_templates", "cluster:admin/ingest/pipeline/get"], + "indices": [ + { + "names": [ "logstash", "logstash-*", "ecs-logstash", "ecs-logstash-*", "logs-*", "metrics-*", "synthetics-*", "traces-*" ], + "privileges": ["manage", "write", "create_index", "read", "view_index_metadata"] + } + ] +``` + + +### Elastic_integration filter plugin [k8s-logstash-plugin-considerations-integration-filter] + +The [`elastic_integration filter`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-elastic_integration.html) plugin allows the use of [`ElasticsearchRef`](configuration-logstash.md#k8s-logstash-esref) and environment variables. + +```logstash + elastic_integration { + pipeline_name => "logstash-pipeline" + hosts => [ "${ECK_ES_HOSTS}" ] + username => "${ECK_ES_USER}" + password => "${ECK_ES_PASSWORD}" + ssl_certificate_authorities => "${ECK_ES_SSL_CERTIFICATE_AUTHORITY}" + } +``` + +The Elastic_integration filter requires certain roles to be configured on the {{es}} cluster to enable {{ls}} to read ingest pipelines. + +```yaml +# Sample role definition +kind: Secret +apiVersion: v1 +metadata: + name: my-roles-secret +stringData: + roles.yml: |- + eck_logstash_user_role: + cluster: [ "monitor", "manage_index_templates", "read_pipeline"] +``` + + +### Elastic Agent input and Beats input plugins [k8s-logstash-plugin-considerations-agent-beats] + +When you use the [Elastic Agent input](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-elastic_agent.html) or the [Beats input](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-beats.html), set the [`ttl`](https://www.elastic.co/guide/en/beats/filebeat/current/logstash-output.html#_ttl) value on the Agent or Beat to ensure that load is distributed appropriately. + + + +## Adding custom plugins [k8s-logstash-working-with-custom-plugins] + +If you need plugins in addition to those included in the standard {{ls}} distribution, you can add them. Create a custom Docker image that includes the installed plugins, using the `bin/logstash-plugin install` utility to add more plugins to the image so that they can be used by {{ls}} pods. + +This sample Dockerfile installs the [`logstash-filter-tld`](https://www.elastic.co/guide/en/logstash/current/plugins-filters-tld.html) plugin to the official {{ls}} Docker image: + +```shell +FROM docker.elastic.co/logstash/logstash:8.16.1 +RUN bin/logstash-plugin install logstash-filter-tld +``` + +Then after building and deploying the custom image (refer to [*Create custom images*](create-custom-images.md) for more details), include it in the {{ls}} manifest: + +```shell +spec: + count: 1 + version: 8.16.1 <1> + image: +``` + +1. The correct version is required as ECK reasons about available APIs and capabilities based on the version field. diff --git a/deploy-manage/deploy/cloud-on-k8s/logstash.md b/deploy-manage/deploy/cloud-on-k8s/logstash.md new file mode 100644 index 000000000..3a614827b --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/logstash.md @@ -0,0 +1,46 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-logstash.html +--- + +# Logstash [k8s-logstash] + +This section describes how to configure and deploy {{ls}} with ECK. + +* [Quickstart](quickstart-logstash.md) +* [Configuration](configuration-logstash.md) + + * [Logstash configuration](configuration-logstash.md#k8s-logstash-configuring-logstash) + * [Configuring Logstash pipelines](configuration-logstash.md#k8s-logstash-pipelines) + * [Defining data volumes for Logstash](configuration-logstash.md#k8s-logstash-volumes) + * [Using Elasticsearch in Logstash pipelines](configuration-logstash.md#k8s-logstash-pipelines-es) + * [Expose services](configuration-logstash.md#k8s-logstash-expose-services) + +* [Securing Logstash API](securing-logstash-api.md) +* [{{ls}} plugins](logstash-plugins.md) + + * [Providing additional resources for plugins](logstash-plugins.md#k8s-plugin-resources) + * [Scaling {{ls}} on ECK](logstash-plugins.md#k8s-logstash-working-with-plugins-scaling) + * [Plugin-specific considerations](logstash-plugins.md#k8s-logstash-working-with-plugin-considerations) + * [Adding custom plugins](logstash-plugins.md#k8s-logstash-working-with-custom-plugins) + +* [Configuration examples](configuration-examples-logstash.md) +* [Update Strategy](update-strategy-logstash.md) +* [Advanced configuration](advanced-configuration-logstash.md) + + * [Setting JVM options](advanced-configuration-logstash.md#k8s-logstash-jvm-options) + * [Setting keystore](advanced-configuration-logstash.md#k8s-logstash-keystore) + + +::::{note} +Running {{ls}} on ECK is compatible only with {{ls}} 8.7+. +:::: + + + + + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/manage-compute-resources.md b/deploy-manage/deploy/cloud-on-k8s/manage-compute-resources.md new file mode 100644 index 000000000..1bf9a189d --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/manage-compute-resources.md @@ -0,0 +1,358 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-managing-compute-resources.html +--- + +# Manage compute resources [k8s-managing-compute-resources] + +To help the Kubernetes scheduler correctly place Pods in available Kubernetes nodes and ensure quality of service (QoS), it is recommended to specify the CPU and memory requirements for objects managed by the operator (Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash). In Kubernetes, `requests` defines the minimum amount of resources that must be available for a Pod to be scheduled; `limits` defines the maximum amount of resources that a Pod is allowed to consume. For more information about how Kubernetes uses these concepts, check [Managing Compute Resources for Containers](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/). + +::::{note} +The operator applies default requests and limits for memory and CPU. They may be suitable for experimenting with the Elastic Stack, however it is recommended to reevaluate these values for production use cases. +:::: + + +Consider that Kubernetes throttles containers exceeding the CPU limit defined in the `limits` section. Do not set this value too low, or it would affect the performance of your workloads, even if you have enough resources available in the Kubernetes cluster. + +Also, to minimize disruption caused by Pod evictions due to resource contention, you can run Pods at the "Guaranteed" QoS level by setting both `requests` and `limits` to the same value. + + +## Set compute resources [k8s-compute-resources] + +You can set compute resource constraints in the `podTemplate` of objects managed by the operator. + + +### Set compute resources for Elasticsearch [k8s-compute-resources-elasticsearch] + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + requests: + memory: 4Gi + cpu: 8 + limits: + memory: 4Gi +``` + + +#### Memory limit and JVM Heap settings [k8s-elasticsearch-memory] + +Starting with Elasticsearch 7.11, the heap size of the JVM is automatically calculated based on the node roles and the available memory. The available memory is defined by the value of `resources.limits.memory` set on the `elasticsearch` container in the Pod template, or the available memory on the Kubernetes node if no limit is set. + +For Elasticsearch before 7.11, or if you want to override the default calculated heap size on newer versions, set the `ES_JAVA_OPTS` environment variable in the `podTemplate` to an appropriate value: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + podTemplate: + spec: + containers: + - name: elasticsearch + env: + - name: ES_JAVA_OPTS + value: -Xms2g -Xmx2g + resources: + requests: + memory: 4Gi + cpu: 8 + limits: + memory: 4Gi +``` + + +#### CPU resources [k8s-elasticsearch-cpu] + +The value set for CPU limits or requests directly impacts the Elasticsearch `node.processors` setting. By default Elasticsearch automatically detects the number of processors and sets the thread pool settings based on it. The following table gives the default value for `node.processors` given the CPU limits and requests set on the `elasticsearch` container: + +| | No CPU limit | With CPU limit | +| --- | --- | --- | +| No CPU request | `All the available cores on the K8S node` | `Value of the CPU limit` | +| CPU request set to 1 | `All the available cores on the K8S node` | `Value of the CPU limit` | +| Other CPU requests | `Value of the CPU request` | `Value of the CPU limit` | + +You can also set your own value for `node.processors` in the Elasticsearch config. + +::::{note} +A [known Kubernetes issue](https://github.com/kubernetes/kubernetes/issues/51135) may lead to over-aggressive CPU limits throttling. If the host Linux Kernel does not include [this CFS quota fix](https://github.com/kubernetes/kubernetes/issues/67577), you may want to: + +* not set any CPU limit in the Elasticsearch resource (Burstable QoS) +* [reduce the CFS quota period](https://github.com/kubernetes/kubernetes/pull/63437) in kubelet configuration +* [disable CFS quotas](https://github.com/kubernetes/kubernetes/issues/51135#issuecomment-386319185) in kubelet configuration + +:::: + + + +### Set compute resources for Kibana, Enterprise Search, Elastic Maps Server, APM Server and Logstash [k8s-compute-resources-kibana-and-apm] + +```yaml +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: quickstart +spec: + version: 8.16.1 + podTemplate: + spec: + containers: + - name: kibana + env: + - name: NODE_OPTIONS + value: "--max-old-space-size=2048" + resources: + requests: + memory: 1Gi + cpu: 0.5 + limits: + memory: 2.5Gi + cpu: 2 +``` + +```yaml +apiVersion: maps.k8s.elastic.co/v1alpha1 +kind: ElasticMapsServer +metadata: + name: quickstart +spec: + version: 8.16.1 + podTemplate: + spec: + containers: + - name: maps + env: + - name: NODE_OPTIONS + value: "--max-old-space-size=980" + resources: + requests: + memory: 1Gi + cpu: 1 + limits: + memory: 1Gi + cpu: 1 +``` + +```yaml +apiVersion: apm.k8s.elastic.co/v1 +kind: ApmServer +metadata: + name: quickstart +spec: + version: 8.16.1 + podTemplate: + spec: + containers: + - name: apm-server + resources: + requests: + memory: 1Gi + cpu: 0.5 + limits: + memory: 2Gi + cpu: 2 +``` + +```yaml +apiVersion: enterprisesearch.k8s.elastic.co/v1 +kind: EnterpriseSearch +metadata: + name: enterprise-search-quickstart +spec: + version: 8.16.1 + podTemplate: + spec: + containers: + - name: enterprise-search + resources: + requests: + memory: 4Gi + cpu: 1 + limits: + memory: 4Gi + cpu: 2 + env: + - name: JAVA_OPTS + value: -Xms3500m -Xmx3500m +``` + +```yaml +apiVersion: logstash.k8s.elastic.co/v1 +kind: logstash +metadata: + name: logstash-quickstart +spec: + version: 8.16.1 + podTemplate: + spec: + containers: + - name: logstash + resources: + requests: + memory: 4Gi + cpu: 1 + limits: + memory: 4Gi + cpu: 2 + env: + - name: LS_JAVA_OPTS + value: -Xms2000m -Xmx2000m +``` + +For the container name, use `apm-server`, `maps`, `kibana` or `enterprise-search`, respectively. + + +### Set compute resources for Beats and Elastic Agent [k8s-compute-resources-beats-agent] + +For Beats or Elastic Agent objects, the `podTemplate` can be configured as follows, depending on the chosen deployment model. + +When deploying as a Kubernetes Deployment: + +```yaml +apiVersion: beat.k8s.elastic.co/v1beta1 +kind: Beat +metadata: + name: quickstart +spec: + type: filebeat + version: 8.16.1 + deployment: + podTemplate: + spec: + containers: + - name: filebeat + resources: + requests: + memory: 300Mi + cpu: 0.5 + limits: + memory: 500Mi + cpu: 0.5 +``` + +When deploying as a Kubernetes DaemonSet: + +```yaml +apiVersion: agent.k8s.elastic.co/v1alpha1 +kind: Agent +metadata: + name: elastic-agent +spec: + version: 8.16.1 + daemonSet: + podTemplate: + spec: + containers: + - name: agent + resources: + requests: + memory: 300Mi + cpu: 0.5 + limits: + memory: 300Mi + cpu: 0.5 +``` + +For the container name, use the name of the Beat in lower case. For example `filebeat`, `metricbeat`, or `heartbeat`. In case of Elastic Agent, use `agent`. + + +## Default behavior [k8s-default-behavior] + +If `resources` is not defined in the specification of an object, then the operator applies a default memory limit to ensure that Pods have enough resources to start correctly. This memory limit will also be applied to any user-defined init containers that do not have explict resource requirements set. As the operator cannot make assumptions about the available CPU resources in the cluster, no CPU limits will be set — resulting in the Pods having the "Burstable" QoS class. Check if this is acceptable for your use case and follow the instructions in [Set compute resources](#k8s-compute-resources) to configure appropriate limits. + +| Type | Requests | Limits | +| --- | --- | --- | +| APM Server | `512Mi` | `512Mi` | +| Elasticsearch | `2Gi` | `2Gi` | +| Kibana | `1Gi` | `1Gi` | +| Beat | `300Mi` | `300Mi` | +| Elastic Agent | `400Mi` | `400Mi` | +| Elastic Maps Server | `200Mi` | `200Mi` | +| Enterprise Search | `4Gi` | `4Gi` | +| Logstash | `2Gi` | `2Gi` | + +If the Kubernetes cluster is configured with [LimitRanges](https://kubernetes.io/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/) that enforce a minimum memory constraint, they could interfere with the operator defaults and cause object creation to fail. + +For example, you might have a `LimitRange` that enforces a default and minimum memory limit on containers as follows: + +```yaml +apiVersion: v1 +kind: LimitRange +metadata: + name: default-mem-per-container +spec: + limits: + - min: + memory: "3Gi" + defaultRequest: + memory: "3Gi" + type: Container +``` + +With this limit range in place, if you create an Elasticsearch object without defining the `resources` section, you will get the following error: + +``` +Cannot create pod elasticsearch-sample-es-ldbgj48c7r: pods "elasticsearch-sample-es-ldbgj48c7r" is forbidden: minimum memory usage per Container is 3Gi, but request is 2Gi +``` +To avoid this, explicitly define the requests and limits mandated by your environment in the resource specification. It will prevent the operator from applying the built-in defaults. + + +## Monitor compute resources [k8s-monitor-compute-resources] + + +#### Using Beats [k8s-monitor-compute-resources-beats] + +[Metricbeat](beats.md) can collect the percentage of both the CPU and the memory limits used by each Pod (or total node allocatable if resource is not limited). The two relevant metrics are `kubernetes.pod.cpu.usage.limit.pct` for CPU, and `kubernetes.pod.memory.usage.node.pct` for memory. + +:::{image} ../../../images/cloud-on-k8s-metrics-explorer-cpu.png +:alt: cgroup CPU perforamce chart +:class: screenshot +::: + + +#### Monitoring Elasticsearch CPU using Stack Monitoring [k8s-monitor-compute-resources-stack-monitoring] + +If [Stack Monitoring](../../monitor/stack-monitoring/enable-stack-monitoring-on-eck-deployments.md) is enabled, the pressure applied by the CPU cgroup controller to an Elasticsearch node can be evaluated from the **Stack Monitoring** page in Kibana. + +1. On the **Stack Monitoring** page select the Elasticsearch node you want to monitor. +2. Select the **Advanced** tab. + +In the following example, an Elasticsearch container is limited to 2 cores. + +```yaml +nodeSets: +- name: default + count: 3 + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 2 +``` + +The **Cgroup usage** curve shows that the CPU usage of this container has been steadily increasing up to 2 cores. Then, while the container was still requesting more CPU, the **Cgroup Throttling** curve shows how much the Elasticsearch container has been throttled: + +:::{image} ../../../images/cloud-on-k8s-cgroups-cfs-stats.png +:alt: cgroup CPU perforamce chart +:class: screenshot +::: + diff --git a/deploy-manage/deploy/cloud-on-k8s/manage-deployments.md b/deploy-manage/deploy/cloud-on-k8s/manage-deployments.md new file mode 100644 index 000000000..19c32a12f --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/manage-deployments.md @@ -0,0 +1,7 @@ +# Manage deployments + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/357 + +% Scope notes: To be decided... \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md b/deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md new file mode 100644 index 000000000..c7d768899 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md @@ -0,0 +1,116 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-stack-helm-chart.html +--- + +# Managing deployments using a Helm chart [k8s-stack-helm-chart] + +Starting from ECK 2.4.0, a Helm chart is available for managing Elastic Stack resources using the ECK Operator. It is available from the Elastic Helm repository and can be added to your Helm repository list by running the following command: + +```sh +helm repo add elastic https://helm.elastic.co +helm repo update +``` + +::::{note} +The minimum supported version of Helm is 3.2.0. +:::: + + + +## Installing Elasticsearch and Kibana using the eck-stack Helm Chart [k8s-install-elasticsearch-kibana-helm] + +Similar to the [quickstart](elasticsearch-deployment-quickstart.md), the following section describes how to setup an Elasticsearch cluster with a simple Kibana instance managed by ECK, and how to customize a deployment using the eck-stack Helm chart’s values. + +```sh +# Install an eck-managed Elasticsearch and Kibana using the default values, which deploys the quickstart examples. +helm install es-kb-quickstart elastic/eck-stack -n elastic-stack --create-namespace +``` + + +### Customizing Kibana and Elasticsearch using the eck-stack Helm Chart’s example values [k8s-eck-stack-helm-customize] + +There are example Helm values files for installing and managing a more advanced Elasticsearch and/or Kibana [in the project repository](https://github.com/elastic/cloud-on-k8s/tree/2.16/deploy/eck-stack/examples). + +To use one or more of these example configurations, use the `--values` Helm option, as seen in the following section. + +```sh +# Install an eck-managed Elasticsearch and Kibana using the Elasticsearch node roles example with hot, warm, and cold data tiers, and the Kibana example customizing the http service. +helm install es-quickstart elastic/eck-stack -n elastic-stack --create-namespace \ + --values https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/deploy/eck-stack/examples/elasticsearch/hot-warm-cold.yaml \ + --values https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/deploy/eck-stack/examples/kibana/http-configuration.yaml +``` + + +## Installing Fleet Server with Elastic Agents along with Elasticsearch and Kibana using the eck-stack Helm Chart [k8s-install-fleet-agent-elasticsearch-kibana-helm] + +The following section builds upon the previous section, and allows installing Fleet Server, and Fleet-managed Elastic Agents along with Elasticsearch and Kibana. + +```sh +# Install an eck-managed Elasticsearch, Kibana, Fleet Server, and managed Elastic Agents using custom values. +helm install eck-stack-with-fleet elastic/eck-stack \ + --values https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/deploy/eck-stack/examples/agent/fleet-agents.yaml -n elastic-stack +``` + + +## Installing Logstash along with Elasticsearch, Kibana and Beats using the eck-stack Helm Chart [k8s-install-logstash-elasticsearch-kibana-helm] + +The following section builds upon the previous sections, and allows installing Logstash along with Elasticsearch, Kibana and Beats. + +```sh +# Install an eck-managed Elasticsearch, Kibana, Beats and Logstash using custom values. +helm install eck-stack-with-logstash elastic/eck-stack \ + --values https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/deploy/eck-stack/examples/logstash/basic-eck.yaml -n elastic-stack +``` + + +## Installing a standalone Elastic APM Server along with Elasticsearch and Kibana using the eck-stack Helm Chart [k8s-install-apm-server-elasticsearch-kibana-helm] + +The following section builds upon the previous sections, and allows installing a standalone Elastic APM Server along with Elasticsearch and Kibana. + +```sh +# Install an eck-managed Elasticsearch, Kibana, and standalone APM Server using custom values. +helm install eck-stack-with-apm-server elastic/eck-stack \ + --values https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/deploy/eck-stack/examples/apm-server/basic.yaml -n elastic-stack +``` + + +## Installing an Elastic Enterprise Search Server along with Elasticsearch and Kibana using the eck-stack Helm Chart [k8s-install-enterprise-search-elasticsearch-kibana-helm] + +The following section builds upon the previous sections, and allows installing an Elastic Enterprise Search Server along with Elasticsearch and Kibana. + +```sh +# Install an eck-managed Elasticsearch, Kibana, and Enterprise Search Server using custom values. +helm install eck-stack-with-enterprise-search elastic/eck-stack \ + --values https://raw.githubusercontent.com/elastic/cloud-on-k8s/2.16/deploy/eck-stack/examples/enterprise-search/basic.yaml -n elastic-stack +``` + + +### Installing individual components of the Elastic Stack using the Helm Charts [k8s-eck-stack-individual-components] + +You can install individual components in one of two ways using the provided Helm Charts. + +1. Using Helm values +2. Using the individual Helm Charts directly + +**Using Helm values to install only Elasticsearch** + +```sh +helm install es-quickstart elastic/eck-stack -n elastic-stack --create-namespace --set=eck-kibana.enabled=false +``` + +**Using the eck-elasticsearch Helm Chart directly to install only Elasticsearch** + +```sh +helm install es-quickstart elastic/eck-elasticsearch -n elastic-stack --create-namespace +``` + + +### Adding Ingress to the Elastic stack using the Helm Charts [k8s-eck-stack-ingress] + +Both Elasticsearch and Kibana support Ingress, which can be enabled using the following options: + +```sh +helm install es-quickstart elastic/eck-elasticsearch -n elastic-stack --create-namespace --set=ingress.enabled=true --set=ingress.hosts[0].host=elasticsearch.example.com --set=ingress.hosts[0].path="/" +``` + diff --git a/deploy-manage/deploy/cloud-on-k8s/map-data.md b/deploy-manage/deploy/cloud-on-k8s/map-data.md new file mode 100644 index 000000000..cbff49066 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/map-data.md @@ -0,0 +1,107 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-maps-data.html +--- + +# Map data [k8s-maps-data] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +The Elastic Maps Server Docker image contains only a few zoom levels of data. To get the map data up to the highest zoom level, Elastic Maps Server needs a basemap file mounted into its container. + +## Basemap download [k8s-maps-basemap-download] + +You have to download the basemap ahead of time on a machine that is not air-gapped and populate a volume that can be mounted into the Elastic Maps Server Pods. Check also the [Elastic Maps Server documentation.](https://www.elastic.co/guide/en/kibana/current/maps-connect-to-ems.html#elastic-maps-server) + +The procedure on how to get a Kubernetes volume populated with that data is outside the scope of this document, as it depends on your specific Kubernetes setup and choice of volume provisioner. This is a possible approach that works for most setups: + +1. Download the basemap zip archive using the link shown in the Elastic Maps Server UI or extracted from the `/status` endpoint. +2. Create a PersistentVolumeClaim of sufficient size (> 90G for the maximal resolution) and a temporary Pod to mount the corresponding volume. + + ```yaml + --- + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: ems-basemap + spec: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 250G + --- + kind: Pod + apiVersion: v1 + metadata: + name: ems-data-setup + spec: + terminationGracePeriodSeconds: 0 + volumes: + - name: ems-storage + persistentVolumeClaim: + claimName: ems-basemap + containers: + - name: ems-setup + image: ubuntu + command: [bash, -c, "apt-get update && apt-get install unzip && while true; do sleep 10; done"] + volumeMounts: + - mountPath: "/usr/share/planet" + name: ems-storage + ``` + +3. Use `kubectl` to copy the basemap data into the volume + + ```sh + kubectl cp planet.zip ems-data-setup:/usr/share/planet/planet.zip + ``` + +4. Unzip the archive on the temporary Pod + + ```sh + kubectl exec ems-data-setup -- unzip /usr/share/data/planet.zip -d /usr/share/planet + ``` + +5. Delete the temporary Pod and remount the volume into the Elastic Maps Server Pods as described in [Pod configuration](#k8s-maps-pod-configuration). + + ```sh + kubectl delete pod ems-data-setup + ``` + + + +## Pod configuration [k8s-maps-pod-configuration] + +You can [customize the Elastic Maps Server Pod](customize-pods.md) using a Pod template. + +The following example demonstrates how to create a Elastic Maps Server deployment which mounts a data volume with the complete basemap. + +```yaml +apiVersion: maps.k8s.elastic.co/v1alpha1 +kind: ElasticMapsServer +metadata: + name: quickstart +spec: + version: 8.16.1 + count: 1 + podTemplate: + spec: + containers: + - name: maps + volumeMounts: + - name: map-data + readOnly: true + mountPath: /usr/src/app/data + volumes: + - name: map-data + persistentVolumeClaim: + claimName: ems-basemap +``` + +The name of the container in the Pod template must be `maps`. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/network-policies.md b/deploy-manage/deploy/cloud-on-k8s/network-policies.md new file mode 100644 index 000000000..0f0bbfdb8 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/network-policies.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-network-policies.html +--- + +# Network policies [k8s-network-policies] + +[Network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) allow you to isolate pods by restricting incoming and outgoing network connections to a trusted set of sources and destinations. This section describes how to use network policies to isolate the ECK operator and the {{stack}} applications to a set of namespaces to implement a form of soft multi-tenancy. Soft multi-tenancy is a term used to describe a scenario where a group of trusted users (different teams within an organization, for example) share a single resource such as a Kubernetes cluster. Note that network policies alone are not sufficient for security. You should complement them with strict RBAC policies, resource quotas, node taints, and other available security mechanisms to ensure that tenants cannot access, modify, or disrupt resources belonging to each other. + +::::{note} +There are several efforts to support multi-tenancy on Kubernetes, including the [official working group for multi-tenancy](https://github.com/kubernetes-sigs/multi-tenancy) and community extensions such as [loft](https://loft.sh) and [kiosk](https://github.com/kiosk-sh/kiosk), that can make configuration and management easier. You might need to employ network policies such the ones described in this section to have fine-grained control over {{stack}} applications deployed by your tenants. +:::: + + +The following sections assume that the operator is installed in the `elastic-system` namespace with the [`namespaces` configuration](configure-eck.md) set to `team-a,team-b`. Each namespace is expected to be labelled as follows: + +```sh +kubectl label namespace elastic-system eck.k8s.elastic.co/operator-name=elastic-operator +kubectl label namespace team-a eck.k8s.elastic.co/tenant=team-a +kubectl label namespace team-b eck.k8s.elastic.co/tenant=team-b +``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/node-configuration.md b/deploy-manage/deploy/cloud-on-k8s/node-configuration.md new file mode 100644 index 000000000..ece4a7918 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/node-configuration.md @@ -0,0 +1,35 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-node-configuration.html +--- + +# Node configuration [k8s-node-configuration] + +Any setting defined in the `elasticsearch.yml` configuration file can also be defined for a set of Elasticsearch nodes in the `spec.nodeSets[?].config` section. + +Some settings are managed by ECK, it is not recommended to change them, refer to [Settings managed by ECK](settings-managed-by-eck.md) for more details. + +```yaml +spec: + nodeSets: + - name: masters + count: 3 + config: + # On Elasticsearch versions before 7.9.0, replace the node.roles configuration with the following: + # node.master: true + node.roles: ["master"] + xpack.ml.enabled: true + - name: data + count: 10 + config: + # On Elasticsearch versions before 7.9.0, replace the node.roles configuration with the following: + # node.master: false + # node.data: true + # node.ingest: true + # node.ml: true + # node.transform: true + node.roles: ["data", "ingest", "ml", "transform"] +``` + +For more information on Elasticsearch settings, check [Configuring Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html). + diff --git a/deploy-manage/deploy/cloud-on-k8s/nodes-orchestration.md b/deploy-manage/deploy/cloud-on-k8s/nodes-orchestration.md new file mode 100644 index 000000000..87762d3aa --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/nodes-orchestration.md @@ -0,0 +1,264 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-orchestration.html +--- + +# Nodes orchestration [k8s-orchestration] + +This section covers the following topics: + +* [NodeSets overview](#k8s-nodesets) +* [Cluster upgrade](#k8s-upgrading) +* [Cluster upgrade patterns](#k8s-upgrade-patterns) +* [StatefulSets orchestration](#k8s-statefulsets) +* [Limitations](#k8s-orchestration-limitations) + +## NodeSets overview [k8s-nodesets] + +NodeSets are used to specify the topology of the Elasticsearch cluster. Each NodeSet represents a group of Elasticsearch nodes that share the same Elasticsearch configuration and Kubernetes Pod configuration. + +::::{tip} +You can use [YAML anchors](https://yaml.org/spec/1.2/spec.md#id2765878) to declare the configuration change once and reuse it across all the node sets. +:::: + + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + nodeSets: + - name: master-nodes + count: 3 + config: + node.roles: ["master"] + volumeClaimTemplates: + - metadata: + name: elasticsearch-data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + storageClassName: standard + - name: data-nodes + count: 10 + config: + node.roles: ["data"] + volumeClaimTemplates: + - metadata: + name: elasticsearch-data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1000Gi + storageClassName: standard +``` + +In this example, the Elasticsearch resource defines two NodeSets: + +* `master-nodes` with 10Gi volumes +* `data-nodes` with 1000Gi volumes + +The Elasticsearch cluster is composed of 13 nodes: 3 master nodes and 10 data nodes. + + +## Upgrading the cluster [k8s-upgrading] + +ECK handles smooth upgrades from one cluster specification to another. You can apply a new Elasticsearch specification at any time. For example, based on the Elasticsearch specification described in the [NodeSets overview](#k8s-nodesets), you can: + +* Add five additional Elasticsearch data nodes: In `data-nodes` change the value in the `count` field from 10 to 15. +* Increase the memory limit of data nodes to 32Gi: Set a [different resource limit](manage-compute-resources.md) in the existing `data-nodes` NodeSet. +* Replace dedicated master and dedicated data nodes with nodes having both master and data roles: Replace the two existing NodeSets by a single one with a different name and the appropriate Elasticsearch configuration settings. +* Upgrade Elasticsearch from version 7.2.0 to 7.3.0: Change the value in the `version` field. + +ECK orchestrates NodeSet changes with no downtime and makes sure that: + +* Before a node is removed, the relevant data is migrated to other nodes (with some [limitations](#k8s-orchestration-limitations)). +* When a cluster topology changes, these Elasticsearch settings are adjusted accordingly: + + * `discovery.seed_hosts` + * `cluster.initial_master_nodes` + * `discovery.zen.minimum_master_nodes` + * `_cluster/voting_config_exclusions` + +* Rolling upgrades are performed safely with existing PersistentVolumes reused where possible. + + +## StatefulSets orchestration [k8s-statefulsets] + +Behind the scenes, ECK translates each NodeSet specified in the Elasticsearch resource into a [StatefulSet in Kubernetes](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/). The NodeSet specification is based on the StatefulSet specification: + +* `count` corresponds to the number of replicas in the StatefulSet. A StatefulSet replica is a Pod — which corresponds to an Elasticsearch node. +* `podTemplate` can be used to [customize some aspects of the Elasticsearch Pods](customize-pods.md) created by the underlying StatefulSet. +* The StatefulSet name is derived from the Elasticsearch resource name and the NodeSet name. Each Pod in the StatefulSet gets a name generated by suffixing the pod ordinal to the StatefulSet name. Elasticsearch nodes have the same name as the Pod they are running on. + +The actual Pod creation is handled by the StatefulSet controller in Kubernetes. ECK relies on the [OnDelete StatefulSet update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies) since it needs full control over when and how Pods get upgraded to a new revision. + +When a Pod is removed and recreated (maybe with a newer revision), the StatefulSet controller makes sure that the PersistentVolumes attached to the original Pod are then attached to the new Pod. + + +## Cluster upgrade patterns [k8s-upgrade-patterns] + +Depending on how the NodeSets are updated, ECK handles the Kubernetes resource reconciliation in various ways. + +* A new NodeSet is added to the Elasticsearch resource. + + ECK creates the corresponding StatefulSet. It also sets up [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) and [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) to hold the TLS certificates and Elasticsearch configuration files. + +* The node count of an existing NodeSet is increased. + + ECK increases the replicas of the corresponding StatefulSet. + +* The node count of an existing NodeSet is decreased. + + ECK migrates data away from the Elasticsearch nodes due to be removed and then decreases the replicas of the corresponding StatefulSet. [PersistentVolumeClaims](volume-claim-templates.md) belonging to the removed nodes are automatically removed as well. + +* An existing NodeSet is removed. + + ECK migrates data away from the Elasticsearch nodes in the NodeSet and removes the underlying StatefulSet. + +* The specification of an existing NodeSet is updated. For example, the Elasticsearch configuration, or the PodTemplate resources requirements. + + ECK performs a rolling upgrade of the corresponding Elasticsearch nodes. It follows the [Elasticsearch rolling upgrade best practices](https://www.elastic.co/guide/en/elastic-stack/current/upgrading-elasticsearch.html) to update the underlying Pods while maintaining the availability of the Elasticsearch cluster where possible. In most cases, the process simply involves restarting Elasticsearch nodes one-by-one. Note that some cluster topologies may be impossible to deploy without making the cluster unavailable (check [Limitations](#k8s-orchestration-limitations) ). + +* An existing NodeSet is renamed. + + ECK creates a new NodeSet with the new name, migrates data away from the old NodeSet, and then removes it. During this process the Elasticsearch cluster could temporarily have more nodes than normal. The Elasticsearch [update strategy](update-strategy.md) controls how many nodes can exist above or below the target node count during the upgrade. + + +In all these cases, ECK handles StatefulSet operations according to the Elasticsearch orchestration best practices by adjusting the following orchestration settings: + +* `discovery.seed_hosts` +* `cluster.initial_master_nodes` +* `discovery.zen.minimum_master_nodes` +* `_cluster/voting_config_exclusions` + + +## Limitations [k8s-orchestration-limitations] + +Due to relying on Kubernetes primitives such as StatefulSets, the ECK orchestration process has some inherent limitations. + +* Cluster availability during rolling upgrades is not guaranteed for the following cases: + + * Single-node clusters + * Clusters containing indices with no replicas + + +If an {{es}} node holds the only copy of a shard, this shard becomes unavailable while the node is upgraded. To ensure [high availability](https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability-cluster-design.html) it is recommended to configure clusters with three master nodes, more than one node per [data tier](https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tiers.html) and at least one replica per index. + +* Elasticsearch Pods may stay `Pending` during a rolling upgrade if the Kubernetes scheduler cannot re-schedule them back. This is especially important when using local PersistentVolumes. If the Kubernetes node bound to a local PersistentVolume does not have enough capacity to host an upgraded Pod which was temporarily removed, that Pod will stay `Pending`. +* Rolling upgrades can only make progress if the Elasticsearch cluster health is green. There are exceptions to this rule if the cluster health is yellow and if the following conditions are satisfied: + + * A cluster version upgrade is in progress and some Pods are not up to date. + * There are no initializing or relocating shards. + + +If these conditions are met, then ECK can delete a Pod for upgrade even if the cluster health is yellow, as long as the Pod is not holding the last available replica of a shard. + +The health of the cluster is deliberately ignored in the following cases: + +* If all the Elasticsearch nodes of a NodeSet are unavailable, probably caused by a misconfiguration, the operator ignores the cluster health and upgrades nodes of the NodeSet. +* If an Elasticsearch node to upgrade is not healthy, and not part of the Elasticsearch cluster, the operator ignores the cluster health and upgrades the Elasticsearch node. + + * Elasticsearch versions cannot be downgraded. For example, it is impossible to downgrade an existing cluster from version 7.3.0 to 7.2.0. This is not supported by Elasticsearch. + + +Advanced users may force an upgrade by manually deleting Pods themselves. The deleted Pods are automatically recreated at the latest revision. + +Operations that reduce the number of nodes in the cluster cannot make progress without user intervention, if the Elasticsearch index replica settings are incompatible with the intended downscale. Specifically, if the Elasticsearch index settings demand a higher number of shard copies than data nodes in the cluster after the downscale operation, ECK cannot migrate the data away from the node about to be removed. You can address this in the following ways: + +* Adjust the Elasticsearch [index settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-update-settings.html) to a number of replicas that allow the desired node removal. +* Use [`auto_expand_replicas`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#dynamic-index-settings) to automatically adjust the replicas to the number of data nodes in the cluster. + + +## Advanced control during rolling upgrades [k8s-advanced-upgrade-control] + +The rules (otherwise known as predicates) that the ECK operator follows during an Elasticsearch upgrade can be selectively disabled for certain scenarios where the ECK operator will not proceed with an Elasticsearch cluster upgrade because it deems it to be "unsafe". + +::::{warning} +Selectively disabling the predicates listed in this section are extremely risky, and carry a high chance of either data loss, or causing a cluster to become completely unavailable. Use them only if you are sure that you are not causing permanent damage to an Elasticsearch cluster. These predicates might change in the future. We will be adding, removing, and renaming these over time, so be careful in adding these to any automation. Also, make sure you remove them after use. `kublectl annotate elasticsearch.elasticsearch.k8s.elastic.co/elasticsearch-sample eck.k8s.elastic.co/disable-upgrade-predicates-` +:::: + + +* The following named predicates control the upgrade process + + * data_tier_with_higher_priority_must_be_upgraded_first + + Upgrade the frozen tier first, then the cold tier, then the warm tier, and the hot tier last. This ensures ILM can continue to move data through the tiers during the upgrade. + + * do_not_restart_healthy_node_if_MaxUnavailable_reached + + If `maxUnavailable` is reached, only allow unhealthy Pods to be deleted. + + * skip_already_terminating_pods + + Do not attempt to restart pods that are already in the process of being terminated. + + * only_restart_healthy_node_if_green_or_yellow + + Only restart healthy Elasticsearch nodes if the health of the cluster is either green or yellow, never red. + + * if_yellow_only_restart_upgrading_nodes_with_unassigned_replicas + + During a rolling upgrade, primary shards assigned to a node running a new version cannot have their replicas assigned to a node with the old version. Therefore we must allow some Pods to be restarted even if cluster health is yellow so the replicas can be assigned. + + * require_started_replica + + If a cluster is yellow, allow deleting a node, but only if they do not contain the only replica of a shard since it would make the cluster go red. + + * one_master_at_a_time + + Only allow a single master to be upgraded at a time. + + * do_not_delete_last_master_if_all_master_ineligible_nodes_are_not_upgraded + + Force an upgrade of all the master-ineligible nodes before upgrading the last master-eligible node. + + * do_not_delete_pods_with_same_shards + + Do not allow two pods containing the same shard to be deleted at the same time. + + * do_not_delete_all_members_of_a_tier + + Do not delete all nodes that share the same node roles at once. This ensures that there is always availability for each configured tier of nodes during a rolling upgrade. + + +Any of these predicates can be disabled by adding an annotation with the key of `eck.k8s.elastic.co/disable-upgrade-predicates` to the Elasticsearch metadata, specifically naming the predicate that is needing to be disabled. Also, all predicates can be disabled by replacing the name of any predicatae with "*". + +* Example use case + +Assume a given Elasticsearch cluster is a "red" state because of an un-allocatable shard setting that was applied to the cluster: + +```json +{ + "settings": { + "index.routing.allocation.include._id": "does not exist" + } +} +``` + +This cluster would never be allowed to be upgraded with the standard set of upgrade predicates in place, as the cluster is in a "red" state, and the named predicate `only_restart_healthy_node_if_green_or_yellow` prevents the upgrade. + +If the following annotation was added to the cluster specification, and the version was increased from 7.15.2 → 7.15.3 + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: testing + annotations: + eck.k8s.elastic.co/disable-upgrade-predicates: "only_restart_healthy_node_if_green_or_yellow" + # Also note that eck.k8s.elastic.co/disable-upgrade-predicates: "*" would work as well, but is much less selective. +spec: + version: 7.15.3 # previously set to 7.15.2, for example +``` + +The ECK operator would allow this upgrade to proceed, even though the cluster was in a "red" state during this upgrade process. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/orchestrate-other-elastic-applications.md b/deploy-manage/deploy/cloud-on-k8s/orchestrate-other-elastic-applications.md new file mode 100644 index 000000000..0ab9e93bd --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/orchestrate-other-elastic-applications.md @@ -0,0 +1,3 @@ +# Orchestrate other Elastic applications + +% What needs to be done: Write from scratch \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/pod-disruption-budget.md b/deploy-manage/deploy/cloud-on-k8s/pod-disruption-budget.md new file mode 100644 index 000000000..661b5f91f --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/pod-disruption-budget.md @@ -0,0 +1,81 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-pod-disruption-budget.html +--- + +# Pod disruption budget [k8s-pod-disruption-budget] + +A [Pod Disruption Budget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) (PDB) allows you to limit the disruption to your application when its pods need to be rescheduled for some reason such as upgrades or routine maintenance work on the Kubernetes nodes. + +ECK manages a default PDB per {{es}} resource. It allows one {{es}} Pod to be taken down, as long as the cluster has a `green` health. Single-node clusters are not considered highly available and can always be disrupted. + +In the {{es}} specification, you can change the default behaviour as follows: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 3 + podDisruptionBudget: + spec: + minAvailable: 2 + selector: + matchLabels: + elasticsearch.k8s.elastic.co/cluster-name: quickstart +``` + +::::{note} +[`maxUnavailable`](https://kubernetes.io/docs/tasks/run-application/configure-pdb/#arbitrary-controllers-and-selectors) cannot be used with an arbitrary label selector, therefore `minAvailable` is used in this example. +:::: + + +## Pod disruption budget per nodeset [k8s-pdb-per-nodeset] + +You can specify a PDB per nodeset or node role. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + podDisruptionBudget: {} <1> + version: 8.16.1 + nodeSets: + - name: master + count: 3 + config: + node.roles: "master" + node.store.allow_mmap: false + - name: hot + count: 2 + config: + node.roles: ["data_hot", "data_content", "ingest"] + node.store.allow_mmap: false + +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: hot-nodes-pdb +spec: + minAvailable: 1 <5> + selector: + matchLabels: + elasticsearch.k8s.elastic.co/cluster-name: quickstart <3> + elasticsearch.k8s.elastic.co/statefulset-name: quickstart-es-hot <6> +``` + +1. Disable the default {{es}} pod disruption budget. +2. Specify pod disruption budget to have 2 master nodes available. +3. The pods should be in the "quickstart" cluster. +4. Pod disruption budget applies on all master nodes. +5. Specify pod disruption budget to have 1 hot node available. +6. Pod disruption budget applies on nodes of the same nodeset. + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/pod-prestop-hook.md b/deploy-manage/deploy/cloud-on-k8s/pod-prestop-hook.md new file mode 100644 index 000000000..0d3223a41 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/pod-prestop-hook.md @@ -0,0 +1,40 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-prestop.html +--- + +# Pod PreStop hook [k8s-prestop] + +When an Elasticsearch `Pod` is terminated, its `Endpoint` is removed from the `Service` and the Elasticsearch process is terminated. As these two operations happen in parallel, a race condition exists. If the Elasticsearch process is already shut down, but the `Endpoint` is still a part of the `Service`, any new connection might fail. For more information, check [Termination of pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/#termination-of-pods). + +Moreover, kube-proxy resynchronizes its rules [every 30 seconds by default](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/#options). During that time window of 30 seconds, the terminating Pod IP may still be used when targeting the service. Please note the resync operation itself may take some time, especially if kube-proxy is configured to use iptables with a lot of services and rules to apply. + +To address this issue and minimize unavailability, ECK relies on a [PreStop lifecycle hook](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/). It waits for an additional `PRE_STOP_ADDITIONAL_WAIT_SECONDS` (defaulting to 50). The additional wait time is used to: + +1. Give time to in-flight requests to be completed. +2. Give clients time to use the terminating Pod IP resolved just before DNS record was updated. +3. Give kube-proxy time to refresh ipvs or iptables rules on all nodes, depending on its sync period setting. + +The exact behavior is configurable using an environment variable, for example: + +```yaml +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + podTemplate: + spec: + containers: + - name: elasticsearch + env: + - name: PRE_STOP_ADDITIONAL_WAIT_SECONDS + value: "5" +``` + +The pre-stop lifecycle hook also tries to gracefully shut down the Elasticsearch node in case of a termination that is not caused by the ECK operator. Examples of such terminations could be Kubernetes node maintenance or a Kubernetes upgrade. In these cases the script will try to interact with the Elasticsearch API to notify Elasticsearch of the impending termination of the node. The intent is to avoid relocation and recovery of shards while the Elasticsearch node is only temporarily unavailable. + +This is done on a best effort basis. In particular requests to an Elasticsearch cluster already in the process of shutting down might fail if the Kubernetes service has already been removed. The script allows for `PRE_STOP_MAX_DNS_ERRORS` which default to 2 before giving up. + +When using local persistent volumes a different behaviour might be desirable because the Elasticsearch node’s associated storage will not be available anymore on the new Kubernetes node. `PRE_STOP_SHUTDOWN_TYPE` allows to override the default shutdown type to one of the [possible values](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-shutdown.html). Please be aware that setting it to anything other than `restart` might mean that the pre-stop hook will run longer than `terminationGracePeriodSeconds` of the Pod while moving data out of the terminating Pod and will not be able to complete unless you also adjust that value in the `podTemplate`. + diff --git a/deploy-manage/deploy/cloud-on-k8s/quickstart-beats.md b/deploy-manage/deploy/cloud-on-k8s/quickstart-beats.md new file mode 100644 index 000000000..bf98e7c60 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/quickstart-beats.md @@ -0,0 +1,101 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-beat-quickstart.html +--- + +# Quickstart [k8s-beat-quickstart] + +1. Apply the following specification to deploy Filebeat and collect the logs of all containers running in the Kubernetes cluster. ECK automatically configures the secured connection to an Elasticsearch cluster named `quickstart`, created in the [Elasticsearch quickstart](deploy-an-orchestrator.md). + + ```yaml + cat < **Discover**. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/quickstart-enterprise-search.md b/deploy-manage/deploy/cloud-on-k8s/quickstart-enterprise-search.md new file mode 100644 index 000000000..f22d8ace5 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/quickstart-enterprise-search.md @@ -0,0 +1,113 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-enterprise-search-quickstart.html +--- + +# Quickstart [k8s-enterprise-search-quickstart] + +1. Apply the following specification to deploy Enterprise Search. ECK automatically configures the secured connection to an Elasticsearch cluster named `quickstart`, created in [Elasticsearch quickstart](deploy-an-orchestrator.md). + + ```yaml + cat < + --- + apiVersion: agent.k8s.elastic.co/v1alpha1 + kind: Agent + metadata: + name: elastic-agent-quickstart + namespace: default + spec: + version: 8.16.1 + kibanaRef: + name: kibana-quickstart + fleetServerRef: + name: fleet-server-quickstart + mode: fleet + policyID: eck-agent + daemonSet: + podTemplate: + spec: + serviceAccountName: elastic-agent + automountServiceAccountToken: true + securityContext: + runAsUser: 0 <1> + volumes: + - name: agent-data + emptyDir: {} + --- + apiVersion: kibana.k8s.elastic.co/v1 + kind: Kibana + metadata: + name: kibana-quickstart + namespace: default + spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: elasticsearch-quickstart + config: + xpack.fleet.agents.elasticsearch.hosts: ["https://elasticsearch-quickstart-es-http.default.svc:9200"] + xpack.fleet.agents.fleet_server.hosts: ["https://fleet-server-quickstart-agent-http.default.svc:8220"] + xpack.fleet.packages: + - name: system + version: latest + - name: elastic_agent + version: latest + - name: fleet_server + version: latest + xpack.fleet.agentPolicies: + - name: Fleet Server on ECK policy + id: eck-fleet-server + namespace: default + is_managed: true + monitoring_enabled: + - logs + - metrics + unenroll_timeout: 900 + package_policies: + - name: fleet_server-1 + id: fleet_server-1 + package: + name: fleet_server + - name: Elastic Agent on ECK policy + id: eck-agent + namespace: default + is_managed: true + monitoring_enabled: + - logs + - metrics + unenroll_timeout: 900 + package_policies: + - name: system-1 + id: system-1 + package: + name: system + --- + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: elasticsearch-quickstart + namespace: default + spec: + version: 8.16.1 + nodeSets: + - name: default + count: 3 + config: + node.store.allow_mmap: false + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: elastic-agent + rules: + - apiGroups: [""] # "" indicates the core API group + resources: + - pods + - nodes + - namespaces + verbs: + - get + - watch + - list + - apiGroups: ["coordination.k8s.io"] + resources: + - leases + verbs: + - get + - create + - update + - apiGroups: ["apps"] + resources: + - replicasets + verbs: + - list + - watch + - apiGroups: ["batch"] + resources: + - jobs + verbs: + - list + - watch + --- + apiVersion: v1 + kind: ServiceAccount + metadata: + name: elastic-agent + namespace: default + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: elastic-agent + subjects: + - kind: ServiceAccount + name: elastic-agent + namespace: default + roleRef: + kind: ClusterRole + name: elastic-agent + apiGroup: rbac.authorization.k8s.io + EOF + ``` + + 1. The root user is required to persist state in a hostPath volume and to trust the {{es}} CA in {{fleet}} mode. See [Storing local state in host path volume](configuration-examples-standalone.md#k8s_storing_local_state_in_host_path_volume) for options to not run the Agent container as root. + + + Check [Configuration Examples](configuration-examples-fleet.md) for more ready-to-use manifests. + + +ECK automatically configures secure connections between all components. {{fleet}} will be set up, and all agents are enrolled in the default policy. + +1. Monitor the status of {{fleet-server}} and {{agent}}. + + ```sh + kubectl get agent + ``` + + ```sh + NAME HEALTH AVAILABLE EXPECTED VERSION AGE + elastic-agent-quickstart green 3 3 8.16.1 14s + fleet-server-quickstart green 1 1 8.16.1 19s + ``` + +2. List all the Pods belonging to a given {{agent}} specification. + + ```sh + kubectl get pods --selector='agent.k8s.elastic.co/name=elastic-agent-quickstart' + ``` + + ```sh + NAME READY STATUS RESTARTS AGE + elastic-agent-quickstart-agent-t49fd 1/1 Running 0 54s + elastic-agent-quickstart-agent-xbcxr 1/1 Running 0 54s + elastic-agent-quickstart-agent-zqp55 1/1 Running 0 54s + ``` + +3. Access logs for one of the Pods. + + ```sh + kubectl logs -f elastic-agent-quickstart-agent-xbcxr + ``` + +4. Configure the policy used by {{agents}}. Check [{{agent}} policies](https://www.elastic.co/guide/en/fleet/current/agent-policy.html) for more details. + diff --git a/deploy-manage/deploy/cloud-on-k8s/quickstart-logstash.md b/deploy-manage/deploy/cloud-on-k8s/quickstart-logstash.md new file mode 100644 index 000000000..396875dde --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/quickstart-logstash.md @@ -0,0 +1,80 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-logstash-quickstart.html +--- + +# Quickstart [k8s-logstash-quickstart] + +Add the following specification to create a minimal {{ls}} deployment that will listen to a Beats agent or Elastic Agent configured to send to Logstash on port 5044, create the service and write the output to an Elasticsearch cluster named `quickstart`, created in the [Elasticsearch quickstart](deploy-an-orchestrator.md). + +```yaml +cat <<'EOF' | kubectl apply -f - +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: quickstart +spec: + count: 1 + elasticsearchRefs: + - name: quickstart + clusterName: qs + version: 8.16.1 + pipelines: + - pipeline.id: main + config.string: | + input { + beats { + port => 5044 + } + } + output { + elasticsearch { + hosts => [ "${QS_ES_HOSTS}" ] + user => "${QS_ES_USER}" + password => "${QS_ES_PASSWORD}" + ssl_certificate_authorities => "${QS_ES_SSL_CERTIFICATE_AUTHORITY}" + } + } + services: + - name: beats + service: + spec: + type: NodePort + ports: + - port: 5044 + name: "filebeat" + protocol: TCP + targetPort: 5044 +EOF +``` + +Check [Configuration examples](configuration-examples-logstash.md) for more ready-to-use manifests. + +1. Check the status of Logstash + + ```sh + kubectl get logstash + ``` + + ```sh + NAME AVAILABLE EXPECTED AGE VERSION + quickstart 3 3 4s 8.16.1 + ``` + +2. List all the Pods that belong to a given Logstash specification. + + ```sh + kubectl get pods --selector='logstash.k8s.elastic.co/name=quickstart' + ``` + + ```sh + NAME READY STATUS RESTARTS AGE + quickstart-ls-0 1/1 Running 0 91s + ``` + +3. Access logs for a Pod. + +```sh +kubectl logs -f quickstart-ls-0 +``` + diff --git a/deploy-manage/deploy/cloud-on-k8s/quickstart-standalone.md b/deploy-manage/deploy/cloud-on-k8s/quickstart-standalone.md new file mode 100644 index 000000000..e2144da96 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/quickstart-standalone.md @@ -0,0 +1,98 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent-quickstart.html +--- + +# Quickstart [k8s-elastic-agent-quickstart] + +1. Apply the following specification to deploy Elastic Agent with the System metrics integration to harvest CPU metrics from the Agent Pods. ECK automatically configures the secured connection to an Elasticsearch cluster named `quickstart`, created in the [Elasticsearch quickstart](deploy-an-orchestrator.md). + + ```yaml + cat < + config: + inputs: + - name: system-1 + revision: 1 + type: system/metrics + use_output: default + meta: + package: + name: system + version: 0.9.1 + data_stream: + namespace: default + streams: + - id: system/metrics-system.cpu + data_stream: + dataset: system.cpu + type: metrics + metricsets: + - cpu + cpu.metrics: + - percentages + - normalized_percentages + period: 10s + EOF + ``` + + 1. The root user is required to persist state in a `hostPath` volume. See [Storing local state in host path volume](configuration-examples-standalone.md#k8s_storing_local_state_in_host_path_volume) for options to not run the Agent container as root. + + + Check [Configuration examples](configuration-examples-standalone.md) for more ready-to-use manifests. + +2. Monitor the status of Elastic Agent. + + ```sh + kubectl get agent + ``` + + ```sh + NAME HEALTH AVAILABLE EXPECTED VERSION AGE + quickstart green 3 3 8.16.1 15s + ``` + +3. List all the Pods that belong to a given Elastic Agent specification. + + ```sh + kubectl get pods --selector='agent.k8s.elastic.co/name=quickstart' + ``` + + ```sh + NAME READY STATUS RESTARTS AGE + quickstart-agent-6bcxr 1/1 Running 0 68s + quickstart-agent-t49fd 1/1 Running 0 68s + quickstart-agent-zqp55 1/1 Running 0 68s + ``` + +4. Access logs for one of the Pods. + + ```sh + kubectl logs -f quickstart-agent-6bcxr + ``` + +5. Access the CPU metrics ingested by Elastic Agent. + + You have two options: + + * Follow the Elasticsearch deployment [guide](elasticsearch-deployment-quickstart.md) and run: + + ```sh + curl -u "elastic:$PASSWORD" -k "https://localhost:9200/metrics-system.cpu-*/_search" + ``` + + * Follow the Kibana deployment [guide](kibana-instance-quickstart.md), log in and go to **Kibana** > **Discover**. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/readiness-probe.md b/deploy-manage/deploy/cloud-on-k8s/readiness-probe.md new file mode 100644 index 000000000..93454872c --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/readiness-probe.md @@ -0,0 +1,47 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-readiness.html +--- + +# Readiness probe [k8s-readiness] + +## Elasticsearch versions before 8.2.0 [k8s_elasticsearch_versions_before_8_2_0] + +By default, the readiness probe checks that the Pod responds to HTTP requests within a timeout of three seconds. This is acceptable in most cases. However, when the cluster is under heavy load, you might need to increase the timeout. This allows the Pod to stay in a `Ready` state and be part of the Elasticsearch service even if it is responding slowly. To adjust the timeout, set the `READINESS_PROBE_TIMEOUT` environment variable in the Pod template and update the readiness probe configuration with the new timeout. + +This example describes how to increase the API call timeout to ten seconds and the overall check time to twelve seconds: + +```yaml +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + podTemplate: + spec: + containers: + - name: elasticsearch + readinessProbe: + exec: + command: + - bash + - -c + - /mnt/elastic-internal/scripts/readiness-probe-script.sh + failureThreshold: 3 + initialDelaySeconds: 10 + periodSeconds: 12 + successThreshold: 1 + timeoutSeconds: 12 + env: + - name: READINESS_PROBE_TIMEOUT + value: "10" +``` + +Note that this requires restarting the Pods. + + +## Elasticsearch versions 8.2.0 and later [k8s_elasticsearch_versions_8_2_0_and_later] + +We do not recommend overriding the default readiness probe on Elasticsearch 8.2.0 and later. ECK configures a socket based readiness probe using the Elasticsearch [readiness port feature](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#readiness-tcp-port) which is not influenced by the load on the Elasticsearch cluster. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/recipes.md b/deploy-manage/deploy/cloud-on-k8s/recipes.md new file mode 100644 index 000000000..3fd402848 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/recipes.md @@ -0,0 +1,22 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-recipes.html +--- + +# Recipes [k8s-recipes] + +This section includes recipes that provide configuration examples for some common use cases. + +* [Expose Elasticsearch and Kibana using a Google Cloud Load Balancer (GCLB)](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/gclb) +* [Expose Elasticsearch and Kibana using Istio ingress gateway](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/istio-gateway) +* [Using Logstash with ECK](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/logstash) +* [Expose Elastic Maps Server and Kibana using a Kubernetes Ingress](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/maps) +* [Secure your cluster with Pod Security Policies](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/psp) +* [Use Traefik to expose Elastic Stack applications](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/traefik) +* [Deploy Elasticsearch, Kibana, Elastic Fleet Server and Elastic Agent within GKE Autopilot](https://github.com/elastic/cloud-on-k8s/tree/main/config/recipes/autopilot) + +::::{warning} +Compared to other configuration examples that are consistently tested, like [fleet-managed Elastic Agent on ECK](configuration-examples-fleet.md), [standalone Elastic Agent on ECK](configuration-examples-standalone.md), or [Beats on ECK](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-beat-configuration-examples.html), the recipes in this section are not regularly tested by our automation system, and therefore should not be considered to be production-ready. +:::: + + diff --git a/deploy-manage/deploy/cloud-on-k8s/requests-routing-to-elasticsearch-nodes.md b/deploy-manage/deploy/cloud-on-k8s/requests-routing-to-elasticsearch-nodes.md new file mode 100644 index 000000000..1b5ac483b --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/requests-routing-to-elasticsearch-nodes.md @@ -0,0 +1,131 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-traffic-splitting.html +--- + +# Requests routing to Elasticsearch nodes [k8s-traffic-splitting] + +The default Kubernetes service created by ECK, named `-es-http`, is configured to include all the Elasticsearch nodes in that cluster. This configuration is good to get started and is adequate for most use cases. However, if you are operating an Elasticsearch cluster with [different node types](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html) and want control over which nodes handle which types of traffic, you should create additional Kubernetes services yourself. + +As an alternative, you can use features provided by third-party software such as service meshes and ingress controllers to achieve more advanced traffic management configurations. Check the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/2.16/config/recipes) in the ECK source repository for a few examples. + +The service configurations shown in these sections are based on the following Elasticsearch cluster definition: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: hulk +spec: + version: 8.16.1 + nodeSets: + # Dedicated master nodes + - name: master + count: 3 + config: + node.roles: ["master"] + # Dedicated data nodes + - name: data + count: 6 + config: + node.roles: ["data"] + # Dedicated ingest nodes + - name: ingest + count: 3 + config: + node.roles: ["ingest"] + # Dedicated coordinating nodes + - name: coordinating + count: 3 + config: + node.roles: [] + # Dedicated machine learning nodes + - name: ml + count: 3 + config: + node.roles: ["ml"] + # Dedicated transform nodes + - name: transform + count: 3 + config: + node.roles: ["transform"] +``` + + +## Create services for exposing different node types [k8s-traffic-splitting-by-node-type] + +The following examples illustrate how to create services for accessing different types of Elasticsearch nodes. The procedure for exposing services publicly is the same as described in [Allow public access](accessing-services.md#k8s-allow-public-access). + +$$$k8s-traffic-splitting-coordinating-nodes$$$ + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hulk-es-coordinating-nodes +spec: + ports: + - name: https + port: 9200 + targetPort: 9200 + selector: + elasticsearch.k8s.elastic.co/cluster-name: "hulk" + elasticsearch.k8s.elastic.co/node-master: "false" + elasticsearch.k8s.elastic.co/node-data: "false" + elasticsearch.k8s.elastic.co/node-ingest: "false" + elasticsearch.k8s.elastic.co/node-ml: "false" + elasticsearch.k8s.elastic.co/node-transform: "false" +``` + +$$$k8s-traffic-splitting-ingest-nodes$$$ + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hulk-es-ingest-nodes +spec: + ports: + - name: https + port: 9200 + targetPort: 9200 + selector: + elasticsearch.k8s.elastic.co/cluster-name: "hulk" + elasticsearch.k8s.elastic.co/node-ingest: "true" +``` + +$$$k8s-traffic-splitting-non-master-nodes$$$ + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hulk-es-non-master-nodes +spec: + ports: + - name: https + port: 9200 + targetPort: 9200 + selector: + elasticsearch.k8s.elastic.co/cluster-name: "hulk" + elasticsearch.k8s.elastic.co/node-master: "false" +``` + + +## Specify a custom service in elasticsearchRef [k8s-traffic-splitting-with-service-name] + +You can then use your custom service in the `elasticsearchRef` element when specifying connections between Elasticsearch and other stack applications. This is an example on how to target only coordinating node from Kibana: + +```yaml +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +metadata: + name: hulk +spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: "hulk" + serviceName: "hulk-es-coordinating-nodes" +``` + diff --git a/deploy-manage/deploy/cloud-on-k8s/required-rbac-permissions.md b/deploy-manage/deploy/cloud-on-k8s/required-rbac-permissions.md new file mode 100644 index 000000000..27bedd92d --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/required-rbac-permissions.md @@ -0,0 +1,81 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-eck-permissions.html +--- + +# Required RBAC permissions [k8s-eck-permissions] + +Installing and running ECK, as well as using ECK-managed resources requires the following Kubernetes [permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac): + +* [Installing CRDs](#k8s-eck-permissions-installing-crds) +* [Installing the ECK operator](#k8s-eck-permissions-installing-operator) +* [Running ECK operator](#k8s-eck-permissions-running) +* [Using ECK-managed resources](#k8s-eck-permissions-using) + + +## Installing CRDs [k8s-eck-permissions-installing-crds] + +This permission is required to install CRDs. CRDs ([CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)) are the only non-namespaced resources required to be installed. + +| Name | API group | Optional? | Usage | +| --- | --- | --- | --- | +| `CustomResourceDefinition` | `apiextensions.k8s.io` | no | Extend Kubernetes APIs with Elastic Stack application resources. | + + +## Installing the ECK operator [k8s-eck-permissions-installing-operator] + +These permissions are required to install the ECK operator in a Kubernetes cluster. + +| Name | API group | Optional? | Usage | +| --- | --- | --- | --- | +| `StatefulSet or Deployment` | `apps` | no | The ECK operator can be either deployed as a StatefulSet or as a Deployment. | +| `ServiceAccount` | `core` | no | Service account that the operator Pods run as. | +| `Role or ClusterRole` | `rbac.authorization.k8s.io` | no | Role bound to the operators Service account. Depending on the installation type (global/restricted) either a global (ClusterRole) or a namespaced (Role) resource is needed. | +| `RoleBinding or ClusterRoleBinding` | `rbac.authorization.k8s.io` | no | Binding between the operators role and the operators service account. Depending on the installation type (global/restricted), either global (ClusterRoleBinding) or namespaced (RoleBinding) resource is needed. | +| `ConfigMap` | `core` | yes | Configuration parameters of the Operator. They can be specified directly in the StatefulSet (or Deployment) resource instead. | +| `Namespace` | `core` | yes | Namespace where the operator will run. It can be a pre-existing namespace as well. | +| `ValidatingWebhookConfiguration` | `admissionregistration.k8s.io` | yes | Validating webhook installation. It provides fast feedback for the user directly as a APIServer response. A subset of these validations is also run by the operator itself, but the results are only available through operator logs and Kubernetes events. Check [docs](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-webhook.html) for more. | +| `Secret` | `core` | yes | Secret containing the validating webhook’s endpoint CA certificate. | +| `Service` | `core` | yes | Service for validating webhook endpoint. | + +And all permissions that [Running ECK operator](#k8s-eck-permissions-running) section specifies. + + +## Running ECK operator [k8s-eck-permissions-running] + +These permissions are needed by the Service Account that ECK operator runs as. + +| Name | API group | Optional? | Usage | +| --- | --- | --- | --- | +| `Pod` | | no | Assuring expected Pods presence during Elasticsearch reconciliation, safely deleting Pods during configuration changes and validating `podTemplate` by dry-run creation of Pods. | +| `Endpoint` | | no | Checking availability of service endpoints. | +| `Event` | | no | Emitting events concerning reconciliation progress and issues. | +| `PersistentVolumeClaim` | | no | Expanding existing volumes. Check [docs](volume-claim-templates.md#k8s-volume-claim-templates-update) to learn more. | +| `Secret` | | no | Reading/writing configuration, passwords, certificates, and so on. | +| `Service` | | no | Creating Services fronting Elastic Stack applications. | +| `ConfigMap` | | no | Reading/writing configuration. | +| `StatefulSet` | `apps` | no | Deploying Elasticsearch | +| `Deployment` | `apps` | no | Deploying Kibana, APM Server, EnterpriseSearch, Maps, Beats or Elastic Agent. | +| `DaemonSet` | `apps` | no | Deploying Beats or Elastic Agent. | +| `PodDisruptionBudget` | `policy` | no | Ensuring update safety for Elasticsearch. Check [docs](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-pod-disruption-budget.html) to learn more. | +| `StorageClass` | `storage.k8s.io` | yes | Validating storage expansion support. Check [docs](volume-claim-templates.md#k8s-volume-claim-templates-update) to learn more. | +| `coreauthorization.k8s.io` | `SubjectAccessReview` | yes | Controlling access between referenced resources. Check [docs](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-restrict-cross-namespace-associations.html) to learn more. | + +And all permissions that the [Using ECK-managed resources](#k8s-eck-permissions-using) chapter specifies. + + +## Using ECK-managed resources [k8s-eck-permissions-using] + +These permissions are needed to manage each Elastic Stack application. For example, to create, update and delete Elasticsearch clusters the permissions for the respective verbs must be held by the user that performs the operation. + +| Name | API group | Optional? | +| --- | --- | --- | +| `Elasticsearch
Elasticsearch/status
Elasticsearch/finalizers` | `elasticsearch.k8s.elastic.co` | no | +| `Kibana
Kibana/status
Kibana/finalizers` | `kibana.k8s.elastic.co` | no | +| `APMServer
APMServer/status
APMServer/finalizers` | `apm.k8s.elastic.co` | no | +| `EnterpriseSearch
EnterpriseSearch/status
EnterpriseSearch/finalizers` | `enterprisesearch.k8s.elastic.co` | no | +| `Beat
Beat/status
Beat/finalizers` | `beat.k8s.elastic.co` | no | +| `Agent
Agent/status
Agent/finalizers` | `agent.k8s.elastic.co` | no | +| `ElasticMapsServer
ElasticMapsServer/status
ElasticMapsServer/finalizers` | `maps.k8s.elastic.co` | no | +| `Logstash
Logstash/status
Logstash/finalizers` | `logstashes.k8s.elastic.co` | no | + diff --git a/deploy-manage/deploy/cloud-on-k8s/restrict-cross-namespace-resource-associations.md b/deploy-manage/deploy/cloud-on-k8s/restrict-cross-namespace-resource-associations.md new file mode 100644 index 000000000..1f279f6f9 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/restrict-cross-namespace-resource-associations.md @@ -0,0 +1,87 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-restrict-cross-namespace-associations.html +--- + +# Restrict cross-namespace resource associations [k8s-restrict-cross-namespace-associations] + +This section describes how to restrict associations that can be created between resources managed by ECK. + +When using the `elasticsearchRef` field to establish a connection to Elasticsearch from Kibana, APM Server, Enterprise Search, or Beats resources, by default the association is allowed as long as both resources are deployed to namespaces managed by that particular ECK instance. The association will succeed even if the user creating the association does not have access to one of the namespaces or the Elasticsearch resource. + +The enforcement of access control rules for cross-namespace associations is disabled by default. Once enabled, it only enforces access control for resources deployed across two different namespaces. Associations between resources deployed in the same namespace are not affected. + +Associations are allowed as long as the `ServiceAccount` used by the associated resource can execute HTTP `GET` requests against the referenced Elasticsearch object. + +::::{important} +ECK automatically removes any associations that do not have the correct access rights. If you have existing associations, do not enable this feature without creating the required `Roles` and `RoleBindings` as described in the following sections. +:::: + + +To enable the restriction of cross-namespace associations, start the operator with the `--enforce-rbac-on-refs` flag. + +1. Create a `ClusterRole` to allow HTTP `GET` requests to be run against Elasticsearch objects: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: elasticsearch-association + rules: + - apiGroups: + - elasticsearch.k8s.elastic.co + resources: + - elasticsearches + verbs: + - get + ``` + +2. Create a `ServiceAccount` and a `RoleBinding` in the Elasticsearch namespace to allow any resource using the `ServiceAccount` to associate with the Elasticsearch cluster: + + ```sh + > kubectl create serviceaccount associated-resource-sa + ``` + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: RoleBinding + metadata: + name: allow-associated-resource-from-remote-namespace + namespace: elasticsearch-ns + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: elasticsearch-association + subjects: + - kind: ServiceAccount + name: associated-resource-sa + namespace: associated-resource-ns + ``` + +3. Set the `serviceAccountName` field in the associated resource to specify which `ServiceAccount` is used to create the association: + + ```yaml + apiVersion: kibana.k8s.elastic.co/v1 + kind: Kibana + metadata: + name: associated-resource + namespace: associated-resource-ns + spec: + ... + elasticsearchRef: + name: "elasticsearch-sample" + namespace: "elasticsearch-ns" + # Service account used by this resource to get access to an Elasticsearch cluster + serviceAccountName: associated-resource-sa + ``` + + +In this example, `associated-resource` can be of any `Kind` that requires an association to be created, for example `Kibana` or `ApmServer`. You can find [a complete example in the ECK GitHub repository](https://github.com/elastic/cloud-on-k8s/blob/2.16/config/recipes/associations-rbac/apm_es_kibana_rbac.yaml). + +::::{note} +If the `serviceAccountName` is not set, ECK uses the default service account assigned to the pod by the [Service Account Admission Controller](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/#service-account-admission-controller). +:::: + + +The associated resource `associated-resource` is now allowed to create an association with any Elasticsearch cluster in the namespace `elasticsearch-ns`. + diff --git a/deploy-manage/deploy/cloud-on-k8s/securing-logstash-api.md b/deploy-manage/deploy/cloud-on-k8s/securing-logstash-api.md new file mode 100644 index 000000000..421346f41 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/securing-logstash-api.md @@ -0,0 +1,119 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-logstash-securing-api.html +--- + +# Securing Logstash API [k8s-logstash-securing-api] + +## Enable HTTPS [k8s-logstash-https] + +Access to the [Logstash Monitoring APIs](https://www.elastic.co/guide/en/logstash/current/monitoring-logstash.html#monitoring-api-security) use HTTPS by default - the operator will set the values `api.ssl.enabled: true`, `api.ssl.keystore.path` and `api.ssl.keystore.password`. + +You can further secure the {{ls}} Monitoring APIs by requiring HTTP Basic authentication by setting `api.auth.type: basic`, and providing the relevant credentials `api.auth.basic.username` and `api.auth.basic.password`: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: logstash-api-secret +stringData: + API_USERNAME: "AWESOME_USER" <1> + API_PASSWORD: "T0p_Secret" <1> +--- +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash-sample +spec: + version: 8.16.1 + count: 1 + config: + api.auth.type: basic + api.auth.basic.username: "${API_USERNAME}" <3> + api.auth.basic.password: "${API_PASSWORD}" <3> + podTemplate: + spec: + containers: + - name: logstash + envFrom: + - secretRef: + name: logstash-api-secret <2> +``` + +1. Store the username and password in a Secret. +2. Map the username and password to the environment variables of the Pod. +3. At Logstash startup, `${API_USERNAME}` and `${API_PASSWORD}` are replaced by the value of environment variables. Check [using environment variables](https://www.elastic.co/guide/en/logstash/current/environment-variables.html) for more details. + + +An alternative is to set up [keystore](advanced-configuration-logstash.md#k8s-logstash-keystore) to resolve `${API_USERNAME}` and `${API_PASSWORD}` + +::::{note} +The variable substitution in `config` does not support the default value syntax. +:::: + + + +## TLS keystore [k8s-logstash-http-tls-keystore] + +The TLS Keystore is automatically generated and includes a certificate and a private key, with default password protection set to `changeit`. This password can be modified by configuring the `api.ssl.keystore.password` value. + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash-sample +spec: + count: 1 + version: 8.16.1 + config: + api.ssl.keystore.password: "${SSL_KEYSTORE_PASSWORD}" +``` + + +## Provide your own certificate [k8s-logstash-http-custom-tls] + +If you want to use your own certificate, the required configuration is similar to Elasticsearch. Configure the certificate in `api` Service. Check [Custom HTTP certificate](../../security/secure-http-communications.md). + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash-sample +spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: "elasticsearch-sample" + services: + - name: api <1> + tls: + certificate: + secretName: my-cert +``` + +1. The service name `api` is reserved for {{ls}} monitoring endpoint. + + + +## Disable TLS [k8s-logstash-http-disable-tls] + +You can disable TLS by disabling the generation of the self-signed certificate in the API service definition + +```yaml +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: logstash-sample +spec: + version: 8.16.1 + count: 1 + elasticsearchRef: + name: "elasticsearch-sample" + services: + - name: api + tls: + selfSignedCertificate: + disabled: true +``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/security-context.md b/deploy-manage/deploy/cloud-on-k8s/security-context.md new file mode 100644 index 000000000..cc8460d7c --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/security-context.md @@ -0,0 +1,65 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-security-context.html +--- + +# Security context [k8s-security-context] + +In Kubernetes, a [`securityContext`](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) defines privilege and access control settings for a Pod or Container. You can set up it through the `podTemplate` section of an Elastic resource specification. + +## Default Elasticsearch security context [k8s_default_elasticsearch_security_context] + +As of version 8.8.0, the Elasticsearch container and ECK managed sidecars and init containers are running with the following security context: + +```yaml +securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: + - ALL + privileged: false + readOnlyRootFilesystem: true <1> +``` + +1. `readOnlyRootFilesystem` is only enabled if the `elasticsearch-data` directory is mounted in a volume. + + + +## Running older versions of Elasticsearch as non-root [k8s_running_older_versions_of_elasticsearch_as_non_root] + +::::{note} +when running on Red Hat OpenShift a random user ID is [automatically assigned](https://cloud.redhat.com/blog/a-guide-to-openshift-and-uids) and the following instructions do not apply. +:::: + + +In versions of Elasticsearch before 8.0.0, the Elastisearch container is run as root and its entrypoint is responsible to run the Elasticsearch process with the `elasticsearch` user (defined with ID 1000). In the background, ECK uses an `initContainer` to make sure that the data volume is writable for the `elasticsearch` user. + +To run the Elastisearch container as a non-root user, you need to configure the Elasticsearch manifest with an appropriate security context to make the data volume writable to the `elasticsearch` user by specifying the right group ID through the `fsGroup`. + +Kubernetes recursively changes ownership and permissions for the contents of each volume to match the `fsGroup` specified in a Pod’s securityContext when that volume is mounted and makes all processes of the containers part of the supplementary group ID. + +For example, if you force the Pod to run as user `1234`, you need to set `fsGroup` accordingly to `1234`: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 +spec: + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + securityContext: + runAsUser: 1234 <1> + fsGroup: 1234 <2> +``` + +1. Any containers in the Pod run all processes with user ID `1234`. +2. All processes are also part of the supplementary group ID `1234`, that owns the Pod volumes. + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/service-meshes.md b/deploy-manage/deploy/cloud-on-k8s/service-meshes.md new file mode 100644 index 000000000..1c943134a --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/service-meshes.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-service-meshes.html +--- + +# Service meshes [k8s-service-meshes] + +You can connect ECK and managed Elastic Stack applications to some of the most popular [service mesh](https://www.cncf.io/blog/2017/04/26/service-mesh-critical-component-cloud-native-stack/) implementations in the Kubernetes ecosystem: + +* [Istio](k8s-service-mesh-istio.md) +* [Linkerd](k8s-service-mesh-linkerd.md) + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/settings-managed-by-eck.md b/deploy-manage/deploy/cloud-on-k8s/settings-managed-by-eck.md new file mode 100644 index 000000000..58b6e22bb --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/settings-managed-by-eck.md @@ -0,0 +1,33 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-reserved-settings.html +--- + +# Settings managed by ECK [k8s-reserved-settings] + +The following Elasticsearch settings are managed by ECK: + +* `cluster.name` +* `discovery.seed_hosts` +* `discovery.seed_providers` +* `discovery.zen.minimum_master_nodes` [7.0] +* `cluster.initial_master_nodes` [7.0] +* `network.host` +* `network.publish_host` +* `path.data` +* `path.logs` +* `xpack.security.authc.reserved_realm.enabled` +* `xpack.security.enabled` +* `xpack.security.http.ssl.certificate` +* `xpack.security.http.ssl.enabled` +* `xpack.security.http.ssl.key` +* `xpack.security.transport.ssl.enabled` +* `xpack.security.transport.ssl.verification_mode` + +The following Elasticsearch settings are not supported by ECK: + +* `xpack.security.http.ssl.client_authentication`: `required` + +::::{warning} +It is not recommended to change these ECK settings. We don’t support user-provided Elasticsearch configurations that use any of these settings. +:::: diff --git a/deploy-manage/deploy/cloud-on-k8s/standalone-elastic-agent.md b/deploy-manage/deploy/cloud-on-k8s/standalone-elastic-agent.md new file mode 100644 index 000000000..7f597dec2 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/standalone-elastic-agent.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elastic-agent.html +--- + +# Standalone Elastic Agent [k8s-elastic-agent] + +This section describes how to configure and deploy Elastic Agent in [standalone mode](https://www.elastic.co/guide/en/fleet/current/install-standalone-elastic-agent.html) with ECK. Check the [Fleet section](fleet-managed-elastic-agent.md) if you want to manage your Elastic Agents with [Fleet](https://www.elastic.co/guide/en/fleet/current/elastic-agent-installation.html). + +* [Quickstart](quickstart-standalone.md) +* [Configuration](configuration-standalone.md) +* [Configuration examples](configuration-examples-standalone.md) + +::::{note} +Running standalone Elastic Agent on ECK is compatible only with Stack versions 7.10+. +:::: + + + + + diff --git a/deploy-manage/deploy/cloud-on-k8s/storage-recommendations.md b/deploy-manage/deploy/cloud-on-k8s/storage-recommendations.md new file mode 100644 index 000000000..0505593e0 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/storage-recommendations.md @@ -0,0 +1,59 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-storage-recommendations.html +--- + +# Storage recommendations [k8s-storage-recommendations] + +ECK does not come with its own storage mechanism for Elasticsearch data. It is compatible with any Kubernetes storage option. It is recommended to use PersistentVolumes, by configuring the [VolumeClaimTemplates](volume-claim-templates.md) section of the Elasticsearch resource. + +Multiple PersistentVolume storage classes are available, depending on your Kubernetes setup. Their specifications impact Elasticsearch performance and operations. Evaluate the trade-offs among the various options and choose the solution that best fits your needs. + + +## Network-attached or Local PersistentVolumes [k8s_network_attached_or_local_persistentvolumes] + +PersistentVolumes can be of two types: **Network-attached** or **Local**. ECK handles them in the same way, but they have different performance, price and operational characteristics. + +* **Network-attached PersistentVolumes** can generally be attached to a Pod regardless of the host they are scheduled on. They provide a major operational benefit: if the host goes down, or needs to be replaced, the Pod can simply be deleted. Kubernetes reschedules it automatically on a different host, generally in the same region, and reattaches the same volume. This can take only a few seconds, and does not require any human intervention. +* **Local PersistentVolumes** are bound to a particular host, and map a directory on the filesystem. They provide a major operational overhead: once bound to a Local PersistentVolume, a Pod can only be scheduled on the same host. If that host goes down, or needs to be replaced, the Pod cannot be scheduled on a different host. It remains in a `Pending` state until the host is available, or until the PersistentVolumeClaim is manually deleted. For that reason, Local PersistentVolumes bring more operational overhead. + +In both cases, the performance depends on the underlying hardware and implementation. In general, local SSDs give the best performance. The fastest network-attached volumes from major Cloud providers can also provide acceptable performance, depending on your Elasticsearch use cases. To better evaluate your performance requirements, you can [benchmark](https://github.com/elastic/rally) your storage options against the expected Elasticsearch usage. + + +## Local PersistentVolumes operations [k8s_local_persistentvolumes_operations] + + +### Host maintenance [k8s_host_maintenance] + +To take a host out of the Kubernetes cluster temporarily, it is common to cordon, then drain it. Kubernetes deletes Elasticsearch Pods scheduled on that host automatically, as long as the [PodDisruptionBudget](pod-disruption-budget.md) allows it. By default, ECK manages a PodDisruptionBudget that allows one Pod to be taken down, as long as the cluster has a green health. Once deleted, that Pod cannot be scheduled again on the cordoned host: the Pod stays `Pending`, waiting for that host to come back online. The next Pod can be automatically deleted when the Elasticsearch cluster health becomes green again. + +Some hosted Kubernetes offerings only respect the PodDisruptionBudget for a certain amount of time, before killing all Pods on the node. For example, [GKE automated version upgrade](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-upgrades) rotates all nodes without preserving local volumes, and respects the PodDisruptionBudget for a maximum of one hour. In such cases it is preferable to [manually handle the cluster version upgrade](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-upgrades#upgrading_manually). + + +### Host removal [k8s_host_removal] + +If a host has a failure, or is permanently removed, its local data is likely lost. The corresponding Pod stays `Pending` because it can no longer attach the PersistentVolume. To schedule the Pod on a different host with a new empty volume, you have to manually remove both the PersistenteVolumeClaim and the Pod. A new Pod is automatically created with a new PersistentVolumeClaim, which is then matched with a PersistentVolume. Then, Elasticsearch shard replication makes sure that data is recovered on the new instance. + + +## Local PersistentVolume provisioners [k8s_local_persistentvolume_provisioners] + +You can provision Local PersistentVolumes in one of the following ways: + +* **Manual provisioning**: Manually [create PersistentVolume resources](https://kubernetes.io/blog/2018/04/13/local-persistent-volumes-beta/#creating-a-local-persistent-volume), matching a local path to a specific host. Data must be manually removed once the PersistentVolumes are released. +* **Static provisioning**: Run a program that automatically discovers the existing partitions on each host, and creates the corresponding PersistentVolume resources. The [Local PersistentVolume Static Provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner) is a great way to get started. +* **Dynamic provisioning**: [OpenEBS](https://openebs.io) and [TopoLVM](https://github.com/topolvm/topolvm) are examples of components you can install into your Kubernetes cluster to manage the provisioning of persistent volumes from local disks attached to the nodes. These tools leverage technologies like LVM and ZFS to dynamically allocate persistent volumes from storage pools made out of local disks. Depending on the technology used, bonus features like dynamic volume resizing, thin-provisioning and, snapshots are also available with some of these offerings. Installation of these components might require initial setup work on your Kubernetes cluster like installing filesystem utilities on all nodes, creating RAID configurations for the disks or even installing API extensions like custom schedulers. Some managed Kubernetes offerings might have restrictions that make it difficult to perform some of those setup steps. Check the documentation of the Kubernetes provider and the storage provisioner to ensure that they are compatible with each other. + + +## Storage class settings [k8s_storage_class_settings] + + +### volumeBindingMode: WaitForFirstConsumer [k8s_volumebindingmode_waitforfirstconsumer] + +In the PersistentVolume StorageClass, it is important to set [`volumeBindingMode: WaitForFirstConsumer`](https://kubernetes.io/docs/concepts/storage/storage-classes/#volume-binding-mode), otherwise a Pod might be scheduled on a host that cannot access the existing PersistentVolume. This setting isn’t always applied by default on Cloud providers StorageClasses, but in most cases it is possible to create (or patch) StorageClasses to add the setting. + + +### Reclaim policy [k8s_reclaim_policy] + +The reclaim policy of a StorageClass specifies whether a PersistentVolume should be automatically deleted once its corresponding PersistentVolumeClaim is deleted. It can be set to `Delete` or `Retain`. + +ECK automatically deletes PersistentVolumeClaims when they are no longer needed, following a cluster downscale or deletion. However, ECK does not delete PersistentVolumes. The system cannot reuse a PersistentVolume with existing data from a different cluster. In this case Elasticsearch does not start, as it detects data that belongs to a different cluster. For this reason, it is recommended to use the `Delete` reclaim policy. diff --git a/deploy-manage/deploy/cloud-on-k8s/tls-certificates.md b/deploy-manage/deploy/cloud-on-k8s/tls-certificates.md new file mode 100644 index 000000000..536ae2bd3 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/tls-certificates.md @@ -0,0 +1,104 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-tls-certificates.html +--- + +# TLS Certificates [k8s-tls-certificates] + +This section only covers TLS certificates for the HTTP layer. TLS certificates for the transport layer that are used for internal communications between Elasticsearch nodes are managed by ECK and cannot be changed. You can however set your own certificate authority for the [transport layer](transport-settings.md#k8s-transport-ca). + +## Default self-signed certificate [k8s-default-self-signed-certificate] + +By default, the operator manages a self-signed certificate with a custom CA for each resource. The CA, the certificate and the private key are each stored in a separate `Secret`. + +```sh +> kubectl get secret | grep es-http +hulk-es-http-ca-internal Opaque 2 28m +hulk-es-http-certs-internal Opaque 2 28m +hulk-es-http-certs-public Opaque 1 28m +``` + +The public certificate is stored in a secret named `-[es|kb|apm|ent|agent]-http-certs-public`. + +```sh +> kubectl get secret hulk-es-http-certs-public -o go-template='{{index .data "tls.crt" | base64decode }}' +-----BEGIN CERTIFICATE----- +MIIDQDCCAiigAwIBAgIQHC4O/RWX15a3/P3upsm3djANBgkqhkiG9w0BAQsFADA6 +... +QLYL4zLEby3vRxq65+xofVBJAaM= +-----END CERTIFICATE----- +``` + +### Reserve static IP and custom domain [k8s-static-ip-custom-domain] + +To use a custom domain name with the self-signed certificate, you can reserve a static IP and/or use an Ingress instead of a `LoadBalancer` `Service`. Whatever you use, your DNS must be added to the certificate SAN in the `spec.http.tls.selfSignedCertificate.subjectAltNames` section of your Elastic resource manifest. + +```yaml +spec: + http: + service: + spec: + type: LoadBalancer + tls: + selfSignedCertificate: + subjectAltNames: + - ip: 160.46.176.15 + - dns: hulk.example.com +``` + + + +## Setup your own certificate [k8s-setting-up-your-own-certificate] + +You can bring your own certificate to configure TLS to ensure that communication between HTTP clients and the Elastic Stack application is encrypted. + +Create a Kubernetes secret with: + +* `ca.crt`: CA certificate (optional if `tls.crt` was issued by a well-known CA). +* `tls.crt`: The certificate. +* `tls.key`: The private key to the first certificate in the certificate chain. + +::::{warning} +If your `tls.crt` is signed by an intermediate CA you may need both the Root CA and the intermediate CA combined within the `ca.crt` file depending on whether the Root CA is globally trusted. +:::: + + +```sh +kubectl create secret generic my-cert --from-file=ca.crt --from-file=tls.crt --from-file=tls.key +``` + +Alternatively you can also bring your own CA certificate including a private key and let ECK issue certificates with it. Any certificate SANs you have configured as decribed in [Reserve static IP and custom domain](#k8s-static-ip-custom-domain) will also be respected when issuing certificates with this CA certificate. + +Create a Kubernetes secret with: + +* `ca.crt`: CA certificate. +* `ca.key`: The private key to the CA certificate. + +```sh +kubectl create secret generic my-cert --from-file=ca.crt --from-file=ca.key +``` + +In both cases, you have to reference the secret name in the `http.tls.certificate` section of the resource manifest. + +```yaml +spec: + http: + tls: + certificate: + secretName: my-cert +``` + + +## Disable TLS [k8s-disable-tls] + +You can explicitly disable TLS for Kibana, APM Server, Enterprise Search and the HTTP layer of Elasticsearch. + +```yaml +spec: + http: + tls: + selfSignedCertificate: + disabled: true +``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/tools-apis.md b/deploy-manage/deploy/cloud-on-k8s/tools-apis.md new file mode 100644 index 000000000..6502ce5d4 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/tools-apis.md @@ -0,0 +1,5 @@ +# Tools and APIs + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/310 \ No newline at end of file diff --git a/deploy-manage/deploy/cloud-on-k8s/transport-settings.md b/deploy-manage/deploy/cloud-on-k8s/transport-settings.md new file mode 100644 index 000000000..e8ffe945c --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/transport-settings.md @@ -0,0 +1,163 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-transport-settings.html +--- + +# Transport settings [k8s-transport-settings] + +The transport module in Elasticsearch is used for internal communication between nodes within the cluster as well as communication between remote clusters. Check the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-transport.html) for details. For customization options of the HTTP layer, check [Services](accessing-services.md) and [TLS certificates](tls-certificates.md). + +## Customize the Transport Service [k8s_customize_the_transport_service] + +In the `spec.transport.service.` section, you can change the Kubernetes service used to expose the Elasticsearch transport module: + +```yaml +spec: + transport: + service: + metadata: + labels: + my-custom: label + spec: + type: LoadBalancer +``` + +Check the [Kubernetes Publishing Services (ServiceTypes)](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) that are currently available. + +::::{note} +When you change the `clusterIP` setting of the service, ECK deletes and re-creates the service, as `clusterIP` is an immutable field. This will cause a short network disruption, but in most cases it should not affect existing connections as the transport module uses long-lived TCP connections. +:::: + + + +## Configure a custom Certificate Authority [k8s-transport-ca] + +Elasticsearch uses X.509 certificates to establish encrypted and authenticated connections across nodes in the cluster. By default, ECK creates a self-signed CA certificate to issue a certificate [for each node in the cluster](https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-tls.html#node-certificates). + +You can use a Kubernetes secret to provide your own CA instead of the self-signed certificate that ECK will then use to create node certificates for transport connections. The CA certificate must be stored in the secret under `ca.crt` and the private key must be stored under `ca.key`. + +You need to reference the name of a secret that contains the TLS private key and the CA certificate, in the `spec.transport.tls.certificate` section, as shown in this example: + +```yaml +spec: + transport: + tls: + certificate: + secretName: custom-ca +``` + + +## Customize the node transport certificates [k8s_customize_the_node_transport_certificates] + +The operator generates a self-signed TLS certificates for each node in the cluster. You can add extra IP addresses or DNS names to the generated certificates as follows: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart +spec: + version: 8.16.1 + transport: + tls: + subjectAltNames: + - ip: 1.2.3.4 + - dns: hulk.example.com + nodeSets: + - name: default + count: 3 +``` + + +## Issue node transport certificates with third-party tools [k8s-transport-third-party-tools] + +When following the instructions in [Configure a custom Certificate Authority](#k8s-transport-ca) the issuance of certificates is orchestrated by the ECK operator and the operator needs access to the CAs private key. If this is undesirable it is also possible to configure node transport certificates without involving the ECK operator. The following two pre-requisites apply: + +1. The tooling used must be able to issue individual certificates for each Elasticsearch node and dynamically add or remove certificates as the cluster scales up and down. +2. The ECK operator must be configured to be aware of the CA in use for the [remote cluster](../../remote-clusters/eck-remote-clusters.md#k8s-remote-clusters-connect-external) support to work. + +The following example configuration using [cert-manager csi-driver](https://cert-manager.io/docs/projects/csi-driver/) and [trust-manager](https://cert-manager.io/docs/projects/trust-manager/) meets these two requirements: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: es +spec: + version: 8.16.1 + transport: + tls: + certificateAuthorities: + configMapName: trust <2> + selfSignedCertificates: + disabled: true <1> + nodeSets: + - name: default + count: 3 + config: + xpack.security.transport.ssl.key: /usr/share/elasticsearch/config/cert-manager-certs/tls.key + xpack.security.transport.ssl.certificate: /usr/share/elasticsearch/config/cert-manager-certs/tls.crt + podTemplate: + spec: + containers: + - name: elasticsearch + volumeMounts: + - name: transport-certs + mountPath: /usr/share/elasticsearch/config/cert-manager-certs + volumes: + - name: transport-certs + csi: + driver: csi.cert-manager.io + readOnly: true + volumeAttributes: + csi.cert-manager.io/issuer-name: ca-cluster-issuer <2> + csi.cert-manager.io/issuer-kind: ClusterIssuer + csi.cert-manager.io/dns-names: "${POD_NAME}.${POD_NAMESPACE}.svc.cluster.local" <3> +``` + +1. Disables the self-signed certificates generated by ECK for the transport layer. +2. The example assumes that a `ClusterIssuer` by the name of `ca-cluster-issuer` exists and a PEM encoded version of the CA certificate is available in a ConfigMap (in the example named `trust`). The CA certificate must be in a file called `ca.crt` inside the ConfigMap in the same namespace as the Elasticsearch resource. +3. If the remote cluster server is enabled, then the DNS names must also include both:* The DNS name for the related Kubernetes `Service`: `-es-remote-cluster.${POD_NAMESPACE}.svc` +* The Pod DNS name: `${POD_NAME}.-es-.${POD_NAMESPACE}.svc` + + + +The following manifest is only provided to illustrate how these certificates can be configured in principle, using the trust-manager Bundle resource and cert-manager provisioned certificates: + +```yaml +apiVersion: trust.cert-manager.io/v1alpha1 +kind: Bundle +metadata: + name: trust +spec: + sources: + - secret: + name: "root-ca-secret" + key: "tls.crt" + target: + configMap: + key: "ca.crt" + +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: selfsigned-issuer +spec: + selfSigned: {} <1> +--- +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: ca-cluster-issuer +spec: + ca: + secretName: root-ca-secret +... +``` + +1. This example uses a self-signed issuer for the root CA and a second issuer for the Elasticsearch cluster transport certificates as the cert-manager CSI driver does not support self-signed CAs. + + +When transitioning from a configuration that uses externally provisioned certificates back to ECK-managed self-signed transport certificates it is important to ensure that the externally provisioned CA remains configured as a trusted CA through the `.spec.transport.tls.certificateAuthorities` attribute until all nodes in the cluster have been updated to use the ECK-managed certificates. When transitioning from ECK-managed certificates to externally provisioned ones, ECK ensures automatically that the ECK CA remains configured until the transition has been completed. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/troubleshooting-beats.md b/deploy-manage/deploy/cloud-on-k8s/troubleshooting-beats.md new file mode 100644 index 000000000..df5a2f81a --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/troubleshooting-beats.md @@ -0,0 +1,31 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-beat-troubleshooting.html +--- + +# Troubleshooting [k8s-beat-troubleshooting] + +## Beat Pods are crashing when kibanaRef is specified [k8s-beat-beat-pods-are-crashing-when-kibanaref-is-specified] + +When `kibanaRef` is specified, Beat tries to connect to the Kibana instance. If it’s unable to do so, the Beat process exits and the Pod restarts. This may happen when Kibana is not yet up or when a Beat user is not yet created in Elasticsearch. The Pod may restart a few times when it is first deployed. Afterwards, the Beat should run successfully. + + +## Configuration containing key: null is malformed [k8s-beat-configuration-containing-key-null-is-malformed] + +When `kubectl` is used to modify a resource, it calculates the diff between the user applied and the existing configuration. This diff has special [semantics](https://tools.ietf.org/html/rfc7396#section-1) that forces the removal of keys if they have special values. For example, if the user-applied configuration contains `some_key: null` (or equivalent `some_key: ~`), this is interpreted as an instruction to remove `some_key`. In Beats configurations, this is often a problem when it comes to defining things like [processors](https://www.elastic.co/guide/en/beats/filebeat/current/add-cloud-metadata.html). To avoid this problem: + +* Use `some_key: {}` (empty map) or `some_key: []` (empty array) instead of `some_key: null` if doing so does not affect the behaviour. This might not be possible in all cases as some applications distinguish between null values and empty values and behave differently. +* Instead of using `config` to define configuration inline, use `configRef` and store the configuration in a Secret. + + +## Pod fails to start after update [k8s_pod_fails_to_start_after_update] + +If you have configured a Beat to run as a `Deployment` and you are using a `hostPath` volume as the Beats data directory, you might encounter an error similar to the following: + +```shell script +ERROR instance/beat.go:958 Exiting: data path already locked by another beat. Please make sure that multiple beats are not sharing the same data path (path.data). +``` + +This can happen if the new Pod is scheduled on the same Kubernetes node as the old Pod and is now trying to use the same data directory. Use a [`Recreate`](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-beat-configuration.html#k8s-beat-chose-the-deployment-model) deployment strategy to avoid this problem. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/troubleshooting-enterprise-search.md b/deploy-manage/deploy/cloud-on-k8s/troubleshooting-enterprise-search.md new file mode 100644 index 000000000..3ee5f7170 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/troubleshooting-enterprise-search.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-enterprise-search-troubleshoot.html +--- + +# Troubleshooting [k8s-enterprise-search-troubleshoot] + +## Capture a JVM heap dump [k8s-enterprise-search-jvm-heap-dump] + +For advanced troubleshooting you might need to capture a JVM heap dump. By default, the Enterprise Search Docker image is not configured to run with a data volume by the ECK operator. However, you can write a heap dump to the `tmp` directory that Enterprise Search uses. Note that your heap dump will be lost if you do not extract it before the container restarts. + +```sh +kubectl exec $POD_NAME -- bash -c \ + 'jmap -dump:format=b,file=tmp/heap.hprof $(jps| grep Main | cut -f 1 -d " ")' + +# The Enterprise Search Docker images don't have tar installed so we cannot use kubectl cp +kubectl exec $POD_NAME -- cat /usr/share/enterprise-search/tmp/heap.hprof | gzip -c > heap.hprof.gz + +# Remove the heap dump from the running container to free up space +kubectl exec $POD_NAME -- rm /usr/share/enterprise-search/tmp/heap.hprof +``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/update-deployments.md b/deploy-manage/deploy/cloud-on-k8s/update-deployments.md new file mode 100644 index 000000000..a0f05f43e --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/update-deployments.md @@ -0,0 +1,31 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-update-deployment.html +--- + +# Update your deployments [k8s-update-deployment] + +You can add and modify most elements of the original Kubernetes cluster specification provided that they translate to valid transformations of the underlying Kubernetes resources (for example [existing volume claims cannot be downsized](volume-claim-templates.md)). The ECK operator will attempt to apply your changes with minimal disruption to the existing cluster. You should ensure that the Kubernetes cluster has sufficient resources to accommodate the changes (extra storage space, sufficient memory and CPU resources to temporarily spin up new pods, and so on). + +For example, you can grow the cluster to three {{es}} nodes from the [deployed {{es}} cluster](elasticsearch-deployment-quickstart.md) example by updating the `count` with [`apply`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_apply/): + +```yaml +cat < + rollingUpdate: + partition: 0 <2> + maxUnavailable: 1 <3> +``` + +1. The `RollingUpdate` strategy will update Pods one by one in reverse ordinal order. +2. This means that all the Pods from ordinal Replicas-1 to `partition` are updated . You can split the update into partitions to perform [canary rollout](https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#rolling-out-a-canary). +3. This ensures that the cluster has no more than one unavailable Pod at any given point in time. + + + +## OnDelete [k8s_ondelete] + +```yaml +spec: + updateStrategy: + type: "OnDelete" +``` + +`OnDelete` strategy does not automatically update Pods when a modification is made. You need to restart Pods yourself. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/update-strategy.md b/deploy-manage/deploy/cloud-on-k8s/update-strategy.md new file mode 100644 index 000000000..decd1f262 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/update-strategy.md @@ -0,0 +1,63 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-update-strategy.html +--- + +# Update strategy [k8s-update-strategy] + +You can use the `updateStrategy` specification to limit the number of simultaneous changes, like for example in the following cases: + +* The operator takes a Pod down to restart a node and applies a new configuration value. +* The operator must spin up Pods above what is currently in the specification to migrate to a new node set. + +```yaml +spec: + updateStrategy: + changeBudget: + maxSurge: 3 + maxUnavailable: 1 +``` + +`maxSurge`: Refers to the number of extra Pods that can be temporarily scheduled exceeding the number of Pods defined in the specification. This setting is useful for controlling the resource usage of the Kubernetes cluster when nodeSet configuration changes and new Pods need to be spun up to replace existing Pods. `MaxSurge` restricts the number of extra pods that can be running at any given point in time. If you have a large Elasticsearch cluster or a Kubernetes cluster running near capacity, not setting `maxSurge` could cause the newly created pods to temporarily use up all available spare resource capacity in the Kubernetes cluster and starve other workloads running there. + +`maxUnavailable`: Refers to the number of Pods that can be unavailable out of the total number of Pods in the currently applied specification. A Pod is defined unavailable when it is not ready from a Kubernetes perspective. + +The operator only tries to apply these constraints when a new specification is being applied. It is possible that the cluster state does not conform to the constraints at the beginning of the operation due to external factors. The operator will attempt to get to the desired state by adding or removing Pods as necessary while ensuring that the constraints are still satisfied. + +For example, if a new specification defines a larger cluster with `maxUnavailable: 0`, the operator creates the missing Pods according to the best practices. Similarly, if a new specification defines a smaller cluster with `maxSurge: 0`, the operator safely removes the unnecessary Pods. + +The operator will not enforce the change budget on version upgrades for clusters that have a non-HA setup, that is, less than three nodes. In these setups, removing a single node makes the whole cluster unavailable, and the operator will instead opt to upgrade all nodes at once. This is to avoid a situation where no progress can be made in a rolling upgrade process because the Elasticsearch cluster cannot form a quorum until all nodes have been upgraded. + +## Specify changeBudget [k8s_specify_changebudget] + +For both `maxSurge` and `maxUnavailable` you can specify the following values: + +* `null` - The default value is used. +* non-negative - The value is used as is. +* negative - The value is unbounded. + + +## Default behavior [k8s_default_behavior] + +When `updateStrategy` is not present in the specification, it defaults to the following: + +```yaml +spec: + updateStrategy: + changeBudget: + maxSurge: -1 + maxUnavailable: 1 +``` + +`maxSurge` is unbounded: This means that all the required Pods are created immediately. `maxUnavailable` defaults to `1`: This ensures that the cluster has no more than one unavailable Pod at any given point in time. + + +## Caveats [k8s_caveats] + +* With both `maxSurge` and `maxUnavailable` set to `0`, the operator cannot bring down an existing Pod nor create a new Pod. +* Due to the safety measures employed by the operator, certain `changeBudget` might prevent the operator from making any progress . For example, with `maxSurge` set to 0, you cannot remove the last data node from one `nodeSet` and add a data node to a different `nodeSet`. In this case, the operator cannot create the new node because `maxSurge` is 0, and it cannot remove the old node because there are no other data nodes to migrate the data to. +* For certain complex configurations, the operator might not be able to deduce the optimal order of operations necessary to achieve the desired outcome. If progress is blocked, you may need to update the `maxSurge` setting to a higher value than the theoretical best to help the operator make progress in that case. + +In these three cases, the operator generates logs to indicate that upscaling or downscaling are limited by `maxSurge` or `maxUnavailable` settings. + + diff --git a/deploy-manage/deploy/cloud-on-k8s/use-an-elasticsearch-cluster-managed-by-eck.md b/deploy-manage/deploy/cloud-on-k8s/use-an-elasticsearch-cluster-managed-by-eck.md new file mode 100644 index 000000000..5e58ab05e --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/use-an-elasticsearch-cluster-managed-by-eck.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-apm-eck-managed-es.html +--- + +# Use an Elasticsearch cluster managed by ECK [k8s-apm-eck-managed-es] + +Managing APM Server, Kibana and Elasticsearch with ECK allows a smooth and secured integration between the stack components. The output configuration of the APM Server is setup automatically to establish a trust relationship with Elasticsearch. Specifying the Kibana reference allows ECK to automatically configure the [Kibana endpoint](https://www.elastic.co/guide/en/apm/server/current/setup-kibana-endpoint.html). + +1. To deploy an APM Server and connect it to the Elasticsearch cluster and Kibana instance you created in the [quickstart](deploy-an-orchestrator.md), apply the following specification: + + ```yaml + cat < /proc/sys/vm/max_map_count'] + containers: + - name: sleep + image: docker.io/bash:5.2.21 + command: ['sleep', 'infinity'] +EOF +``` + +To run an Elasticsearch instance that waits for the kernel setting to be in place: + +```yaml +cat <<'EOF' | kubectl apply -f - +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + # Only uncomment the below section if you are not using the previous Daemonset to set max_map_count. + # config: + # node.store.allow_mmap: false + podTemplate: + spec: + # This init container ensures that the `max_map_count` setting has been applied before starting Elasticsearch. + # This is not required, but is encouraged when using the previous Daemonset to set max_map_count. + # Do not use this if setting config.node.store.allow_mmap: false + initContainers: + - name: max-map-count-check + command: ['sh', '-c', "while true; do mmc=$(cat /proc/sys/vm/max_map_count); if [ ${mmc} -eq 262144 ]; then exit 0; fi; sleep 1; done"] +EOF +``` + + diff --git a/deploy-manage/deploy/cloud-on-k8s/volume-claim-templates.md b/deploy-manage/deploy/cloud-on-k8s/volume-claim-templates.md new file mode 100644 index 000000000..0b713c23d --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/volume-claim-templates.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-volume-claim-templates.html +--- + +# Volume claim templates [k8s-volume-claim-templates] + + +### Specifying the volume claim settings [k8s_specifying_the_volume_claim_settings] + +By default, the operator creates a [`PersistentVolumeClaim`](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) with a capacity of 1Gi for each pod in an Elasticsearch cluster to prevent data loss in case of accidental pod deletion. For production workloads, you should define your own volume claim template with the desired storage capacity and (optionally) the Kubernetes [storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) to associate with the persistent volume. + +::::{important} +The name of the volume claim must always be `elasticsearch-data`. If you chose a different name you have to set up a corresponding volume mount matching the [data.path](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#path-settings) yourself ( `/usr/share/elasticsearch/data` by default). +:::: + + +```yaml +spec: + nodeSets: + - name: default + count: 3 + volumeClaimTemplates: + - metadata: + name: elasticsearch-data # Do not change this name unless you set up a volume mount for the data path. + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi + storageClassName: standard +``` + +## Controlling volume claim deletion [k8s_controlling_volume_claim_deletion] + +ECK automatically deletes PersistentVolumeClaim resources if the owning Elasticsearch nodes are scaled down. The corresponding PersistentVolumes may be preserved, depending on the configured [storage class reclaim policy](https://kubernetes.io/docs/concepts/storage/storage-classes/#reclaim-policy). + +In addition, you can control what ECK should do with the PersistentVolumeClaims if you delete the Elasticsearch cluster altogether through the `volumeClaimDeletePolicy` attribute. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: es +spec: + version: 8.16.1 + volumeClaimDeletePolicy: DeleteOnScaledownOnly + nodeSets: + - name: default + count: 3 +``` + +The possible values are `DeleteOnScaledownAndClusterDeletion` and `DeleteOnScaledownOnly`. By default `DeleteOnScaledownAndClusterDeletion` is in effect, which means that all PersistentVolumeClaims are deleted together with the Elasticsearch cluster. However, `DeleteOnScaledownOnly` keeps the PersistentVolumeClaims when deleting the Elasticsearch cluster. If you recreate a deleted cluster with the same name and node sets as before, the existing PersistentVolumeClaims will be adopted by the new cluster. + + +### Updating the volume claim settings [k8s-volume-claim-templates-update] + +If the storage class allows [volume expansion](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/), you can increase the storage requests size in the volumeClaimTemplates. ECK will update the existing PersistentVolumeClaims accordingly, and recreate the StatefulSet automatically. If the volume driver supports `ExpandInUsePersistentVolumes`, the filesystem is resized online, without the need of restarting the Elasticsearch process, or re-creating the Pods. If the volume driver does not support `ExpandInUsePersistentVolumes`, Pods must be manually deleted after the resize, to be recreated automatically with the expanded filesystem. + +Kubernetes forbids any other changes in the volumeClaimTemplates, such as [changing the storage class](https://kubernetes.io/docs/concepts/storage/storage-classes) or [decreasing the volume size](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/). To make these changes, you can create a new nodeSet with different settings, and remove the existing nodeSet. In practice, that’s equivalent to renaming the existing nodeSet while modifying its claim settings in a single update. Before removing Pods of the deleted nodeSet, ECK makes sure that data is migrated to other nodes. + + +### EmptyDir [k8s_emptydir] + +::::{warning} +Don’t use `emptyDir` as it might generate permanent data loss. +:::: + + +If you are not concerned about data loss, you can use an `emptyDir` volume for Elasticsearch data: + +```yaml +spec: + nodeSets: + - name: data + count: 10 + podTemplate: + spec: + volumes: + - name: elasticsearch-data + emptyDir: {} +``` diff --git a/deploy-manage/deploy/cloud-on-k8s/webhook-namespace-selectors.md b/deploy-manage/deploy/cloud-on-k8s/webhook-namespace-selectors.md new file mode 100644 index 000000000..41e052ff2 --- /dev/null +++ b/deploy-manage/deploy/cloud-on-k8s/webhook-namespace-selectors.md @@ -0,0 +1,20 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-webhook-namespace-selectors.html +--- + +# Webhook namespace selectors [k8s-webhook-namespace-selectors] + +If you install ECK through the Helm chart, you can now set `namespaceSelector` and `objectSelector` on the webhook. The webhook name is generated as `..k8s.elastic.co` so that multiple operators can be installed side-by-side in the same cluster. + +This can be useful in large and busy clusters, where you might want to divide the set of namespaces across several operators to speed up reconciliation times and reduce the amount of resources required per operator. + +Webhook resources are cluster-scoped, therefore `createClusterScopedResources` must be set to true when installing the chart. This means that each operator gets a ClusterRole that applies to the whole cluster and not just the set of namespaces it is configured to manage. This approach is suitable only if you want to do load-splitting in a trusted cluster. + +::::{warning} +It is not recommended to deploy webhook resources in environments where operators are run by untrusted users and need to be locked down tightly. +:::: + + +For more information, check [Configure the validating webhook](configure-validating-webhook.md) and [Dynamic Admission Control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/). + diff --git a/deploy-manage/deploy/elastic-cloud.md b/deploy-manage/deploy/elastic-cloud.md new file mode 100644 index 000000000..06113a2d1 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud.md @@ -0,0 +1,91 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/intro.html#general-what-is-serverless-elastic-differences-between-serverless-projects-and-hosted-deployments-on-ecloud +--- + +# Elastic Cloud [intro] + +{{serverless-full}} is a fully managed solution that allows you to deploy and use Elastic for your use cases without managing the underlying infrastructure. It represents a shift in how you interact with {{es}} - instead of managing clusters, nodes, data tiers, and scaling, you create **serverless projects** that are fully managed and automatically scaled by Elastic. This abstraction of infrastructure decisions allows you to focus solely on gaining value and insight from your data. + +{{serverless-full}} automatically provisions, manages, and scales your {{es}} resources based on your actual usage. Unlike traditional deployments where you need to predict and provision resources in advance, serverless adapts to your workload in real-time, ensuring optimal performance while eliminating the need for manual capacity planning. + +Serverless projects use the core components of the {{stack}}, such as {{es}} and {{kib}}, and are based on an architecture that decouples compute and storage. Search and indexing operations are separated, which offers high flexibility for scaling your workloads while ensuring a high level of performance. + +Elastic provides three serverless solutions available on {{ecloud}}: + +* **https://www.elastic.co/guide/en/serverless/current/what-is-elasticsearch-serverless.html[{{es-serverless}}]**: Build powerful applications and search experiences using a rich ecosystem of vector search capabilities, APIs, and libraries. +* **https://www.elastic.co/guide/en/serverless/current/what-is-observability-serverless.html[{{obs-serverless}}]**: Monitor your own platforms and services using powerful machine learning and analytics tools with your logs, metrics, traces, and APM data. +* **https://www.elastic.co/guide/en/serverless/current/what-is-security-serverless.html[{{sec-serverless}}]**: Detect, investigate, and respond to threats with SIEM, endpoint protection, and AI-powered analytics capabilities. + +[Learn more about {{serverless-full}} in our blog](https://www.elastic.co/blog/elastic-cloud-serverless). + + +## Benefits of serverless projects [_benefits_of_serverless_projects] + +**Management free.** Elastic manages the underlying Elastic cluster, so you can focus on your data. With serverless projects, Elastic is responsible for automatic upgrades, data backups, and business continuity. + +**Autoscaled.** To meet your performance requirements, the system automatically adjusts to your workloads. For example, when you have a short time spike on the data you ingest, more resources are allocated for that period of time. When the spike is over, the system uses less resources, without any action on your end. + +**Optimized data storage.** Your data is stored in cost-efficient, general storage. A cache layer is available on top of the general storage for recent and frequently queried data that provides faster search speed. The size of the cache layer and the volume of data it holds depend on [settings](elastic-cloud/project-settings.md) that you can configure for each project. + +**Dedicated experiences.** All serverless solutions are built on the Elastic Search Platform and include the core capabilities of the Elastic Stack. They also each offer a distinct experience and specific capabilities that help you focus on your data, goals, and use cases. + +**Pay per usage.** Each serverless project type includes product-specific and usage-based pricing. + +**Data and performance control**. Control your project data and query performance against your project data. * Data. Choose the data you want to ingest and the method to ingest it. By default, data is stored indefinitely in your project, and you define the retention settings for your data streams. * Performance. For granular control over costs and query performance against your project data, serverless projects come with a set of predefined settings you can edit. + + +## Differences between serverless projects and hosted deployments on {{ecloud}} [general-what-is-serverless-elastic-differences-between-serverless-projects-and-hosted-deployments-on-ecloud] + +You can run [hosted deployments](https://www.elastic.co/guide/en/cloud/current/ec-getting-started.html) of the {{stack}} on {{ecloud}}. These hosted deployments provide more provisioning and advanced configuration options. + +| | | | +| --- | --- | --- | +| Option | Serverless | Hosted | +| **Cluster management** | Fully managed by Elastic. | You provision and manage your hosted clusters. Shared responsibility with Elastic. | +| **Scaling** | Autoscales out of the box. | Manual scaling or autoscaling available for you to enable. | +| **Upgrades** | Automatically performed by Elastic. | You choose when to upgrade. | +| **Pricing** | Individual per project type and based on your usage. | Based on deployment size and subscription level. | +| **Performance** | Autoscales based on your usage. | Manual scaling. | +| **Solutions** | Single solution per project. | Full Elastic Stack per deployment. | +| **User management** | Elastic Cloud-managed users. | Elastic Cloud-managed users and native Kibana users. | +| **API support** | Subset of [APIs](https://www.elastic.co/docs/api). | All Elastic APIs. | +| **Backups** | Projects automatically backed up by Elastic. | Your responsibility with Snapshot & Restore. | +| **Data retention** | Editable on data streams. | Index Lifecycle Management. | + + +## Answers to common serverless questions [general-what-is-serverless-elastic-answers-to-common-serverless-questions] + +**Is there migration support between hosted deployments and serverless projects?** + +Migration paths between hosted deployments and serverless projects are currently unsupported. + +**How can I move data to or from serverless projects?** + +We are working on data migration tools! In the interim, [use Logstash](https://www.elastic.co/guide/en/serverless/current/elasticsearch-ingest-data-through-logstash.html) with Elasticsearch input and output plugins to move data to and from serverless projects. + +**How does serverless ensure compatibility between software versions?** + +Connections and configurations are unaffected by upgrades. To ensure compatibility between software versions, quality testing and API versioning are used. + +**Can I convert a serverless project into a hosted deployment, or a hosted deployment into a serverless project?** + +Projects and deployments are based on different architectures, and you are unable to convert. + +**Can I convert a serverless project into a project of a different type?** + +You are unable to convert projects into different project types, but you can create as many projects as you’d like. You will be charged only for your usage. + +**How can I create serverless service accounts?** + +Create API keys for service accounts in your serverless projects. Options to automate the creation of API keys with tools such as Terraform will be available in the future. + +To raise a Support case with Elastic, raise a case for your subscription the same way you do today. In the body of the case, make sure to mention you are working in serverless to ensure we can provide the appropriate support. + +**Where can I learn about pricing for serverless?** + +See serverless pricing information for [Search](https://www.elastic.co/pricing/serverless-search), [Observability](https://www.elastic.co/pricing/serverless-observability), and [Security](https://www.elastic.co/pricing/serverless-security). + +**Can I request backups or restores for my projects?** + +It is not currently possible to request backups or restores for projects, but we are working on data migration tools to better support this. diff --git a/deploy-manage/deploy/elastic-cloud/access-kibana.md b/deploy-manage/deploy/elastic-cloud/access-kibana.md new file mode 100644 index 000000000..59f8ca7ba --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/access-kibana.md @@ -0,0 +1,21 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-access-kibana.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-access-kibana.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-enable-kibana2.html +--- + +# Access Kibana + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-access-kibana.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-access-kibana.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-enable-kibana2.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + + +$$$ec-enable-kibana2$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/add-plugins-extensions.md b/deploy-manage/deploy/elastic-cloud/add-plugins-extensions.md new file mode 100644 index 000000000..4845bc8fc --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/add-plugins-extensions.md @@ -0,0 +1,31 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-adding-plugins.html +--- + +# Add plugins and extensions [ec-adding-plugins] + +Plugins extend the core functionality of {{es}}. There are many suitable plugins, including: + +* Discovery plugins, such as the cloud AWS plugin that allows discovering nodes on EC2 instances. +* Analysis plugins, to provide analyzers targeted at languages other than English. +* Scripting plugins, to provide additional scripting languages. + +Plugins can come from different sources: the official ones created or at least maintained by Elastic, community-sourced plugins from other users, and plugins that you provide. Some of the official plugins are always provided with our service, and can be [enabled per deployment](https://www.elastic.co/guide/en/cloud/current/ec-adding-elastic-plugins.html). + +There are two ways to add plugins to a deployment in Elasticsearch Service: + +* [Enable one of the official plugins already available in Elasticsearch Service](https://www.elastic.co/guide/en/cloud/current/ec-adding-elastic-plugins.html). +* [Upload a custom plugin and then enable it per deployment](upload-custom-plugins-bundles.md). + +Custom plugins can include the official {{es}} plugins not provided with Elasticsearch Service, any of the community-sourced plugins, or [plugins that you write yourself](https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugin-authors.html). Uploading custom plugins is available only to Gold, Platinum, and Enterprise subscriptions. For more information, check [Upload custom plugins and bundles](upload-custom-plugins-bundles.md). + +To learn more about the official and community-sourced plugins, refer to [{{es}} Plugins and Integrations](https://www.elastic.co/guide/en/elasticsearch/plugins/current/index.html). + +For a detailed guide with examples of using the Elasticsearch Service API to create, get information about, update, and delete extensions and plugins, check [Managing plugins and extensions through the API](manage-plugins-extensions-through-api.md). + +Plugins are not supported for {{kib}}. To learn more, check [Restrictions for {{es}} and {{kib}} plugins](restrictions-known-problems.md#ec-restrictions-plugins). + + + + diff --git a/deploy-manage/deploy/elastic-cloud/add-plugins-provided-with-elastic-cloud-hosted.md b/deploy-manage/deploy/elastic-cloud/add-plugins-provided-with-elastic-cloud-hosted.md new file mode 100644 index 000000000..62b781fac --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/add-plugins-provided-with-elastic-cloud-hosted.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-adding-plugins.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-adding-elastic-plugins.html +--- + +# Add plugins provided with Elastic Cloud Hosted + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-adding-plugins.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-adding-elastic-plugins.md \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/available-stack-versions.md b/deploy-manage/deploy/elastic-cloud/available-stack-versions.md new file mode 100644 index 000000000..570978c89 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/available-stack-versions.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-version-policy.html +--- + +# Available stack versions [ec-version-policy] + +This section describes our version policy for Elasticsearch Service, including: + +* [What Elastic Stack versions are available](#ec-version-policy-available) +* [When we make new Elastic Stack versions available](#ec-version-policy-new) +* [When we might force an upgrade or restart to keep your cluster safe](#ec-version-policy-critical) +* [What release candidates and cutting edge builds we make available](#ec-release-builds) +* [What happens when a version reaches its end-of-life (EOL)](#ec-version-policy-eol) + + +## Available Elastic Stack versions [ec-version-policy-available] + +Elastic Stack uses a versions code that is constructed of three numbers separated by dots: the leftmost number is the number of the major release, the middle number is the number of the minor release and the rightmost number is the number of the maintenance release (e.g., 8.3.2 means major release 8, minor release 3 and maintenance release 2). + +You might sometimes notice additional versions listed in the user interface beyond the versions we currently support and maintain, such as [release candidate builds](#ec-release-builds) and older versions. If a version is listed in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), it can be deployed. + + +## New Elastic Stack versions [ec-version-policy-new] + +Whenever a new Elastic Stack version is released, we do our best to provide the new version on our hosted service at the same time. We send you an email and add a notice to the console, recommending an upgrade. You’ll need to decide whether to upgrade to the new version with new features and bug fixes or to stay with a version you know works for you a while longer. + +There can be [breaking changes](https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes.html) in some new versions of Elasticsearch that break what used to work in older versions. Before upgrading, you’ll want to check if the new version introduces any changes that might affect your applications. A breaking change might be a function that was previously deprecated and that has been removed in the latest version, for example. If you have an application that depends on the removed function, the application will need to be updated to continue working with the new version of Elasticsearch. + +To learn more about upgrading to newer versions of the Elastic Stack on our hosted service, check [Upgrade Versions](../../upgrade/deployment-or-cluster.md). + + +## Upgrades or restart for critical issues [ec-version-policy-critical] + +We reserve the right to force upgrade or restart a cluster immediately and without notice in advance if there is a critical security or stability issue. Such upgrades happen only within minor versions. + +A forced upgrade or restart might become necessary in a situation that: + +* Bypasses Shield, where knowing only the cluster endpoint is sufficient to gain access to data. +* Disrupts our ability to effectively manage a cluster in disaster scenarios +* Impairs stability to the point where we cannot guarantee cluster node or data integrity +* Impairs or risks impairing our infrastructure + + +## Release candidates and cutting-edge releases [ec-release-builds] + +Interested in kicking the tires of Elasticsearch releases at the cutting edge? We sometimes make release candidate builds and other cutting-edge releases available in Elasticsearch Service for you to try out. + +::::{warning} +Remember that cutting-edge releases are used to test new function fully. These releases might still have issues and might be less stable than the GA version. There’s also no guaranteed upgrade path to the GA version when it becomes available. +:::: + + +If you’re interested in trying out one of these cutting-edge releases, we don’t recommended upgrading an existing deployment directly. Instead, use a copy of your existing data with a test deployment, first. + +Cutting-edge releases do not remain available forever. Once the GA version of Elasticsearch is released, your deployment needs to be removed after a grace period. We cannot guarantee that you will be able to upgrade to the GA version when it becomes available. + + +## Version Policy and Product End of Life [ec-version-policy-eol] + +For Elasticsearch Service, we follow the [Elastic Version Maintenance and Support Policy](https://www.elastic.co/support/eol), which defines the support and maintenance policy of the Elastic Stack. diff --git a/deploy-manage/deploy/elastic-cloud/aws-marketplace.md b/deploy-manage/deploy/elastic-cloud/aws-marketplace.md new file mode 100644 index 000000000..ac3e419d8 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/aws-marketplace.md @@ -0,0 +1,84 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-aws.html +--- + +# AWS Marketplace [ec-billing-aws] + +7-Day Free Trial Sign-Up: On the [Elasticsearch Service AWS marketplace page](https://aws.amazon.com/marketplace/pp/prodview-voru33wi6xs7k), click **View purchase options**, sign into your AWS account, then start using Elastic Cloud. + +::::{tip} +The free trial includes provisioning of a single deployment and you are not charged for the first 7 days. Billing starts automatically after the 7-day trial period ends. Get started today! +:::: + + +You can subscribe to Elasticsearch Service directly from the AWS Marketplace. You then have the convenience of viewing your Elasticsearch Service subscription as part of your AWS bill, and you do not have to supply any additional billing information to Elastic. + +Some differences exist when you subscribe to Elasticsearch Service through the AWS Marketplace: + +* Billing starts automatically after the 7-day trial period. +* Previous Elasticsearch Service accounts cannot be converted to use the AWS Marketplace. If you already have an account, you must use a different email address when you sign up for a subscription through the AWS Marketplace. +* Pricing is based on the AWS region, the size of your deployment, as well as some other parameters such as data transfer out, data transfer internode, snapshot storage, and snapshot APIs. For more details, check [Billing Dimensions](../../cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.md). +* The consolidated charges for your Elasticsearch Service subscription display in the AWS Marketplace billing console. It can take a day or two before new charges show up. +* Regardless of where your deployment is hosted (visible in the Elastic Cloud console), the AWS Marketplace charges for all AWS regions are metered in US East (Northern Virginia). As a result, US East (Northern Virginia) is listed as the region in the AWS Marketplace console. +* To get a detailed breakdown of your charges by deployment or by product, open the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) and go to **Account & Billing** > **Usage**. +* To end your trial or unsubscribe from the service, delete your deployment(s). +* Elastic provides different [subscription levels](https://www.elastic.co/subscriptions/cloud). During your 7-day trial you will automatically have an Enterprise level subscription. After the trial you can choose the subscription level. + + +## Before you begin [ec_before_you_begin] + +Note the following items before you subscribe: + +* You cannot use an email address that already has an Elastic Cloud account. If you want to use the same account email address with AWS Marketplace billing, you must first change the email address on your existing account before setting up your new AWS Marketplace subscription. For instructions on how to change your email address in Elastic Cloud, check [update your email address](../../../cloud-account/update-your-email-address.md). +* If you want to manage deployments on the existing Elasticsearch Service account with your AWS MP billing account, you must migrate your deployments over to the new MP billing account. To migrate, use a [custom repository](../../tools/snapshot-and-restore/elastic-cloud-hosted.md) to take a snapshot and then restore that snapshot to a new deployment under your AWS Marketplace account. + + +## Subscribe to Elasticsearch Service through the AWS Marketplace [ec_subscribe_to_elasticsearch_service_through_the_aws_marketplace] + +To subscribe to Elasticsearch Service through the AWS Marketplace: + +1. Go to [Elasticsearch Service on the AWS Marketplace](https://aws.amazon.com/marketplace/pp/B01N6YCISK) and click **View purchase options**. +2. Click **Subscribe** and then **Set Up Your Account** to continue. +3. Follow the steps displayed to complete the signup process. + + 1. Ensure that you have the necessary AWS permissions required to complete a marketplace transaction. + 2. Create a new {{ecloud}} account. This account is linked to your AWS Marketplace subscription. + 3. (Optional) Use the {{ecloud}} CloudFormation template to quickly get started with Elastic. The template deploys the Elastic Stack in your {{ecloud}} account, and also provisions the {{agent}} on a new EC2 instance in your AWS environment. + 4. Navigate to {{ecloud}} to continue. + + ::::{note} + You can leave this page and return to it later. Select **Copy** to get a direct URL to the configuration page with your saved settings. You can also send the URL to an email address. + :::: + + + +## Troubleshooting [ec-billing-aws-troubleshooting] + +This section describes some scenarios that you may experience onboarding onto the marketplace offer. If you’re running into issues with your marketplace subscription or are encountering technical issues, create a support case or contact `support@elastic.co`. + +* [I receive an error message telling me that I’m already signed up using an Elastic Cloud email address.](#ec-awsmp-account-collision01) +* [When I try to configure a new account from the AWS console, I get the Elastic Cloud login page, not the sign-up page. If I sign up to a new account it is not connected to the marketplace.](#ec-awsmp-account-collision02) +* [When I try to configure an account from the AWS console I get an error that An active AWS subscription already exists.](#ec-awsmp-account-collision03) + + +### I receive an error message telling me that I’m already signed up using an Elastic Cloud email address. [ec-awsmp-account-collision01] + +This occurs when you attempt to sign up to the marketplace offer using an email address that already exists in Elastic Cloud, such as part of a trial account. You have a few options: + +* **Change the email address of your previous Elastic Cloud account** - Log in to your existing Elastic Cloud account and change the email address. Once changed, navigate back to the AWS console to finish setting up your marketplace subscription. +* **Sign up using a different email address** - Sign up to Elastic Cloud using a different email address. + + +### When I try to configure a new account from the AWS console, I get the Elastic Cloud login page, not the sign-up page. If I sign up to a new account it is not connected to the marketplace. [ec-awsmp-account-collision02] + +If the Elastic Cloud login page displays when coming from the AWS console, then an Elastic Cloud account is already connected to your marketplace subscription. Log into Elastic Cloud with that account to continue. If you can’t remember your password, use the **Forgot password?** link to reset your password. + +If you can’t remember which email address you used to sign up to Elastic Cloud, or you need more help, contact `support@elastic.co`. + + +### When I try to configure an account from the AWS console I get an error that an active AWS subscription already exists. [ec-awsmp-account-collision03] + +This error occurs when you have already provisioned a marketplace subscription under your AWS user account. Each AWS user account can only subscribe to Elastic Cloud once. + +If you wish to configure multiple marketplace subscriptions, you need to use a different AWS user account to create the marketplace subscription from the AWS console. Once the marketplace subscription is created in AWS, you can continue to configure the subscription in Elastic Cloud. diff --git a/deploy-manage/deploy/elastic-cloud/azure-marketplace-pricing.md b/deploy-manage/deploy/elastic-cloud/azure-marketplace-pricing.md new file mode 100644 index 000000000..75ab51bbd --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/azure-marketplace-pricing.md @@ -0,0 +1,51 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-azure-marketplace-pricing.html +--- + +# Azure Marketplace pricing [ec-azure-marketplace-pricing] + +The pricing in Azure Marketplace defines how on-demand usage and prepaid fees get converted from ECUs and discounts into the local currency in which you transact on Azure Marketplace. + +We will be updating the pricing plan for {{ecloud}} on Azure Marketplace effective January 1st, 2024. This update will affect customers paying in non-USD currencies. + + +## Why we’re making these changes [ec_why_were_making_these_changes] + +The pricing plan update enables us to align with market trends and adapt to changing economic conditions, ensuring that we continue delivering the highest standard of service. + + +## Who is affected [ec_who_is_affected] + +These pricing changes will apply to customers who are currently paying for Azure Marketplace services in non-USD currencies. If you are paying in USD, your pricing and billing will remain unchanged. + +| | | | +| --- | --- | --- | +| Currency | Price | Elastic Billing Units for Azure† | +| USD | 1.00 | $0.10 per 1000 units | +| AUD | 1.60 | $0.16 per 1000 units | +| BRL | 5.40 | R$0.54 per 1000 units | +| CAD | 1.50 | $0.15 per 1000 units | +| CHF | 1.00 | CHF 0.10 per 1000 units | +| DKK | 7.40 | 0,74 kr. per 1000 units | +| EUR | 1.00 | €0.10 per 1000 units | +| GBP | 0.90 | £0.09 per 1000 units | +| INR | 92.00 | ₹9.20 per 1000 units | +| JPY | 148.30 | ¥14.83 per 1000 units | +| KRW | 1421.20 | ₩142.12 per 1000 units | +| NOK | 11.20 | NOK 1.12 per 1000 units | +| NZD | 1.80 | $0.18 per 1000 units | +| SEK | 11.50 | 1,15 kr. per 1000 units | +| TWD | 34.70 | NT$3.47 per 1000 units | + +† used to avoid rounding issues: at list price, 1 ECU corresponds to 10,000 Elastic Billing Units for Azure + + +## How the changes will affect you [ec_how_the_changes_will_affect_you] + +For customers paying in non-USD currencies, any future prepaid fees, or on-demand usage after the plan change will be charged at the new currency exchange rate. The applicable rate will be clearly displayed on the Azure Marketplace listing page, allowing you to stay informed about the pricing adjustments. You will receive an email from Azure Marketplace once the plan change is in effect. + + +## Our commitment to you [ec_our_commitment_to_you] + +We understand that pricing adjustments can raise questions or concerns, and we are here to support you throughout this process. Should you have any inquiries or need assistance, please reach out to your Elastic account representative or Elastic Support at `support@elastic.co`. diff --git a/deploy-manage/deploy/elastic-cloud/azure-native-isv-service.md b/deploy-manage/deploy/elastic-cloud/azure-native-isv-service.md new file mode 100644 index 000000000..abbd39da9 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/azure-native-isv-service.md @@ -0,0 +1,538 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-azure-marketplace-native.html +--- + +# Azure Native ISV Service [ec-azure-marketplace-native] + +The {{ecloud}} Azure Native ISV Service allows you to deploy managed instances of the {{stack}} directly in Azure, through the Azure integrated marketplace. The service brings the following benefits: + +* **Easy deployment for managed {{stack}} instances** + + {{stack}} instances managed by Elastic are deployed directly from the Azure console. This provides the complete {{stack}} experience with all commercial features. + +* **Integrated billing** + + You are billed directly to your Azure account; no need to configure billing details in Elastic. See [Integrated billing](#ec-azure-integration-billing-summary) for details, as well as the [Billing FAQ](#ec-azure-integration-billing-faq). + +* **Easy consolidation of your Azure logs in Elastic** + + Use a single-step setup to ingest logs from your Azure services into the {{stack}}. + + +::::{tip} +The full product name in the Azure integrated marketplace is `Elastic Cloud (Elasticsearch) - An Azure Native ISV Service`. +:::: + + + +## Integrated billing [ec-azure-integration-billing-summary] + +Azure Native ISV Service includes integrated billing: Elastic resource costs are posted to your Azure subscription through the Microsoft Commercial Marketplace. You can create various {{ecloud}} resources (deployments) across different Azure subscriptions, with all of the costs associated with an {{ecloud}} organization posted to a single Azure subscription. + +Note the following terms: + +* **Azure Marketplace SaaS ID**: This is a unique identifier that’s generated one time by Microsoft Commercial Marketplace when a user creates their first Elastic resource (deployment) using the Microsoft Azure (Portal, API, SDK, or Terraform). This is mapped to a User ID and Azure Subscription ID +* **{{ecloud}} organization**: An [organization](../../users-roles/cloud-organization.md) is the foundational construct under which everything in {{ecloud}} is grouped and managed. An organization is created as a step during the creation of your first Elastic resource (deployment), whether that’s done through Microsoft Azure (Portal, API, SDK, or Terraform). The initial member of the {{ecloud}} organization can then invite other users. +* **Elastic resource (deployment)**: An {{ecloud}} deployment helps you manage an {{es}} cluster and instances of other Elastic products in one place. You can work with Elastic deployments from within the Azure ecosystem. Multiple users in the {{ecloud}} organization can create different deployments from different Azure subscriptions. They can also create deployments from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). + +The following diagram shows the mapping between Microsoft Azure IDs, {{ecloud}} organization IDs, and your Elastic resources (deployments). + +:::{image} ../../../images/cloud-ec-azure-billing-mapping.png +:alt: Azure to {{ecloud}} mappings +::: + +The following diagram shows how your {{ecloud}} organization costs are reported in Microsoft Azure. You can also refer to our [Billing FAQ](#ec-azure-integration-billing-faq) on this page. + +:::{image} ../../../images/cloud-ec-azure-billing-reporting.png +:alt: Azure to {{ecloud}} mappings +::: + + +## Frequently asked questions [ec-azure-integration-faq] + +Check the following sections to learn more about the Azure Native ISV Service: + +* **Getting started** + + * [How do I get started?](#azure-integration-get-started) + * [What is the pricing for this offer?](#azure-integration-pricing) + * [Which Azure regions are supported?](#azure-integration-regions) + * [Which {{ecloud}} subscription levels are available?](#azure-integration-subscription-levels) + * [How can I change my {{ecloud}} subscription level?](#azure-integration-change-subscription) + * [Can I subscribe using an email address from another Elastic account?](#azure-integration-existing-email) + * [Is the {{ecloud}} Azure Native ISV Service connected with Azure user management?](#azure-integration-azure-user-management) + * [Does {{ecloud}} Azure Native ISV Service support recently introduced {{ecloud}} RBAC capability?](#azure-integration-azure-rbac) + * [I already have an {{ecloud}} account, can I use this service?](#azure-integration-prior-cloud-account) + * [Can I sign up for an {{ecloud}} trial account and then convert to the {{ecloud}} Azure Native ISV Service?](#azure-integration-convert-trial) + * [Does {{es}} get deployed into my tenant in Azure?](#azure-integration-azure-tenant) + * [What Azure tenant information does Elastic have access to?](#azure-integration-azure-tenant-info) + * [What other methods are available to deploy {{es}}?](#azure-integration-cli-api) + * [How do I migrate my data from the classic Azure marketplace account to the {{ecloud}} Azure Native ISV Service?](#azure-integration-migrate) + * [Can I invite users to my organization, even if they cannot receive emails?](#azure-integration-no-inbox) + +* **Billing** + + * [Which Azure Subscription will be billed for my Elastic resources?](#azure-integration-billing-which-subscription) + * [How do I get different Elastic resources (deployments) charges to different Azure Subscriptions?](#azure-integration-billing-different-deployments) + * [Why can’t I see Elastic resources costs in Azure Cost Explorer?](#azure-integration-billing-elastic-costs) + * [Why don’t I see my individual Elastic resources (deployments) in the Azure Marketplace Invoice?](#azure-integration-billing-deployments) + * [Why can’t I find Instance ID and Instance Name values from Azure Marketplace Invoice in the Azure Portal?](#azure-integration-billing-instance-values) + +* **Managing your {{ecloud}} deployment** + + * [What is included in my {{ecloud}} deployment?](#azure-integration-whats-included) + * [How can I access my {{ecloud}} deployment?](#azure-integration-how-to-access) + * [How can I modify my {{ecloud}} deployment?](#azure-integration-modify-deployment) + * [How can I delete my {{ecloud}} deployment?](#azure-integration-delete-deployment) + * [Can I delete the Azure Resource Group containing my deployment?](#azure-integration-delete-resource-group) + +* **Configuring logs and metrics** + + * [How do I monitor my existing Azure services?](#azure-integration-monitor) + * [How do I ingest metrics from my Azure services?](#azure-integration-ingest-metrics) + * [How can I monitor my Azure virtual machines in {{es}}?](#azure-integration-vm-extensions) + +* **Troubleshooting** + + * [I receive an error message about not having required authorization.](#azure-integration-authorization-access) + * [My {{ecloud}} deployment creation failed.](#azure-integration-deployment-failed-traffic-filter) + * [I can’t SSO into my {{ecloud}} deployment.](#azure-integration-failed-sso) + * [I see some deployments in the {{ecloud}} console but not in the Azure Portal.](#azure-integration-cant-see-deployment) + * [My {{ecloud}} Azure Native ISV Service logs are not being ingested.](#azure-integration-logs-not-ingested) + +* **Support** + + * [How do I get support?](#azure-integration-support) + * [How can I change my subscription level / support level?](#azure-integration-change-level) + + + +## Getting started [ec-azure-integration-getting-started] + +$$$azure-integration-get-started$$$How do I get started with {{ecloud}}? +: {{ecloud}} is available as an offering through the Azure console. + + **Prerequisites** + + There are a few requirements to check before setting up an {{ecloud}} deployment: + + * In Azure your account role for the subscription is set as *Owner* or *Contributor*. For details and steps to assign roles, check [Permission to purchase](https://docs.microsoft.com/en-us/marketplace/azure-purchasing-invoicing#permission-to-purchase) in the Azure documentation. + * You cannot use an email address that already has an {{ecloud}} account. Use a different Azure account to set up the {{es}} resource, or [contact the Elastic Support Team](#azure-integration-support) for assistance. + * You must have a credit card registered on your Azure subscription. If you have a non-payment subscription, such as a [Virtual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/), you can’t create an {{ecloud}} deployment. Refer to the Azure [Purchase errors](https://docs.microsoft.com/en-us/azure/partner-solutions/elastic/troubleshoot#purchase-errors) troubleshooting documentation for more information. + * In order to single sign-on into your {{ecloud}} deployment from Azure you need to request approval from your Azure administrator. + + **Getting started** + + To create a deployment directly from the Azure portal, go to [the list of {{ecloud}} deployments in the Azure portal](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.Elastic%2Fmonitors) and select `Create`. + + When you create an {{ecloud}} deployment, an {{stack}} cluster is created for you. The size of this deployment is **16GB of RAM** and **560GB of storage**, across **two availability zones** for redundancy. The size of the deployment, both RAM and storage, is changed directly in the Elastic console. Usage charges are based on the deployment size, so size your instance efficiently. The deployment defaults to the latest available version of the {{stack}}. Check our [Version policy](available-stack-versions.md) to learn more about when new versions are made available and old versions are removed from service. + + +$$$azure-integration-pricing$$$What is the pricing for this offer? +: Pricing is pay-as-you-go per hour for each {{ecloud}} deployment created. Note that there is no free trial period for the offering. Charges are applied to your Azure bill at the end of the month. Use the {{ecloud}} [Pricing Calculator](https://www.elastic.co/cloud/elasticsearch-service/pricing?page=docs&placement=docs-body) to size a deployment and view the corresponding hourly rate. + + Elastic charges include: + + * [Hourly consumption based on your active deployments](https://cloud.elastic.co/pricing) + * [Data transfer and snapshot storage charges](https://cloud.elastic.co/deployment-pricing-table) + + +$$$azure-integration-regions$$$Which Azure regions are supported? +: Here is the [list of available Azure regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html#ec-azure_regions) supported in {{ecloud}}. + +$$$azure-integration-subscription-levels$$$Which {{ecloud}} subscription levels are available? +: The subscription defaults to the Enterprise subscription, granting immediate access to advanced {{stack}} features like machine learning, and premium support response time SLAs. {{ecloud}} offers a number of different [subscription levels](https://elastic.co/pricing). + +$$$azure-integration-change-subscription$$$How can I change my {{ecloud}} subscription level? +: Modify your subscription level on the billing page in the Elastic console. + + 1. Select a deployment to open the deployment overview page. + 2. Select the **Advanced Settings** link to access your deployment in the {{ecloud}} console. + 3. In the {{ecloud}} console, select your account avatar icon at the top of the page, and then choose **Account & Billing**. + 4. Select the **Billing** tab and choose **Change my subscription**. + + :::{image} ../../../images/cloud-ec-marketplace-azure009.png + :alt: The Elastic Account Billing page with Advanced Settings highlighted + ::: + + 5. Select the [subscription level](https://elastic.co/pricing) that you’d like. + + :::{image} ../../../images/cloud-ec-marketplace-azure006.png + :alt: The Update Subscription page showing Standard + ::: + + +$$$azure-integration-existing-email$$$Can I subscribe using an email address from another Elastic account? +: Your email address is associated with only one Elastic account. For a workaround, check [Sign up using an email address from another Cloud account](create-an-organization.md). + +$$$azure-integration-azure-user-management$$$Is the {{ecloud}} Azure Native ISV Service connected with Azure user management? +: No. Elastic is not currently integrated with Azure user management. Azure users who deploy {{es}} on Azure view and manage their own cluster through the Cloud console. Other Azure users in the same tenant cannot access clusters through the Cloud console other than those that they themselves created. + + When trying to access resources such as {{es}}, {{kib}}, {{ents}}, or APM in a deployment that was created by another Azure user, the following error is shown: + + :::{image} ../../../images/cloud-ec-marketplace-azure026.png + :alt: Error message displayed in the {{ecloud}} console: To access the resource {resource-name} + ::: + + Share deployment resources directly with other Azure users by [configuring Active Directory single sign-on with the {{es}} cluster](../../users-roles/cluster-or-deployment-auth/openid-connect.md#ec-securing-oidc-azure). + + +$$$azure-integration-azure-rbac$$$Does {{ecloud}} Azure Native ISV Service support recently introduced {{ecloud}} RBAC capability? +: Yes. Currently [{{ecloud}} RBAC capability](../../users-roles/cloud-organization/user-roles.md) is available only from the {{ecloud}} Console and is not integrated with Azure Portal. This means that the users who will interact with Elastic resources from Azure Portal will not be recognized by the {{ecloud}} RBAC policies. + +$$$azure-integration-prior-cloud-account$$$I already have an {{ecloud}} account, can I use this service? +: Yes. If you already have an {{ecloud}} account with the same email address as your Azure account you may need to contact `support@elastic.co`. + +$$$azure-integration-convert-trial$$$Can I sign up for an {{ecloud}} trial account and then convert to the {{ecloud}} Azure Native ISV Service? +: Yes. You can start a [free Elasticsearch Service trial](https://cloud.elastic.co/registration?page=docs&placement=docs-body) and then convert your account over to Azure. There are a few requirements: + + * Make sure when creating deployments in the trial account you specify Azure as the cloud provider. + * To convert your trial to the Azure marketplace you need to create a deployment in the Azure console. Just delete the new deployment if you don’t need it. After you create the new deployment your marketplace subscription is ready. + * Any deployments created during your trial won’t show up in the Azure console, since they weren’t created in Azure, but they are still accessible through the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) and you are billed for their usage. + + +$$$azure-integration-azure-tenant$$$Does {{es}} get deployed into my tenant in Azure? +: No. {{es}} resources deployed in an Azure tenant are managed by Elastic. The management capabilities associated with this tenant are the same as used to run Elastic’s managed service, which also allows users to deploy on Azure. + +$$$azure-integration-azure-tenant-info$$$What Azure tenant information does Elastic have access to? +: After you subscribe to {{ecloud}} through the Azure Native ISV Service, Elastic has access to the following Azure tenant information: + + * Data defined in the marketplace [Saas fulfillment Subscription APIs](https://docs.microsoft.com/en-us/azure/marketplace/partner-center-portal/pc-saas-fulfillment-subscription-api). + * The following additional data: + + * Marketplace subscription ID + * Marketplace plan ID + * Azure Account ID + * Azure Tenant ID + * Company + * First name + * Last name + * Country + + + Elastic can also access data from {{ecloud}} Azure Native ISV Service features, including [resource and activity log data](https://docs.microsoft.com/en-us/azure/azure-monitor/essentials/platform-logs-overview). This data is available to Elastic only if you enable it. By default, Elastic does not have access to this information. + + +$$$azure-integration-cli-api$$$What other methods are available to deploy {{es}}? +: Use any of the following methods: + + * **Deploy using Azure tools** + + * The Azure console + * [Azure Terraform](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/elastic_cloud_elasticsearch) + * The [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/elastic?view=azure-cli-latest) + * The Azure [REST API](https://docs.microsoft.com/en-us/rest/api/elastic) + * [PowerShell](https://docs.microsoft.com/en-us/powershell/module/az.elastic/?view=azps-8.0.0#elastic) + + * **Deploy using official Azure SDKs** + + * [Python](https://github.com/Azure/azure-sdk-for-python/blob/main/README.md) + * [Java](https://github.com/Azure/azure-sdk-for-java/blob/azure-resourcemanager-elastic_1.0.0-beta.1/README.md) + * [.NET](https://github.com/Azure/azure-sdk-for-net/blob/main/README.md) + * [Rust](https://github.com/Azure/azure-sdk-for-rust/blob/main/services/README.md) + + * **Deploy using {{ecloud}}** + + * The {{ecloud}} [console](https://cloud.elastic.co?page=docs&placement=docs-body) + * The {{ecloud}} [REST API](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html) + * The {{ecloud}} [command line tool](https://www.elastic.co/guide/en/ecctl/current/index.html) + * The {{ecloud}} [Terraform provider](https://registry.terraform.io/providers/elastic/ec/latest/docs) + + Note that when you use any of the {{ecloud}} methods, the {{es}} deployment will not be available in Azure. + + +$$$azure-integration-migrate$$$How do I migrate my data from the classic Azure marketplace account to the native integration? +: First create a new account configured with {{ecloud}} Azure Native ISV Service, then perform the migration as follows: + + 1. From your classic Azure marketplace account, navigate to the deployment and [configure a custom snapshot repository using Azure Blog Storage](../../tools/snapshot-and-restore/ec-azure-snapshotting.md). + 2. Using the newly configured snapshot repository, [create a snapshot](../../tools/snapshot-and-restore/create-snapshots.md) of the data to migrate. + 3. Navigate to Azure and log in as the user that manages the {{es}} resources. + 4. Before proceeding, ensure the new account is configured according to the [prerequisites](#azure-integration-get-started). + 5. Create a [new {{es}} resource](#azure-integration-get-started) for each existing deployment that needs migration from the classic Azure account. + 6. In the new {{es}} resource, follow the steps in [Restore from a snapshot](../../../manage-data/migrate.md#ec-restore-snapshots) to register the custom snapshot repository from Step 1. + 7. In the same set of steps, restore the snapshot data from the snapshot repository that you registered. + 8. Confirm the data has moved successfully into your new {{es}} resource on Azure. + 9. To remove the old Azure subscription and the old deployments, go to the [Azure SaaS page](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources) and unsubscribe from the `{{ecloud}} ({{es}})` marketplace subscription. This action triggers the existing deployments termination. + + +$$$azure-integration-no-inbox$$$Can I invite users to my organization, even if they cannot receive emails? +: You can add Azure users as members of your organization even if they don’t have an inbox. Please reach out to Elastic support. + + +## Billing [ec-azure-integration-billing-faq] + +$$$azure-integration-billing-which-subscription$$$Which Azure Subscription will be billed for my Elastic resources? +: The Azure Marketplace integrated billing posts all of the Elastic deployment/resources costs related to an {{ecloud}} organization to the Azure subscription you used to create your first-ever Elastic deployment/resource. This is the case even if your individual Elastic resources (deployments) are spread across different Azure subscriptions. For more detail, refer to [Integrated billing](#ec-azure-integration-billing-summary). + +$$$azure-integration-billing-different-deployments$$$How do I get different Elastic deployment/resources charges to different Azure Subscriptions? +: See [Integrated billing](#ec-azure-integration-billing-summary). To have different Elastic deployment/resources costs reported to different Azure subscriptions, they need to be in separate {{ecloud}} organizations. To create a separate {{ecloud}} organization from an Azure subscription, you will need to subscribe as a user who is not already part of an existing {{ecloud}} organization. + +$$$azure-integration-billing-elastic-costs$$$Why can’t I see Elastic resources costs in Azure Cost Explorer? +: The costs associated with Elastic resources (deployments) are reported under unassigned in the Azure Portal. Refer to [Understand your Azure external services charges](https://learn.microsoft.com/en-us/azure/cost-management-billing/understand/understand-azure-marketplace-charges) in the Microsoft Documentation to understand Elastic resources/deployments costs. For granular Elastic resources costs, refer to [Monitor and analyze your acccount usage](../../cloud-organization/billing/monitor-analyze-usage.md). + +$$$azure-integration-billing-deployments$$$Why don’t I see my individual Elastic resources (deployments) in the Azure Marketplace Invoice? +: The way Azure Marketplace Billing Integration works today, the costs for Elastic resources (deployments) are reported for an {{ecloud}} organization as a single line item, reported against the Marketplace SaaS ID. This includes the Elastic deployments created using the Azure Portal, API, SDK, or CLI, and also the Elastic deployments created directly from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) in the respective {{ecloud}} organization. For granular Elastic resources costs refer to [Monitor and analyze your acccount usage](../../cloud-organization/billing/monitor-analyze-usage.md). As well, for more detail refer to [Integrated billing](#ec-azure-integration-billing-summary). + + :::{image} ../../../images/cloud-ec-azure-billing-example.png + :alt: Example billing report in the {{ecloud}} console + ::: + + +$$$azure-integration-billing-instance-values$$$Why can’t I find Instance ID and Instance Name values from Azure Marketplace Invoice in the Azure Portal? +: With {{ecloud}} Azure Native ISV Service, the "instance name/ID" shown in the Azure Marketplace invoice is the Azure Marketplace SaaS identifier that represents an {{ecloud}} organization. For Microsoft Azure, `Microsoft.SaaS` (namespace) resources are used for billing Marketplace Resources - in this case, Elastic. + + For instance: Elastic Organization `Org1` is associated with a Marketplace SaaS (Microsoft.SaaS) asset `AzureElastic_GUID_NAME`. The Elastic resources (`Microsoft.Elastic`) `E1`, `E2`, and `E3` within `Org1` are all mapped to `AzureElastic_GUID_NAME`. + + `Microsoft.SaaS` (Instance name) asset is shown in the Azure Marketplace invoice and represents costs related to an {{ecloud}} organization and not individual Elastic resources (deployments). To see the cost breakdown for individual Elastic resources (deployments), refer to [Monitor and analyze your acccount usage](../../cloud-organization/billing/monitor-analyze-usage.md). + + :::{image} ../../../images/cloud-ec-azure-missing-instance-id.png + :alt: Instance ID not found error in Azure console + ::: + + + +## Managing your {{ecloud}} deployment [ec-azure-integration-managing-deployment] + +$$$azure-integration-whats-included$$$What is included in my {{ecloud}} deployment? +: Each {{ecloud}} deployment includes: + + * An {{es}} cluster + * A {{kib}} instance which provides data visualization and a front-end for the {stack} + * An APM server that allows you to easily collect application traces + * An {{ents}} instance that allows you to easily build a search experience with an intuitive interface + + +$$$azure-integration-how-to-access$$$How can I access my {{ecloud}} deployment? +: Navigate to the deployment overview page in Azure: + + 1. Select a deployment to open the deployment overview page. + + You now have a few options to access your deployment: + + * **{{es}} endpoint** - the URL for the {{es}} cluster itself + * **{{kib}} endpoint** - the UI for the {{stack}}, a great way for new users to get started + * **{{ecloud}}** - Open the **Advanced Settings** link to access the deployment in the {{ecloud}} console, to change the size of the deployment or upgrade it. + + +$$$azure-integration-modify-deployment$$$How can I modify my {{ecloud}} deployment? +: Modify your {{ecloud}} deployment in the {{ecloud}} console, which is accessed from the Azure UI through the **Advanced Settings** link on the deployment overview page. In the {{ecloud}} console you can perform a number of actions against your deployment, including: + + * [Re-size](ec-customize-deployment-components.md) to increase or decrease the amount of RAM, CPU, and storage available to your deployment, or to add additional availability zones. + * [Upgrade](../../upgrade/deployment-or-cluster.md) your deployment to a new {{stack}} version. + * Enable or disable individual {{stack}} components such as APM, Machine Learning, and {{ents}}. + * [Update {{stack}} user settings](edit-stack-settings.md) in the component YML files. + * [Add or remove custom plugins](add-plugins-extensions.md). + * [Configure IP filtering](../../security/traffic-filtering.md). + * [Monitor your {{ecloud}} deployment](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) to ensure it remains healthy. + * Add or remove API keys to use the [REST API](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html). + * [And more](cloud-hosted.md) + + +$$$azure-integration-delete-deployment$$$How can I delete my {{ecloud}} deployment? +: Delete the deployment directly from the Azure console. The delete operation performs clean-up activities in the Elastic console to ensure any running components are removed, so that no additional charges occur. + +$$$azure-integration-delete-resource-group$$$Can I delete the Azure Resource Group containing my deployment? +: If you delete an Azure Resource Group containing {{ecloud}} resources, the latter will be deleted automatically. However, you should not delete the Azure Resource Group containing the first deployment you created. The usage associated with any other Elastic deployment created outside of the first resource group will continue to get reported and charged against this resource group. If you want to stop all charges to this Resource Group, you should delete the individual deployments. + + +## Configuring logs and metrics [ec-azure-logs-and-metrics] + +$$$azure-integration-monitor$$$How do I monitor my existing Azure services? +: The {{ecloud}} Azure Native ISV Service simplifies logging for Azure services with the {{stack}}. This integration supports: + + * Azure subscription logs + * Azure resources logs (check [Supported categories for Azure Resource Logs](https://docs.microsoft.com/en-us/azure/azure-monitor/essentials/resource-logs-categories?WT.mc_id=Portal-Azure_Marketplace_Elastic) for examples) + + +::::{note} +If you want to send platform logs to a deployment that has [IP or Private Link traffic filters](../../security/traffic-filtering.md) enabled, then you need to contact [the Elastic Support Team](#azure-integration-support) to perform additional configurations. Refer support to the article [Azure++ Resource Logs blocked by Traffic Filters](https://support.elastic.co/knowledge/18603788). + +:::: + + +The following log types are not supported as part of this integration: + +* Azure tenant logs +* Logs from Azure compute services, such as Virtual Machines + +::::{note} +If your Azure resources and Elastic deployment are in different subscriptions, before creating diagnostic settings confirm that the `Microsoft.Elastic` resource provider is registered in the subscription in which the Azure resources exist. If not, register the resource provider following these steps: + +1. In Azure, navigate to **Subscriptions → Resource providers**. +2. Search for `Microsoft.Elastic` and check that it is registered. + +If you already created diagnostic settings before the `Microsoft.Elastic` resource provider was registered, delete and add the diagnostic setting again. + +:::: + + +In the Azure console, configure the ingestion of Azure logs into either a new or existing {{ecloud}} deployment: + +* When creating a new deployment, use the **Logs & metrics** tab in Azure to specify the log type and a key/value tag pair. Any Azure resources that match on the tag value automatically send log data to the {{ecloud}} deployment, once it’s been created. + +:::{image} ../../../images/cloud-ec-marketplace-azure004.png +:alt: The Logs & Metrics tab on the Create Elastic Resource page +::: + +* For existing deployments configure Azure logs from the deployment overview page in the Azure console. + +::::{important} +Note that following restrictions for logging: + +* Only logs from non-compute Azure services are ingested as part of the configuration detailed in this document. Logs from compute services, such as Virtual Machines, into the {{stack}} will be added in a future release. + +* The Azure services must be in one of the [supported regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html#ec-azure_regions). All regions will be supported in the future. + +:::: + + +::::{note} +Your Azure logs may sometimes contain references to a user `Liftr_Elastic`. This user is created automatically by Azure as part of the integration with {{ecloud}}. +:::: + + +To check which of your Azure resources are currently being monitored, navigate to your {{es}} deployment and open the **Monitored resources** tab. Each resource shows one of the following status indicators: + +* *Sending* - Logs are currently being sent to the {{es}} cluster. +* *Logs not configured* - Log collection is currently not configured for the resource. Open the **Edit tags** link to configure which logs are collected. For details about tagging resources, check [Use tags to organize your Azure resources and management hierarchy](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/tag-resources?tabs=json) in the Azure documentation. +* *N/A* - Monitoring is not available for this resource type. +* *Limit reached* - Azure resources can send diagnostic data to a maximum of five outputs. Data is not being sent to the {{es}} cluster because the output limit has already been reached. +* *Failed* - Logs are configured but failed to ship to the {{es}} cluster. For help resolving this problem you can [contact Support](#azure-integration-support). +* *Region not supported* - The Azure resource must be in one of the [supported regions](#ec-supported-regions). + +$$$azure-integration-ingest-metrics$$$How do I ingest metrics from my Azure services? +: Metrics are not supported as part of the current {{ecloud}} Azure Native ISV Service. This will be implemented in a future phase. Metrics can still be collected from all Azure services using Metricbeat. For details, check [Ingest other Azure metrics using the Metricbeat Azure module](../../../solutions/observability/cloud/monitor-microsoft-azure-with-beats.md#azure-step-four). + +$$$azure-integration-vm-extensions$$$How can I monitor my Azure virtual machines in {{es}}? +: You can monitor your Azure virtual machines by installing the Elastic Agent VM extension. Once enabled, the VM extension downloads the Elastic Agent, installs it, and enrols it to the Fleet Server. The Elastic Agent will then send system related logs and metrics to the {{ecloud}} cluster where you can find pre-built system dashboards showing the health and performance of your virtual machines. + + :::{image} ../../../images/cloud-ec-marketplace-azure010.png + :alt: A dashboard showing system metrics for the VM + ::: + + **Enabling and disabling VM extensions** + + To enable or disable a VM extension: + + 1. In Azure, navigate to your {{es}} deployment. + 2. Select the **Virtual machines** tab + 3. Select one or more virtual machines + 4. Choose **Install Extension** or **Uninstall Extension**. + + :::{image} ../../../images/cloud-ec-marketplace-azure011.png + :alt: The Virtual Machines page in Azure + ::: + + While it’s possible to enable or disable a VM extension directly from the VM itself, we recommend always enabling or disabling your {{es}} VM extensions from within the context of your {{es}} deployment. + + **Managing the Elastic Agent VM extension** + + Once installed on the virtual machine, you can manage Elastic Agent either from Fleet or locally on the host where it’s installed. We recommend managing the VM extension through Fleet, because it makes handling and upgrading the agents considerably easier. For more information on the Elastic Agent, check [Manage your Elastic Agents](https://www.elastic.co/guide/en/fleet/current/elastic-agent-installation.html). + + **Operating system compatibility matrix** + + The Azure Elastic Agent VM extension is supported on the following operating systems: + + | **Platform** | **Version** | + | --- | --- | + | Windows | 2008r2+ | + | CentOS | 6.10+ | + | Debian | 9,10 | + | Oracle | 6.8+ | + | RHEL | 7+ | + | Ubuntu | 16+ | + + + +## Troubleshooting [ec-azure-integration-troubleshooting] + +This section describes some scenarios that you may experience onboarding to {{ecloud}} through the Azure console. If you’re running into issues you can always [get support](#azure-integration-support). + +$$$azure-integration-authorization-access$$$I receive an error message about not having the required authorization. +: When trying to access {{ecloud}} resources, you may get an error message indicating that *the user must have the required authorization.* + + :::{image} ../../../images/cloud-ec-marketplace-azure026.png + :alt: Error message displayed in the {{ecloud}} console: To access the resource {resource-name} + ::: + + Elastic is not currently integrated with Azure user management, so sharing deployment resources through the Cloud console with other Azure users is not possible. However, sharing direct access to these resources is possible. For details, check [Is the {{ecloud}} Azure Native ISV Service connected with Azure user management?](#azure-integration-azure-user-management). + + +$$$azure-integration-deployment-failed-traffic-filter$$$My {{ecloud}} deployment creation failed. +: When creating a new {{ecloud}} deployment, the deployment creation may fail with a `Your deployment failed` error. The process results with a status message such as: + + ```txt + { + "code": "DeploymentFailed", + "message": "At least one resource deployment operation failed. Please list deployment operations for details. Please see https://aka.ms/DeployOperations for usage details.", + "details": [ + { + "code": "500", + "message": "An error occurred during deployment creation. Please try again. If the problem persists, please contact support@elastic.co." + } + ] + ``` + + One possible cause of a deployment creation failure is the default traffic filtering rules. Deployments fail to create if a previously created traffic filter has enabled the **Include by default** option. When this option is enabled, traffic to the deployment is blocked, including traffic that is part of the {{ecloud}} Azure Native ISV Service. As a result, some of the integration components are not successfully provisioned and the deployment creation fails. + + Follow these steps to resolve the problem: + + 1. Login to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). + 2. Go to the [Traffic filters page](https://cloud.elastic.co/deployment-features/traffic-filters). + 3. Edit the traffic filter and disable the **Include by default** option. + + :::{image} ../../../images/cloud-ec-marketplace-azure-traffic-filter-option.png + :alt: The Include by default option under Add to Deployments on the Traffic Filter page + ::: + + 4. In Azure, create a new {{ecloud}} deployment. + 5. After the deployment has been created successfully, go back to the [Traffic filters page](https://cloud.elastic.co/deployment-features/traffic-filters) in {{ecloud}} and re-enable the **Include by default** option. + + +If your deployment still does not create successfully, [contact the Elastic Support Team](#azure-integration-support) for assistance. + +$$$azure-integration-failed-sso$$$I can’t SSO into my {{ecloud}} deployment. +: When you try to access your {{ecloud}} deployment using single sign-on, the access may fail due to missing permission required by your Azure environment. + + You can review your user consent settings configuration following the instructions in [Configure how users consent to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent?tabs=azure-portal). To resolve this problem, contact your Azure Administrator. + + +$$$azure-integration-cant-see-deployment$$$I see some deployments in the {{ecloud}} console but not in the Azure Portal. +: Elastic Deployments created using the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), the [{{es}} Service API](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html), or the [{{ecloud}} Terraform provider](https://registry.terraform.io/providers/elastic/ec/latest/docs) are only visible through the {{ecloud}} Console. To have the necessary metadata to be visible in the Azure Portal, {{ecloud}} deployments need to be created in Microsoft Azure. + +::::{note} +Mimicking this metadata by manually adding tags to an {{ecloud}} deployment will not work around this limitation. Instead, it will prevent you from being able to delete the deployment using the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +:::: + + +$$$azure-integration-logs-not-ingested$$$My {{ecloud}} Azure Native ISV Service logs are not being ingested. +: * When you set up monitoring for your Azure services, if your Azure and Elastic resources are in different subscriptions, you need to make sure that the `Microsoft.Elastic` resource provider is registered in the subscription in which the Azure resources exist. Check [How do I monitor my existing Azure services?](#azure-integration-monitor) for details. +* If you are using [IP or Private Link traffic filters](../../security/traffic-filtering.md), please reach out to [the Elastic Support Team](#azure-integration-support). + + + +## Getting support [ec-getting-support] + +$$$azure-integration-support$$$How do I get support? +: Support is provided by Elastic. To open a support case: + + 1. Navigate to the deployment overview page in the Azure console. + 2. Click **New support request** from the menu. + 3. Click the link to launch the Elastic console and provide further details. + + The Elastic Support team responds based on the SLA response time of your subscription. + + :::{image} ../../../images/cloud-ec-marketplace-azure005.png + :alt: The New Support Request page in Azure + ::: + + + In case your {{ecloud}} resource is not fully set up and you’re not able to access the Support page, you can always send an email to `support@elastic.co`. + + +$$$azure-integration-change-level$$$How can I change my subscription level / support level? +: Your Elastic subscription level includes the support level. Check [How can I change my {{ecloud}} subscription level?](#azure-integration-change-subscription) to make an update. + + +$$$ec-supported-regions$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/change-hardware.md b/deploy-manage/deploy/elastic-cloud/change-hardware.md new file mode 100644 index 000000000..2e14ac4c9 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/change-hardware.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-change-hardware-for-a-specific-resource.html +--- + +# Change hardware [ec-change-hardware-for-a-specific-resource] + +The virtual hardware on which Elastic stack deployments run is defined by instance configurations. To learn more about what an instance configuration is, refer to [Instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations). + +When a deployment is created, each Elasticsearch tier and stateless resource (e.g., Kibana, Enterprise Search) gets an instance configuration assigned to it, based on the hardware profile used. The combination of instance configurations defined within each hardware profile is designed to provide the best possible outcome for each use case. Therefore, it is not advisable to use instance configurations that are not specified on the hardware profile, except in specific situations in which we may need to migrate an Elasticsearch tier or stateless resource to a different hardware type. An example of such a scenario is when a cloud provider stops supporting a hardware type in a specific region. + + +## Migrate to a different instance configuration using the API [ec_migrate_to_a_different_instance_configuration_using_the_api] + +Hardware profile migrations are possible to perform through the Elastic Cloud console, however, migrating a specific tier or resource to a different instance configuration can only be achieved through the API. + +Prerequisites: + +* A valid Elastic Cloud [API key](../../api-keys/elastic-cloud-api-keys.md) (`$EC_API_KEY`) + +Follow these steps to migrate to a different instance configuration, replacing the default `$EC_API_KEY` value with your actual API key: + +1. From the [list of instance configurations available for each region](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html), select the target instance configuration you want to migrate to. +2. Get the deployment update payload from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) **Edit** page, by selecting **Equivalent API request**, and store it in a file called `migrate_instance_configuration.json`. + + Example payload containing relevant data for migrating the hot Elasticsearch tier: + + ```json + { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "gcp.es.datahot.n2.68x10x45", + "instance_configuration_version": 1, + ``` + +3. Set the `instance_configuration_id` field of the Elasticsearch tier or stateless resource you want to migrate to the **Instance ID** of the instance configuration selected in step 1. +4. If the `instance_configuration_version` field is defined for that Elasticsearch tier or stateless resource, remove it from the payload. + + Following is the update that would be required to migrate the example above to the `gcp.es.datahot.n2.68x10x95` instance configuration: + + ```json + { + "resources": { + "elasticsearch": [ + { + "plan": { + "cluster_topology": [ + { + "id": "hot_content", + "instance_configuration_id": "gcp.es.datahot.n2.68x10x95", + ``` + +5. Use the payload to update your deployment and perform the instance configuration migration. + + ```sh + curl -XPUT https://api.elastic-cloud.com/api/v1/deployments/{deployment_id} \ + -H "Authorization: ApiKey $EC_API_KEY" \ + -H 'Content-Type: application/json' \ + -d @migrate_instance_configuration.json + ``` + + +::::{note} +You can perform multiple instance configuration migrations in the same request. +:::: + + +::::{warning} +Having an instance configuration mismatch between the deployment and the hardware profile will cause the Elastic Cloud console to announce that there is a **Newer version available** for the hardware profile. Any hardware profile migration performed through the Elastic Cloud console will cause the instance configurations to be reset to the values in the hardware profile. +:::: + + + +## Deprecated instance configurations (ICs) and deployment templates (DTs) [ec-deprecated-icdt] + +A list of deprecated and valid ICs/DTs can be found on the [Available regions, deployment templates and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) page, as well as through the API, using `hide_deprecated` to return valid ICs/DTs. For example, to return valid ICs/DTs the following request can be used: `https://api.elastic-cloud.com/api/v1/deployments/templates?region=us-west-2&hide_deprecated=true`. To list only the deprecated ones, this can be used: `https://api.elastic-cloud.com/api/v1/deployments/templates?region=us-west-2&metadata=legacy:true`. + +If a deprecated IC/DT is already in use, it can continue to be used. However, creating or migrating to a deprecated IC/DT is no longer possible and will result in a plan failing. In order to migrate to a valid IC/DT, navigate to the **Edit hardware profile** option in the Cloud UI or use the [Deployment API](https://www.elastic.co/docs/api/doc/cloud/operation/operation-migrate-deployment-template). diff --git a/deploy-manage/deploy/elastic-cloud/cloud-hosted.md b/deploy-manage/deploy/elastic-cloud/cloud-hosted.md new file mode 100644 index 000000000..d6dd7fbe4 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/cloud-hosted.md @@ -0,0 +1,51 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-getting-started.html + - https://www.elastic.co/guide/en/cloud/current/ec-prepare-production.html + - https://www.elastic.co/guide/en/cloud/current/ec-faq-getting-started.html + - https://www.elastic.co/guide/en/cloud/current/ec-about.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-configure.html +--- + +# Cloud Hosted + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/338 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-getting-started.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-prepare-production.md +% Notes: link roundup is good but the plan for prod content is not needed here +% - [ ] ./raw-migrated-files/cloud/cloud/ec-faq-getting-started.md +% Notes: extract what we can from faq +% - [ ] ./raw-migrated-files/cloud/cloud/ec-about.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-configure.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$faq-aws-difference$$$ + +$$$faq-aws$$$ + +$$$faq-config$$$ + +$$$faq-elastic$$$ + +$$$faq-full-stack$$$ + +$$$faq-limit$$$ + +$$$faq-subscriptions$$$ + +$$$faq-trial$$$ + +$$$faq-vs-aws$$$ + +$$$faq-what$$$ + +$$$faq-where$$$ + +$$$faq-x-pack$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/configure.md b/deploy-manage/deploy/elastic-cloud/configure.md new file mode 100644 index 000000000..1cb52996a --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/configure.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-customize-deployment.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-configure-settings.html +--- + +# Configure + +% What needs to be done: Refine + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-customize-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-configure-settings.md \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/create-an-elastic-cloud-hosted-deployment.md b/deploy-manage/deploy/elastic-cloud/create-an-elastic-cloud-hosted-deployment.md new file mode 100644 index 000000000..d6e8204ea --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/create-an-elastic-cloud-hosted-deployment.md @@ -0,0 +1,59 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-create-deployment.html +--- + +# Create an Elastic Cloud Hosted deployment [ec-create-deployment] + +An Elastic Cloud deployment includes Elastic Stack components such as Elasticsearch, Kibana, and other features, allowing you to store, search, and analyze your data. You can spin up a proof-of-concept deployment to learn more about what Elastic can do for you. + +::::{note} +To explore Elasticsearch Service and its solutions, create your first deployment by following one of these [getting started guides](https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current/getting-started-guides.html). If you are instead interested in serverless Elastic Cloud, check the [serverless documentation](https://docs.elastic.co/serverless). +:::: + + +You can also create a deployment using the [Elastic Cloud API](https://www.elastic.co/guide/en/cloud/current/Deployment_-_CRUD.html). This can be an interesting alternative for more advanced needs, such as for [creating a deployment encrypted with your own key](../../security/encrypt-deployment-with-customer-managed-encryption-key.md). + +1. Log in to your [cloud.elastic.co](https://cloud.elastic.co/login) account and select **Create deployment** from the Elasticsearch Service main page: + + :::{image} ../../../images/cloud-ec-login-first-deployment.png + :alt: Log in to create a deployment + ::: + + +Once you are on the **Create deployment** page, you can create the deployment with the defaults assigned, where you can edit the basic settings, or configure more advanced settings. + +1. From the main **Settings**, you can change the cloud provider and region that host your deployment, the stack version, and the hardware profile, or restore data from another deployment (**Restore snapshot data**): + + :::{image} ../../../images/cloud-ec-create-deployment.png + :alt: Create deployment + ::: + + Cloud provider + : The cloud platform where you’ll deploy your deployment. We support: Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. You do not need to provide your own keys. + + Region + : The cloud platform’s region your deployment will live. If you have compliance or latency requirements, you can create your deployment in any of our [supported regions](https://www.elastic.co/guide/en/cloud/current/ec-reference-regions.html). The region should be as close as possible to the location of your data. + + Hardware profile + : This allows you to configure the underlying virtual hardware that you’ll deploy your Elastic Stack on. Each hardware profile provides a unique blend of storage, RAM and vCPU sizes. You can select a hardware profile that’s best suited for your use case. For example CPU Optimized if you have a search-heavy use case that’s bound by compute resources. For more details, check the [hardware profiles](ec-configure-deployment-settings.md#ec-hardware-profiles) section. You can also view the [virtual hardware details](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html) which powers hardware profiles. With the **Advanced settings** option, you can configure the underlying virtual hardware associated with each profile. + + Version + : The Elastic Stack version that will get deployed. Defaults to the latest version. Our [version policy](available-stack-versions.md) describes which versions are available to deploy. + +2. Expand **Advanced settings** to configure your deployment for encryption using a customer-managed key, autoscaling, storage, memory, and vCPU. Check [Customize your deployment](configure.md) for more details. + + ::::{tip} + Trial users won’t find the Advanced settings when they create their first deployment. This option is available on the deployment’s edit page once the deployment is created. + :::: + +3. Select **Create deployment**. It takes a few minutes before your deployment gets created. While waiting, you are prompted to save the admin credentials for your deployment which provides you with superuser access to Elasticsearch. Keep these credentials safe as they are shown only once. These credentials also help you [add data using Kibana](../../../manage-data/ingest.md). If you need to refresh these credentials, you can [reset the password](../../users-roles/cluster-or-deployment-auth/built-in-users.md). +4. Once the deployment is ready, select **Continue** to open the deployment’s main page. From here, you can start [ingesting data](../../../manage-data/ingest.md) or simply [try a sample data](../../../explore-analyze/overview/kibana-quickstart.md#gs-get-data-into-kibana) set to get started. + + At any time, you can manage and [adjust the configuration](configure.md) of your deployment to your needs, add extra layers of [security](../../users-roles/cluster-or-deployment-auth.md), or (highly recommended) set up [health monitoring](../../monitor/stack-monitoring.md). + + :::{image} ../../../images/cloud-ec-deployment-mainpage.png + :alt: ESS Deployment main page + ::: + + diff --git a/deploy-manage/deploy/elastic-cloud/create-an-organization.md b/deploy-manage/deploy/elastic-cloud/create-an-organization.md new file mode 100644 index 000000000..bdbf3f277 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/create-an-organization.md @@ -0,0 +1,24 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-getting-started-trial.html + - https://www.elastic.co/guide/en/serverless/current/general-sign-up-trial.html + - https://www.elastic.co/guide/en/cloud/current/ec-getting-started-existing-email.html +--- + +# Create an organization + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/336 + +% Scope notes: merge + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-getting-started-trial.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-sign-up-trial.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-getting-started-existing-email.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$general-sign-up-trial-what-is-included-in-my-trial$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-aws-marketplace.md b/deploy-manage/deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-aws-marketplace.md new file mode 100644 index 000000000..532645aa5 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-aws-marketplace.md @@ -0,0 +1,30 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-aws-marketplace-conversion.html +--- + +# Create a monthly pay-as-you-go subscription on AWS Marketplace [ec-aws-marketplace-conversion] + +When subscribing to an annual prepaid subscription to Elastic Cloud on AWS Marketplace, please follow these instructions to obtain a separate pay-as-you-go subscription. This subscription will allow us to continue your Elastic Cloud service through the Marketplace once the contract is expired. You will not get charged twice for the usage under the annual contract. + +1. Log in to AWS under the same Account ID that you will use to accept the Annual Private Offer. +2. Go to the [AWS Marketplace subscription page for Elastic Cloud pay-as-you-go](https://aws.amazon.com/marketplace/saas/ordering?productId=bb253a6c-e775-4634-bdf0-17bd56a69c36&offerId=b2uzdkwqj7177fqhm39o4snxy). +3. Click **Subscribe** to create an AWS Marketplace subscription under the selected AWS Account. + +:::{image} ../../../images/cloud-aws-subscribe-button.png +:alt: Subscribe to Elastic Cloud on AWS Marketplace +::: + +No further steps required in AWS. Ignore the steps 1 to 3 that appear on the right side of the AWS page. + +:::{image} ../../../images/cloud-aws-mp-steps-to-skip.png +:alt: AWS panel with steps to skip +::: + +You should now see the monthly *Pay as you go* subscription for Elastic Cloud in your AWS **Manage subscriptions** page. + +From the top-right corner, you can check that the Account ID is the same account that has your Elastic Cloud annual subscription. + +:::{image} ../../../images/cloud-aws-mp-manage-subscriptions.png +:alt: Account ID on top-right menu +::: diff --git a/deploy-manage/deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-gcp-marketplace.md b/deploy-manage/deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-gcp-marketplace.md new file mode 100644 index 000000000..1569c2dd1 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-gcp-marketplace.md @@ -0,0 +1,15 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-gcp-marketplace-conversion.html +--- + +# Create a monthly pay-as-you-go subscription on GCP Marketplace [ec-gcp-marketplace-conversion] + +When subscribing to an annual prepaid subscription to Elastic Cloud on GCP Marketplace, please follow these instructions to obtain a separate pay-as-you-go subscription. This subscription will allow us to continue your Elastic Cloud service through the Marketplace once the contract is expired. You will not get charged twice for the usage under the annual contract. + +1. Go to the [GCP Marketplace listing page for Elastic Cloud pay-as-you-go](https://console.cloud.google.com/marketplace/product/elastic-prod/elastic-cloud). +2. Click **Subscribe** to create a GCP Marketplace subscription under the selected GCP Billing Account. + +No further steps required in GCP. You do not need to register for a new Elastic Cloud organization if you are already using Elastic Cloud. + +You should now see the monthly *Pay as you go* subscription for Elastic Cloud in your [GCP Marketplace Orders page](https://console.cloud.google.com/marketplace/orders). diff --git a/deploy-manage/deploy/elastic-cloud/create-serverless-project.md b/deploy-manage/deploy/elastic-cloud/create-serverless-project.md new file mode 100644 index 000000000..a3ed45d3c --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/create-serverless-project.md @@ -0,0 +1,22 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/serverless-get-started.html +--- + +# Create a serverless project [serverless-get-started] + +There are two options to create serverless projects: + +* If you are a new user, [sign up for a free 14-day trial](https://cloud.elastic.co/serverless-registration) to create a serverless project. For more information about the Elastic Cloud trials, check [Trial features](create-an-organization.md#general-sign-up-trial-what-is-included-in-my-trial). +* If you are an existing customer, [log in to Elastic Cloud](https://cloud.elastic.co/login). On the home page, you will see a new option to create serverless projects. + +Choose the type of project that matches your needs and we’ll help you get started with our solution guides. + +| | | +| --- | --- | +| | | +| ![elasticsearch](https://www.elastic.co/docs/assets/images/serverless-elasticsearch.png "") | Elasticsearch
Build custom search applications with Elasticsearch.

[**View guide →**](../../../solutions/search.md)
| +| ![observability](https://www.elastic.co/docs/assets/images/serverless-observability.png "") | Observability
Monitor applications and systems with Elastic Observability.

[**View guide →**](../../../solutions/observability.md)
| +| ![security](https://www.elastic.co/docs/assets/images/serverless-security.png "") | Security
Detect, investigate, and respond to threats with Elastic Security.

[**View guide →**](../../../solutions/security/elastic-security-serverless.md)
| +| | | + diff --git a/deploy-manage/deploy/elastic-cloud/custom-endpoint-aliases.md b/deploy-manage/deploy/elastic-cloud/custom-endpoint-aliases.md new file mode 100644 index 000000000..d64decd3f --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/custom-endpoint-aliases.md @@ -0,0 +1,14 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-regional-deployment-aliases.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-regional-deployment-aliases.html +--- + +# Custom endpoint aliases + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-regional-deployment-aliases.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-regional-deployment-aliases.md \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md b/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md new file mode 100644 index 000000000..64b2121ac --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md @@ -0,0 +1,169 @@ +--- +navigation_title: "Serverless differences" +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/elasticsearch-differences.html +--- + + + +# Differences from other Elasticsearch offerings [elasticsearch-differences] + + +[{{es-serverless}}](../../../solutions/search.md) handles all the infrastructure management for you, providing a fully managed {{es}} service. + +If you’ve used {{es}} before, you’ll notice some differences in how you work with the service on {{serverless-full}}, because a number of APIs and settings are not required for serverless projects. + +This guide helps you understand what’s different, what’s available, and how to work effectively when running {{es}} on {{serverless-full}}. + + +## Fully managed infrastructure [elasticsearch-differences-serverless-infrastructure-management] + +{{es-serverless}} manages all infrastructure automatically, including: + +* Cluster scaling and optimization +* Node management and allocation +* Shard distribution and replication +* Resource utilization and monitoring + +This fully managed approach means many traditional {{es}} infrastructure APIs and settings are not available to end users, as detailed in the following sections. + + +## Index size guidelines [elasticsearch-differences-serverless-index-size] + +To ensure optimal performance, follow these recommendations for sizing individual indices on {{es-serverless}}: + +| Use case | Maximum index size | Project configuration | +| --- | --- | --- | +| Vector search | 150GB | Vector optimized | +| General search (non data-stream) | 300GB | General purpose | +| Other uses (non data-stream) | 600GB | General purpose | + +For large datasets that exceed the recommended maximum size for a single index, consider splitting your data across smaller indices and using an alias to search them collectively. + +These recommendations do not apply to indices using better binary quantization (BBQ). Refer to [vector quantization](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-quantization) in the core {{es}} docs for more information. + + +## API availability [elasticsearch-differences-serverless-apis-availability] + +Because {{es-serverless}} manages infrastructure automatically, certain APIs are not available, while others remain fully accessible. + +::::{tip} +Refer to the [{{es-serverless}} API reference](https://www.elastic.co/docs/api/doc/elasticsearch-serverless) for a complete list of available APIs. + +:::: + + +The following categories of operations are unavailable: + +Infrastructure operations +: * All `_nodes/*` operations +* All `_cluster/*` operations +* Most `_cat/*` operations, except for index-related operations such as `/_cat/indices` and `/_cat/aliases` + + +Storage and backup +: * All `_snapshot/*` operations +* Repository management operations + + +Index management +: * `indices/close` operations +* `indices/open` operations +* Recovery and stats operations +* Force merge operations + + +When attempting to use an unavailable API, you’ll receive a clear error message: + +```json +{ + "error": { + "root_cause": [ + { + "type": "api_not_available_exception", + "reason": "Request for uri [/] with method [] exists but is not available when running in serverless mode" + } + ], + "status": 410 + } +} +``` + + +## Settings availability [elasticsearch-differences-serverless-settings-availability] + +In {{es-serverless}}, you can only configure [index-level settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-modules-settings). Cluster-level settings and node-level settings are not required by end users and the `elasticsearch.yml` file is fully managed by Elastic. + +Available settings +: **Index-level settings**: Settings that control how {{es}} documents are processed, stored, and searched are available to end users. These include: + + * Analysis configuration + * Mapping parameters + * Search/query settings + * Indexing settings such as `refresh_interval` + + +Managed settings +: **Infrastructure-related settings**: Settings that affect cluster resources or data distribution are not available to end users. These include: + + * Node configurations + * Cluster topology + * Shard allocation + * Resource management + + + +## Feature availability [elasticsearch-differences-serverless-feature-categories] + +Some features that are available in Elastic Cloud Hosted and self-managed offerings are not available in {{es-serverless}}. These features have either been replaced by a new feature, are planned to be released in future, or are not applicable in the new serverless architecture. + + +### Replaced features [elasticsearch-differences-serverless-features-replaced] + +These features have been replaced by a new feature and are therefore not available on {{es-serverless}}: + +* **Index lifecycle management ({{ilm-init}})** is not available, in favor of [**data stream lifecycle**](../../../manage-data/data-store/index-basics.md). + + In an Elastic Cloud Hosted or self-managed environment, {{ilm-init}} lets you automatically transition indices through data tiers according to your performance needs and retention requirements. This allows you to balance hardware costs with performance. {{es-serverless}} eliminates this complexity by optimizing your cluster performance for you. + + Data stream lifecycle is an optimized lifecycle tool that lets you focus on the most common lifecycle management needs, without unnecessary hardware-centric concepts like data tiers. + +* **Watcher** is not available, in favor of [**Alerts**](../../../explore-analyze/alerts/kibana.md#rules-alerts). + + Kibana Alerts allows rich integrations across use cases like APM, metrics, security, and uptime. Prepackaged rule types simplify setup and hide the details of complex, domain-specific detections, while providing a consistent interface across Kibana. + + + +### Planned features [elasticsearch-differences-serverless-feature-planned] + +The following features are planned for future support in all {{serverless-full}} projects: + +* Reindexing from remote clusters +* Cross-project search and replication +* Snapshot and restore +* Migrations from non-serverless deployments +* Audit logging +* Clone index API +* Traffic filtering and VPCs + +The following {{es-serverless}} project-specific features are planned for future support: + +* [Behavioral Analytics](../../../solutions/search/site-or-app/behavioral-analytics.md) +* [Search Applications](../../../solutions/search/applications.md) +* Managed web crawler + + You can use the [self-managed web crawler](https://github.com/elastic/crawler) in the meantime. + +* Managed Search connectors + + You can use [self-managed Search connectors](https://www.elastic.co/guide/en/elasticsearch/reference/current/es-build-connector.html) in the meantime. + + + +### Unplanned features [elasticsearch-differences-serverless-feature-unavailable] + +The following features are not available in {{es-serverless}} and are not planned for future support: + +* [Custom plugins and bundles](https://www.elastic.co/guide/en/cloud/current/ec-custom-bundles.html) +* [{{es}} for Apache Hadoop](https://www.elastic.co/guide/en/elasticsearch/hadoop/current/reference.html) +* [Scripted metric aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-scripted-metric-aggregation.html) diff --git a/deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile.md b/deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile.md new file mode 100644 index 000000000..28e198d3d --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile.md @@ -0,0 +1,204 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-change-hardware-profile.html +--- + +# Change hardware profiles [ec-change-hardware-profile] + +Deployment [hardware profiles](ec-configure-deployment-settings.md#ec-hardware-profiles) deploy the Elastic Stack on virtual hardware. Each hardware profile has a different blend of storage, RAM, and vCPU. + +Elastic Cloud regularly introduces new hardware profiles to provide: + +* More optimal hardware for applications in the Elastic Stack. +* Cost efficiencies when new hardware from Cloud providers becomes available. + +::::{tip} +The Elastic Cloud console indicates when a new version of a hardware profile is available in the overview page for your deployment, under the Hardware profile section. +:::: + + +## Change the hardware profile using the Elastic Cloud console [ec_change_the_hardware_profile_using_the_elastic_cloud_console] + +### Upgrade to the newest version of your current hardware profile [ec_upgrade_to_the_newest_version_of_your_current_hardware_profile] + +Note that if there’s no indication that a newer version is available, that means that your deployment is already running on the latest version of that hardware profile. + +1. On the deployment overview page, next to your current hardware profile where there is indication of a newer available version, select **Edit**. + + :::{image} ../../../images/cloud-ec-new-hardware-profile-version.png + :alt: Badge indicating new hardware profile version + ::: + +2. Preview the changes for the new hardware profile version. + + :::{image} ../../../images/cloud-ec-preview-hardware-profile.png + :alt: Notification showing that a new profile version is there + ::: + + The configuration screen summarizes hardware changes for each component of your deployment. + + :::{image} ../../../images/cloud-ec-preview-profile-changes.png + :alt: Preview of the changes between the 2 versions of the hardware profile + ::: + +3. Select **Update** to apply the change. + + +### Change to a different hardware profile [ec_change_to_a_different_hardware_profile] + +When the current hardware profile of your deployment isn’t the most optimal one available for your usage, you can change it as follows: + +1. On the deployment overview page, next to your current hardware profile, select **Edit**. +2. Select the hardware profile you wish to change to. The configuration screen summarizes hardware changes for each component of your deployment. + + :::{image} ../../../images/cloud-ec-preview-different-profile-changes.png + :alt: Preview of the changes between the 2 hardware profiles + ::: + +3. Select **Update** to apply the change. + +::::{note} +If your deployment is configured for high availability, the hardware profile change does not impact your ability to read and write from the deployment as the change is rolled out instance by instance. Refer to [Plan for production](cloud-hosted.md) to learn about high availability (HA) and how to configure your deployment as HA. +:::: + + + + +## Change the hardware profile using the API [ec_change_the_hardware_profile_using_the_api] + +Prerequisites: + +* A valid Elastic Cloud [API key](../../api-keys/elastic-cloud-api-keys.md) (`$EC_API_KEY`) +* The deployment ID of the deployment you wish to modify (`{{deployment_id}}`) + +Replace those values with your actual API key and deployment ID in the following instructions. + +1. Get the current API payload for your deployment. + + ```sh + curl \ + -H "Authorization: ApiKey $EC_API_KEY" \ + "https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}" + ``` + +2. Using the API payload for your deployment, determine the following: + + * Your current `deployment_template` ID. The template ID corresponds to the hardware profile used for your deployment. + + ```json + "resources":{ + "elasticsearch":[ + { + "ref_id":"main-elasticsearch", + "id":"$CLUSTER_ID", + "region":"gcp-us-central1", + "info":{ + "cluster_id":"$CLUSTER_ID", + "cluster_name":"$CLUSTER_NAME", + "deployment_id":"$DEPLOYMENT_ID", + "plan_info":{ + "current":{ + "plan":{ + "deployment_template":{ + "id":"gcp-cpu-optimized-v5" + }, + ``` + + * The region that your deployment is in: + + ```json + "resources":{ + "elasticsearch":[ + { + "ref_id":"main-elasticsearch", + "id":"$DEPLOYMENT_ID", + "region":"gcp-us-central1", + ``` + +3. Check the [hardware profiles available](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) for the region that your deployment is in and find the template ID of the deployment hardware profile you’d like to use. + + ::::{tip} + If you wish to update your hardware profile to the latest version available for that same profile, locate the template ID corresponding to the `deployment_template` you retrieved at step 2, but without the version information. For example, if your deployment’s current hardware profile is `gcp-cpu-optimized-v5`, use `gcp-cpu-optimized` as a template ID to update your deployment. + :::: + +4. Get the API payload for your deployment based on the new template ID. + + ```sh + curl -XGET https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/migrate_template?template_id={new_template_id} \ + -H "Authorization: ApiKey $EC_API_KEY" > migrate_deployment.json + ``` + +5. Use the payload returned to update your deployment to use the hardware profile. + + ```sh + curl -XPUT https://api.elastic-cloud.com/api/v1/deployments/{deployment_id} \ + -H "Authorization: ApiKey $EC_API_KEY" \ + -H 'Content-Type: application/json' \ + -d @migrate_deployment.json + ``` + + + +## List of hardware profiles [ec_list_of_hardware_profiles] + +### Storage optimized [ec-profiles-storage] + +Your Elasticsearch data nodes are optimized for high I/O throughput. Use this profile if you are new to Elasticsearch or don’t need to run a more specialized workload. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Good for most ingestion use cases with 7-10 days of data available for fast access. Also good for light search use cases without heavy indexing or CPU needs. + + +### Storage optimized (dense) [ec-profiles-storage-dense] + +Your Elasticsearch data nodes are optimized for high I/O throughput. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Ideal for ingestion use cases with more than 10 days of data available for fast access. Also, good for light search use cases with very large data sets. + + +### CPU optimized [ec-profiles-compute-optimized] + +This profile runs CPU-intensive workloads faster. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Consider this configuration for ingestion use cases with 1-4 days of data available for fast access and for search use cases with indexing and querying workloads. Provides the most CPU resources per unit of RAM. + + +### CPU optimized (ARM) [ec-profiles-compute-optimized-arm] + +This profile is similar to CPU optimized profile but is powered by AWS Graviton2 instances. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Consider this configuration for ingestion use cases with 1-4 days of data available for fast access and for search use cases with indexing and querying workloads. Provides the most CPU resources per unit of RAM. + + +### Vector search optimized (ARM) [ec-profiles-vector-search] + +This profile is suited for Vector search, Generative AI and Semantic search optimized workloads. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Optimized for applications that leverage Vector Search and/or Generative AI. Also the optimal choice for utilizing ELSER for semantic search applications. Broadly suitable for all semantic search, text embedding, image search, and other Vector Search use cases. + + +### General purpose [ec-profiles-general-purpose] + +This profile runs CPU-intensive workloads faster . You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Suitable for ingestion use cases with 5-7 days of data available for fast access. Also good for search workloads with less-frequent indexing and medium to high querying loads. Provides a balance of storage, memory, and CPU. + + +### General purpose (ARM) [ec-profiles-general-purpose-arm] + +This profile is similar to the General purpose profile but is powered by AWS Graviton2 instances. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) for each cloud provider. + +**Ideal use case** + +Suitable for ingestion use cases with 5-7 days of data available for fast access. Also good for search workloads with less-frequent indexing and medium to high querying loads. Provides a balance of storage, memory, and CPU. diff --git a/deploy-manage/deploy/elastic-cloud/ec-configure-deployment-settings.md b/deploy-manage/deploy/elastic-cloud/ec-configure-deployment-settings.md new file mode 100644 index 000000000..d096be0d7 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ec-configure-deployment-settings.md @@ -0,0 +1,68 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-configure-deployment-settings.html +--- + +# What deployment settings are available? [ec-configure-deployment-settings] + +The following deployment settings are available: + + +## Cloud provider [ec_cloud_provider] + +Selects a cloud platform where your {{es}} clusters and {{kib}} instances will be hosted. Elasticsearch Service currently supports Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. + + +## Region [ec_region] + +Regions represent data centers in a geographic location, where your deployment will be located. When choosing a region, the general rule is to choose one as close to your application servers as possible in order to minimize network delays. + +::::{tip} +You can select your cloud platform and region only when you create a new deployment, so pick ones that works for you. They cannot be changed later. Different deployments can use different platforms and regions. +:::: + + + +## Hardware profile [ec-hardware-profiles] + +Elastic Cloud deploys Elastic Stack components into a *hardware profile* which provides a unique blend of storage, memory and vCPU. This gives you more flexibility to choose the hardware profile that best fits for your use case. For example, *Compute Optimized* deploys Elasticsearch on virtual hardware that provides high [vCPU](../../monitor/monitoring-data/ec-vcpu-boost-instance.md) which can help search-heavy use cases return queries quickly. + +Under the covers, hardware profiles leverage virtualized instances from a cloud provider, such as Amazon Web Services, Google Compute Platform, and Microsoft Azure. You don’t interact with the cloud provider directly, but we do document what we use for your reference. To learn more, check [Elasticsearch Service Hardware](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html). + +The components of the Elastic Stack that we support as part of a deployment are called *instances* and include: + +* Elasticsearch data tiers and master nodes +* Machine Learning (ML) nodes +* Kibana instances +* APM and Fleet instances +* Integrations Server instances +* Enterprise Search instances + +When you [create your deployment](create-an-elastic-cloud-hosted-deployment.md), you can choose the hardware profile that best fits your needs, and configure it with the **Advanced settings** option. Depending on the cloud provider that you select, you can adjust the size of Elasticsearch nodes, or configure your Kibana, APM & Fleet, and Enterprise Search instances. As your usage evolves, you can [change the hardware profile](ec-change-hardware-profile.md) of your deployment. + +::::{note} +Elastic Agent, Beats, and Logstash are components of the Elastic Stack that are not included in the hardware profiles as they are installed outside of Elastic Cloud. +:::: + + + +## Version [ec_version] + +Elastic Stack uses a versions code that is constructed of three numbers separated by dots: the leftmost number is the number of the major release, the middle number is the number of the minor release and the rightmost number is the number of the maintenance release (e.g., 8.3.2 means major release 8, minor release 3 and maintenance release 2). + +You might sometimes notice additional versions listed in the user interface beyond the versions we currently support and maintain, such as [release candidate builds](available-stack-versions.md#ec-release-builds) and older versions. If a version is listed in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), it can be deployed. + +To learn about how we support {{es}} versions in Elasticsearch Service, check [Version Policy](available-stack-versions.md). + +You can always upgrade {{es}} versions, but you cannot downgrade. To learn more about upgrading versions of {{es}} and best practices for major version upgrades, check [Version Upgrades](../../upgrade/deployment-or-cluster.md). + + +## Snapshot source [ec_snapshot_source] + +To create a deployment from a snapshot, select the snapshot source. You need to [configure snapshots](../../tools/snapshot-and-restore.md) and establish a snapshot lifecycle management policy and repository before you can restore from a snapshot. The snapshot options depend on the stack version the deployment is running. + + +## Name [ec_name] + +This setting allows you to assign a more human-friendly name to your cluster which will be used for future reference in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). Common choices are dev, prod, test, or something more domain specific. + diff --git a/deploy-manage/deploy/elastic-cloud/ec-customize-deployment-components.md b/deploy-manage/deploy/elastic-cloud/ec-customize-deployment-components.md new file mode 100644 index 000000000..01765f415 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ec-customize-deployment-components.md @@ -0,0 +1,150 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-customize-deployment-components.html +--- + +# How can I customize the components of my deployment? [ec-customize-deployment-components] + +When you create or edit an existing deployment, you can fine-tune the capacity, add extensions, and select additional features. + + +## Autoscaling [ec-customize-autoscaling] + +Autoscaling reduces some of the manual effort required to manage a deployment by adjusting the capacity as demands on the deployment change. Currently, autoscaling is supported to scale {{es}} data tiers upwards, and to scale machine learning nodes both upwards and downwards. Check [Deployment autoscaling](../../autoscaling.md) to learn more. + + +## {{es}} [ec-cluster-size] + +Depending upon how much data you have and what queries you plan to run, you need to select a cluster size that fits your needs. There is no silver bullet for deciding how much memory you need other than simply testing it. The [cluster performance metrics](../../monitor/stack-monitoring.md) in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) can tell you if your cluster is sized appropriately. You can also [enable deployment monitoring](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) for more detailed performance metrics. Fortunately, you can change the amount of memory allocated to the cluster later without any downtime for HA deployments. + +To change a cluster’s topology, from deployment management, select **Edit deployment** from the **Actions** dropdown. Next, select a storage and RAM setting from the **Size per zone** drop-down list, and save your changes. When downsizing the cluster, make sure to have enough resources to handle the current load, otherwise your cluster will be under stress. + +:::{image} ../../../images/cloud-ec-capacity.png +:alt: Capacity slider to adjust {{es}} cluster size +::: + +For trials, larger sizes are not available until you [add a credit card](../../cloud-organization/billing/add-billing-details.md). + +Currently, half the memory is assigned to the JVM heap (a bit less when monitoring is activated). For example, on a 32 GB cluster, 16 GB are allotted to heap. The disk-to-RAM ratio currently is 1:24, meaning that you get 24 GB of storage space for each 1 GB of RAM. All clusters are backed by SSD drives. + +::::{tip} +For production systems, we recommend not using less than 4 GB of RAM for your cluster, which assigns 2 GB to the JVM heap. +:::: + + +The CPU resources assigned to a cluster are relative to the size of your cluster, meaning that a 32 GB cluster gets twice as much CPU resources as a 16 GB cluster. All clusters are guaranteed their share of CPU resources, as we do not overcommit resources. Smaller clusters up to and including 8 GB of RAM benefit from temporary CPU boosting to improve performance when needed most. + +If you don’t want to autoscale your deployment, you can manually increase or decrease capacity by adjusting the size of hot, warm, cold, and frozen [data tiers](../../../manage-data/lifecycle/data-tiers.md) nodes. For example, you might want to add warm tier nodes if you have time series data that is accessed less frequently and rarely needs to be updated. Alternatively, you might need cold tier nodes if you have time series data that is accessed occasionally and not normally updated. For clusters that have six or more {{es}} nodes, dedicated master-eligible nodes are introduced. When your cluster grows, it becomes important to consider separating dedicated master-eligible nodes from dedicated data nodes. + +::::{tip} +We recommend using at least 4GB RAM for dedicated master nodes. +:::: + + + +## Fault tolerance [ec-high-availability] + +High availability is achieved by running a cluster with replicas in multiple data centers (availability zones), to prevent against downtime when infrastructure problems occur or when resizing or upgrading deployments. We offer the options of running in one, two, or three data centers. + +:::{image} ../../../images/cloud-ec-fault-tolerance.png +:alt: High availability features +::: + +Running in two data centers or availability zones is our default high availability configuration. It provides reasonably high protection against infrastructure failures and intermittent network problems. You might want three data centers if you need even higher fault tolerance. Just one zone might be sufficient, if the cluster is mainly used for testing or development. + +::::{important} +Some [regions](https://www.elastic.co/guide/en/cloud/current/ec-reference-regions.html) might have only two availability zones. +:::: + + +Like many other changes, you change the level of fault tolerance while the cluster is running. For example, when you prepare a new cluster for production use, you can first run it in a single data center and then add another data center right before deploying to production. + +While multiple data centers or availability zones increase a cluster’s fault tolerance, they do not protect against problematic searches that cause nodes to run out of memory. For a cluster to be highly reliable and available, it is also important to [have enough memory](../../../troubleshoot/monitoring/high-memory-pressure.md). + +The node capacity you choose is per data center. The reason for this is that there is no point in having two data centers if the failure of one will result in a cascading error because the remaining data center cannot handle the total load. Through the allocation awareness in {{es}}, we configure the nodes so that your {{es}} cluster will automatically allocate replicas between each availability zone. + + +## Sharding [ec_sharding] + +You can review your {{es}} shard activity from Elasticsearch Service. At the bottom of the {{es}} page, you can hover over each part of the shard visualization for specific numbers. + +:::{image} ../../../images/cloud-ec-shard-activity.gif +:alt: Shard activity +::: + +We recommend that you read [Size your shards](../../production-guidance/optimize-performance/size-shards.md) before you change the number of shards. + + +## Manage user settings and extensions [ec_manage_user_settings_and_extensions] + +Here, you can configure user settings, extensions, and system settings (older versions only). + + +### User settings [ec-user-settings] + +Set specific configuration parameters to change how {{es}} and other Elastic products run. User settings are appended to the appropriate YAML configuration file, but not all settings are supported in Elasticsearch Service. + +For more information, refer to [Edit your user settings](edit-stack-settings.md). + + +### Extensions [ec_extensions] + +Lists the official plugins available for your selected {{es}} version, as well as any custom plugins and user bundles with dictionaries or scripts. + +When selecting a plugin from this list you get a version that has been tested with the chosen {{es}} version. The main difference between selecting a plugin from this list and uploading the same plugin as a custom extension is in who decides the version used. To learn more, check [*Add plugins and extensions*](add-plugins-extensions.md). + +The reason we do not list the version chosen on this page is because we reserve the option to change it when necessary. That said, we will not force a cluster restart for a simple plugin upgrade unless there are severe issues with the current version. In most cases, plugin upgrades are applied lazily, in other words when something else forces a restart like you changing the plan or {{es}} runs out of memory. + +::::{tip} +Only Gold and Platinum subscriptions have access to uploading custom plugins. All subscription levels, including Standard, can upload scripts and dictionaries. +:::: + + + +## {{kib}} [ec_kib] + +A {{kib}} instance is created automatically as part of every deployment. + +::::{tip} +If you use a version before 5.0 or if your deployment didn’t include a {{kib}} instance initially, there might not be a {{kib}} endpoint URL shown, yet. To enable {{kib}}, select **Enable**. Enabling {{kib}} provides you with an endpoint URL, where you can access {{kib}}. It can take a short while to provision {{kib}} right after you select **Enable**, so if you get an error message when you first access the endpoint URL, try again. +:::: + + +Selecting **Open** will log you in to {{kib}} using single sign-on (SSO). For versions older than 7.9.2, you need to log in to {{kib}} with the `elastic` superuser. The password was provided when you created your deployment or [can be reset](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + +In production systems, you might need to control what {{es}} data users can access through {{kib}}. Refer to [Securing your deployment](../../users-roles/cluster-or-deployment-auth.md) to learn more. + + +## {{integrations-server}} [ec_integrations_server] + +{{integrations-server}} connects observability and security data from Elastic Agents and APM to Elasticsearch. An {{integrations-server}} instance is created automatically as part of every deployment. + +Refer to [Manage your Integrations Server](manage-integrations-server.md) to learn more. + + +## {{ents}} [ec_ents] + +{{ents}} enables you to add modern search to your application or connect and unify content across your workplace. An {{ents}} instance is created automatically as part of every deployment. + +Refer to [Enable Enterprise Search](https://www.elastic.co/guide/en/cloud/current/ec-enable-enterprise-search.html) to learn more. + + +## Security [ec_security] + +Here, you can configure features that keep your deployment secure: reset the password for the `elastic` user, set up traffic filters, and add settings to the {{es}} keystore. You can also set up remote connections to other deployments. + + +## Actions [ec_actions] + +There are a few actions you can perform from the **Actions** dropdown: + +* Edit the deployment +* Reset the `elastic` user password. +* Restart {{es}} - Needed only rarely, but full cluster restarts can help with a suspected operational issue before reaching out to Elastic for help. +* Delete your deployment - For deployment that you no longer need and don’t want to be charged for any longer. Deleting a deployment removes the {{es}} cluster and all your data permanently. + +::::{important} +Use these actions with care. Deployments are not available while they restart and deleting a deployment does really remove the {{es}} cluster and all your data permanently. +:::: + + diff --git a/deploy-manage/deploy/elastic-cloud/ec-customize-deployment.md b/deploy-manage/deploy/elastic-cloud/ec-customize-deployment.md new file mode 100644 index 000000000..09b813ff5 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ec-customize-deployment.md @@ -0,0 +1,63 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-customize-deployment.html +--- + +# Change your configuration [ec-customize-deployment] + +You might want to change the configuration of your deployment to: + +* Add features, such as machine learning or APM (application performance monitoring). +* Increase or decrease capacity by changing the amount of reserved memory and storage for different parts of your deployment. + + ::::{note} + During the free trial, Elasticsearch Service deployments are restricted to a limited size. You can increase the size of your deployments when your trial is converted to a paid subscription. + :::: + +* Enable [autoscaling](../../autoscaling.md) so that the available resources for deployment components, such as data tiers and machine learning nodes, adjust automatically as the demands on them change over time. +* Enable high availability, also known as fault tolerance, by adjusting the number of data center availability zones that parts of your deployment run on. +* Upgrade to new versions of {{es}}. You can upgrade from one major version to another, such as from 6.8.23 to 7.17.27, or from one minor version to another, such as 6.1 to 6.2. You can’t downgrade versions. +* Change what plugins are available on your {{es}} cluster. + +With the exception of major version upgrades for Elastic Stack products, Elasticsearch Service can perform configuration changes without having to interrupt your deployment. You can continue searching and indexing. The changes can also be done in bulk. For example: in one action, you can add more memory, upgrade, adjust the number of {{es}} plugins and adjust the number of availability zones. + +We perform all of these changes by creating instances with the new configurations that join your existing deployment before removing the old ones. For example: if you are changing your {{es}} cluster configuration, we create new {{es}} nodes, recover your indexes, and start routing requests to the new nodes. Only when all new {{es}} nodes are ready, do we bring down the old ones. + +By doing it this way, we reduce the risk of making configuration changes. If any of the new instances have a problems, the old ones are still there, processing requests. + +::::{note} +If you use a Platform-as-a-Service provider like Heroku, the administration console is slightly different and does not allow you to make changes that will affect the price. That must be done in the platform provider’s add-on system. You can still do things like change {{es}} version or plugins. +:::: + + +To change your deployment: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From the deployment menu, select **Edit**. +4. Let the user interface guide you through the cluster configuration for your cluster. For a full list of the supported settings, check [What Deployment Settings Are Available?](ec-configure-deployment-settings.md) + + If you are changing an existing deployment, you can make multiple changes to your {{es}} cluster with a single configuration update, such as changing the capacity and upgrading to a new {{es}} version in one step. + +5. Save your changes. The new configuration takes a few moments to create. + +Review the changes to your configuration on the **Activity** page, with a tab for {{es}} and one for {{kib}}. + +::::{tip} +If you are creating a new deployment, select **Edit settings** to change the cloud provider, region, hardware profile, and stack version; or select **Advanced settings** for more complex configuration settings. +:::: + + +That’s it! If you haven’t already, [start exploring with {{kib}}](access-kibana.md), our visualization tool. If you’re not familiar with adding data yet, {{kib}} can show you how to index your data into {{es}}, or try our basic steps for working with [{{es}}](../../../manage-data/data-store/manage-data-from-the-command-line.md). + +::::{tip} +Some features are not available during the 14-day free trial. If a feature is greyed out, [add a credit card](../../cloud-organization/billing/add-billing-details.md) to unlock the feature. +:::: + + + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-about.md b/deploy-manage/deploy/elastic-cloud/ech-about.md new file mode 100644 index 000000000..0037572ed --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-about.md @@ -0,0 +1,17 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-about.html +--- + +# About [ech-about] + +The information in this section covers: + +* [Subscription Levels](ech-licensing.md) +* [Version Policy](ech-version-policy.md) +* [Elasticsearch Add-On for Heroku Hardware](ech-reference-hardware.md) +* [Elasticsearch Add-On for Heroku Regions](ech-reference-regions.md) +* [Service Status](ech-service-status.md) +* [Getting help](ech-get-help.md) +* [Restrictions and known problems](ech-restrictions.md) + diff --git a/deploy-manage/deploy/elastic-cloud/ech-access-kibana.md b/deploy-manage/deploy/elastic-cloud/ech-access-kibana.md new file mode 100644 index 000000000..76f4415f0 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-access-kibana.md @@ -0,0 +1,38 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-access-kibana.html +--- + +# Access Kibana [ech-access-kibana] + +Kibana is an open source analytics and visualization platform designed to search, view, and interact with data stored in Elasticsearch indices. The use of Kibana is included with your subscription. + +For new Elasticsearch clusters, we automatically create a Kibana instance for you. + +To access Kibana: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the **Deployments** page, select your deployment. + + Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. Under **Applications**, select the Kibana **Launch** link and wait for Kibana to open. + + ::::{note} + Both ports 443 and 9243 can be used to access Kibana. SSO only works with 9243 on older deployments, where you will see an option in the Cloud UI to migrate the default to port 443. In addition, any version upgrade will automatically migrate the default port to 443. + :::: + +4. Log into Kibana. Single sign-on (SSO) is enabled between your Cloud account and the Kibana instance. If you’re logged in already, then Kibana opens without requiring you to log in again. However, if your token has expired, choose from one of these methods to log in: + + * Select **Login with Cloud**. You’ll need to log in with your Cloud account credentials and then you’ll be redirected to Kibana. + * Log in with the `elastic` superuser. The password was provided when you created your cluster or [can be reset](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + * Log in with any users you created in Kibana already. + + +In production systems, you might need to control what Elasticsearch data users can access through Kibana, so you need create credentials that can be used to access the necessary Elasticsearch resources. This means granting read access to the necessary indexes, as well as access to update the `.kibana` index. + +::::{tip} +If your cluster didn’t include a Kibana instance initially, there might not be a Kibana endpoint URL shown, yet. To gain access, all you need to do is [enable Kibana first](access-kibana.md). +:::: + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-api-console.md b/deploy-manage/deploy/elastic-cloud/ech-api-console.md new file mode 100644 index 000000000..55cffbc51 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-api-console.md @@ -0,0 +1,38 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-api-console.html +--- + +# Access the Elasticsearch API console [ech-api-console] + +Interact with a specific Elasticsearch cluster directly from the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) without having to authenticate again. This RESTful API access is limited to the specific cluster and works only for Elasticsearch API calls. + +::::{note} +API console is intended for admin purposes. Avoid running normal workload like indexing or search request. +:::: + + +You are unable to make Elasticsearch Add-On for Heroku platform changes from the Elasticsearch API. + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the deployments page, select your deployment. + + Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From the Elasticsearch menu, go to the **API Console** page. +4. Make a selection from the operation drop-down list and complete the path. + + For example, select `GET`, then use the `_cluster/health?pretty=true` path for cluster status and other pertinent details. + +5. If needed, add the body information. + + ::::{tip} + To display the body area, select PUT, POST, or DELETE from the drop-down list. + :::: + +6. Select **Submit**. + +The results of the API operation are displayed, along with the time it took to complete the operation. + +To learn more about what kinds of Elasticsearch API calls you can make from the Cloud UI, check the [Elasticsearch Reference](https://www.elastic.co/guide/en/elasticsearch/reference/current). + diff --git a/deploy-manage/deploy/elastic-cloud/ech-aws-instance-configuration.md b/deploy-manage/deploy/elastic-cloud/ech-aws-instance-configuration.md new file mode 100644 index 000000000..558752080 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-aws-instance-configuration.md @@ -0,0 +1,85 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-aws-instance-configuration.html +--- + +# Elasticsearch Add-On for Heroku AWS instance configurations [ech-aws-instance-configuration] + +Amazon EC2 (AWS) C6gd, M6gd & R6gd instances, powered by AWS Graviton2, are now available for Elastic Cloud deployments. C6gd, M6gd & R6gd VMs use the [Graviton2, ARM neoverse N1 cores](https://aws.amazon.com/about-aws/whats-new/2020/07/announcing-new-amazon-ec2-instances-powered-aws-graviton2-processors/) and provide high compute coupled with fast NVMe storage, which makes them a good fit to power Elastic workloads. In addition, Graviton2 VMs also offer more than a 20% improvement in price-performance over comparable Intel chipsets. + +In addition to AWS Graviton2 instances, Amazon EC2 (AWS) C5d, M5d, I3, I3en, and D2/D3 instances are now available for Elastic Cloud deployments in all supported [AWS Cloud Regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html#ec-aws_regions). + +For specific AWS hardware and availability details, check the [Regional availability of instances per AWS region](ech-default-aws-configurations.md#aws-list-region) and the [AWS default provider instance configurations](ech-default-aws-configurations.md). + +## VM configurations [echvm_configurations] + +For the AWS infrastructure upgrade, we use the default instance type configurations provided by AWS which are unique to them. + +To make it easy to identify each instance type in AWS, a new common nomenclature is introduced. + +For example, Instance ID / SKU: `aws.es.datahot.i3` + +| | | +| --- | --- | +| `aws.*` | Denotes the cloud provider, AWS in this case with Azure in future cases. | +| `\*.es.datahot.*` | Denotes that this configuration is an Elasticsearch (`es`) cluster component that serves as a data node for hot content. Other options may be `datawarm`, `datacold`, `datafrozen` for data nodes, and `kibana`, `master`, and so on for other components. | +| `*.i3` | Denotes that this configuration is running on the AWS i3 instance family. | + +The new configuration naming convention aligns with the [data tiers](https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tiers.html) intended for each configuration type, replacing prior naming conventions of “highio”, “highcpu”, and so on. The following table details the new configurations for data nodes and compares them with prior naming conventions where applicable. + +| New config name | Notes | +| --- | --- | +| aws.es.datahot.i3 | This configuration maintains the same type of VM configuration as used in the previous config (“aws.data.highio.i3”) but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.datahot.i3en | This is a new configuration that is similar to the “aws.data.datahot.i3” config, but with more disk space to allow for longer retention in ingest use cases, or larger catalog in search use cases. | +| aws.es.datahot.m5d | This configuration maintains the same type of VM configuration as used in the previous config (“aws.data.highcpu.m5d”) but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.datahot.m6gd | This is a new configuration that is similar to the “aws.es.datahot.m5d” config but with more disk space and similar RAM:CPU ratios. It is powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.es.datahot.c5d | This is a new configuration that provides double the CPU capacity compared to “aws.es.datahot.m5d” config. It is intended for high throughput ingest use cases or intensive search use cases. | +| aws.es.datahot.c6gd | This is a new configuration that is similar to the “aws.es.datahot.c5d” config but with more disk space and similar RAM:CPU ratios. It is powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.es.datahot.r6gd | This is a new configuration powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.es.datawarm.d2, aws.es.datacold.d2 | These configurations maintain the same type of VM configuration as used in the previous config (“aws.data.highstorage.d2”) but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.datawarm.d3, aws.es.datacold.d3 | These configurations maintain the same type of VM configuration as used in the previous config (“aws.data.highstorage.d3”) but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.datawarm.i3en, aws.es.datacold.i3en | These configurations maintain the same type of VM configuration as used in the previous config (“aws.data.highstorage.i3en”) but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.datafrozen.i3en | This configuration maintains the same type of VM configuration as defined for (“aws.es.datacold.i3en”) config. | + +For a detailed price list, check the [Elastic Cloud price list](https://cloud.elastic.co/deployment-pricing-table?provider=aws). For a detailed specification of the new configurations, check [Elasticsearch Service default provider instance configurations](ech-default-aws-configurations.md). + +The benefits of the new configurations are multifold: + +* By providing a net new configuration of C5d instances, there is a general boost of performance related to new chipsets and faster hardware. On average the boost we witnessed in select benchmarks can reach up to 15%, however, different workloads may exhibit different improvements. +* Introducing C6gd, M6gd & R6gd instances, powered by AWS Graviton 2, provides high compute coupled with fast NVMe storage and offer more than a 20% improvement in price-performance over comparable Intel chipsets. +* The existing family types have been extended in terms of disk capacity which translates to a more cost effective infrastructure which in some cases can save up to 80% when calculating cost by disk capacity. +* There are now more instance types to choose from in the hot tier. Rather than the traditional “highio” and “highcpu”, there are now six options to cover the hot data tier which allows to optimize cost/performance further. + +In addition to data nodes for storage and search, Elasticsearch nodes also have machine learning nodes, master nodes, and coordinating nodes. These auxiliary node types along with application nodes such as APM servers, Kibana, and Enterprise search have also been upgraded to the new C5d, C6gd, M5d, and M6gd instance types. Both auxiliary node and application node configurations are based on Elasticsearch data node configuration types shown in the previous table. + +| New config name | Notes | +| --- | --- | +| aws.es.master.c5d | Master nodes have been “upgraded” to use 4x the CPU with more memory and disk space as they had when based on “aws.master.r5d” config. This will help boost the overall performance and stability of clusters, as master nodes have a critical role in maintaining cluster state and controlling workloads. | +| aws.es.master.c6gd | This is a new configuration that is similar to the “aws.es.master.c5d” config but with more disk space and similar RAM:CPU ratios. It is powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.es.ml.m5d | ML nodes will maintain the same type of VM configuration as used in the previous config (“aws.ml.m5d”), but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.ml.m6gd | This is a new configuration that is similar to the “aws.es.ml.m5d” config but with more disk space and similar RAM:CPU ratios. It is powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.es.ml.c5d | This is a new configuration that is similar to the “aws.es.ml.m5d” config but with 2x more CPU per unit of RAM and more disk space. | +| aws.es.coordinating.m5d | Coordinating nodes will maintain the same type of VM configuration as used in the previous config (“aws.coordinating.m5d”), but will have a new name (and billing SKU) that is consistent with the new naming. | +| aws.es.coordinating.m6gd | This is a new configuration that is similar to the “aws.es.coordinating.m5d” config but with more disk space and similar RAM:CPU ratios. It is powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.kibana.c5d | Same “upgrade” for Kibana as that of master nodes. Will now use 4x the CPU with more memory and disk space. This ensures a more performant Kibana and helps with some client side aggregation, as well as responsive UI. | +| aws.kibana.c6gd | This is a new configuration that is similar to the “aws.kibana.c5d” config but with more disk space and similar RAM:CPU ratios. It is powered by AWS Graviton2 which offers a better price-performance over comparable Intel chipsets. | +| aws.apm.c5d | Same “upgrade” for APM as that of Kibana. Will now use 4x the CPU with more memory and disk space. | +| aws.integrationsserver.c5d | Same “upgrade” for Integrations Server as that of Kibana. Will now use 4x the CPU with more memory and disk space. | +| aws.enterprisesearch.c5d | Enterprisesearch nodes have been “upgraded” to use 2x the CPU with more memory and disk space as they had when based on “aws.enterprisesearch.m5d” config. | + + +## Selecting the right configuration for you [echselecting_the_right_configuration_for_you] + +While far from being a comprehensive guide for performance tuning, the following advice is provided for selecting the hot tier instance configuration: + +| Deployment template | Hot data tier instance configuration | Notes | +| --- | --- | --- | +| Storage Optimized | aws.es.datahot.i3 | Good for most ingestion use cases with 7-10 days of data available for fast access. Also good for light search use cases without heavy indexing or CPU needs. | +| Storage Optimized (Dense) | aws.es.datahot.i3en | Ideal for ingestion use cases with more than 10 days of data available for fast access. Also, good for light search use cases with very large data sets. | +| CPU Optimized | aws.es.datahot.c5d | Suitable for ingestion use cases with 1-4 days of data available for fast access and for search use cases with indexing and querying workloads. Provides the most CPU resources per unit of RAM. | +| CPU Optimized (ARM) | aws.es.datahot.c6gd | Suitable for ingestion use cases with 1-4 days of data available for fast access and for search use cases with indexing and querying workloads. Provides the most CPU resources per unit of RAM. | +| Vector Search Optimized (ARM) | aws.es.datahot.r6gd | Optimized for applications that leverage Vector Search and/or Generative AI. Also the optimal choice for utilizing ELSER for semantic search applications. Broadly suitable for all semantic search, text embedding, image search, and other Vector Search use cases. | +| General Purpose | aws.es.datahot.m5d | Suitable for ingestion use cases with 5-7 days of data available for fast access. Also good for search workloads with less-frequent indexing and medium to high querying loads. Provides a balance of storage, memory, and CPU. | +| General Purpose (ARM) | aws.es.datahot.m6gd | Suitable for ingestion use cases with 5-7 days of data available for fast access. Also good for search workloads with less-frequent indexing and medium to high querying loads. Provides a balance of storage, memory, and CPU. | + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-azure-instance-configuration.md b/deploy-manage/deploy/elastic-cloud/ech-azure-instance-configuration.md new file mode 100644 index 000000000..01602c7b2 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-azure-instance-configuration.md @@ -0,0 +1,72 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-azure-instance-configuration.html +--- + +# Elasticsearch Add-On for Heroku Azure instance configurations [ech-azure-instance-configuration] + +Azure [Ddv4](https://docs.microsoft.com/en-us/azure/virtual-machines/ddv4-ddsv4-series/), [Edsv4](https://docs.microsoft.com/en-us/azure/virtual-machines/edv4-edsv4-series/), [Fsv2](https://docs.microsoft.com/en-us/azure/virtual-machines/fsv2-series/), and [Lsv3](https://docs.microsoft.com/en-us/azure/virtual-machines/lsv3-series/) virtual machines (VM) are now available for Elastic Cloud deployments in all supported [Azure Cloud regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html#ec-azure_regions). These VMs provide additional combinations of compute, memory, and disk configurations to better fit your use-cases to optimize performance and cost. + +To learn about the Azure specific configurations, check: + +* [VM configurations](#ech-azure-vm-configurations) +* [Selecting the right configuration for you](#ech-azure-configuration-choose) +* [Azure default provider instance configurations](ech-default-azure-configurations.md) +* [Regional availability of instances per Azure region](ech-default-azure-configurations.md#ech-azure-list-region) + +## VM configurations [ech-azure-vm-configurations] + +For Azure, we use the default instance type configurations provided by Azure which are unique to them. To make it easy to identify each instance type in Azure, a new common nomenclature is introduced. + +For example, Instance ID / SKU: `azure.es.datahot.ddv4` + +| | | +| --- | --- | +| `azure.*` | Denotes the cloud provider, Azure in this case. | +| `\*.es.datahot.*` | Denotes that this configuration is an Elasticsearch (`es`) cluster component that serves as a data node for hot content. Other options may be `datawarm`, `datacold`, `datafrozen` for data nodes, and `kibana`, `master`, and so on for other components. | +| `*.ddv4` | Denotes that this configuration is running on the Azure Ddv4 VM series. | + +The new configuration naming convention aligns with the [data tiers](https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tiers.html) intended for each configuration type, replacing prior naming conventions of “highio”, “highcpu”, and so on. The following table details the new configurations for data nodes and compares them with prior naming conventions where applicable. + +| New config name | Notes | +| --- | --- | +| azure.es.datahot.edsv4 | This is a new configuration that replaces “azure.data.highio.l32sv2” or “azure.data.highio.e32sv3” config, but provides more disk space and similar RAM:CPU ratios. | +| azure.es.datahot.ddv4 | This is a new configuration that replaces “azure.data.highcpu.d64sv3” config, but provides more disk space to allow for longer retention in ingest use cases, or larger catalog in search use cases. | +| azure.es.datahot.fsv2 | This is a new configuration that provides double the CPU compared to “azure.es.datahot.ddv4” config. It is intended for high throughput ingest use cases or intensive search use cases. | +| azure.es.datahot.lsv3 | This is a new configuration powered by Intel Ice lake processor which provides similar RAM:CPU ratios as that of edsv4 but provides lower disk space. | +| azure.es.datawarm.edsv4, azure.es.datacold.edsv4 | This is a new configuration that replaces “azure.data.highstorage.e16sv3” config but provides more disk space. | +| azure.es.datafrozen.edsv4 | This is a new configuration that replaces “azure.es.datafrozen.lsv2” or “azure.es.datafrozen.esv3” config but provides more disk space. | + +For a detailed price list, check the [Elastic Cloud price list](https://cloud.elastic.co/deployment-pricing-table?provider=azure). For a detailed specification of the new configurations, check [Elasticsearch Service default Azure instance configurations](ech-default-azure-configurations.md). + +The benefits of the new configurations are multifold: + +* By providing a net new configuration of fsv2 VM series, there is a general boost of performance related to new chipsets and faster hardware. +* The new instances provide more disk capacity as compared to existing VM series which translates to a more cost effective infrastructure which can save up to 80% when calculating cost by disk capacity. +* There are now more instances to choose from in the hot tier. Rather than the traditional “highio” and “highcpu”, there are now three options to cover the hot data tier which allows to optimize cost/performance further. + +In addition to data nodes for storage and search, Elasticsearch nodes also have machine learning nodes, master nodes, and coordinating nodes. These auxiliary node types along with application nodes such as APM servers, Kibana, and Enterprise search have also been upgraded to the new Fsv2 VM series. Both auxiliary node and application node configurations are based on Elasticsearch data node configuration types shown in the previous table. + +| New config name | Notes | +| --- | --- | +| azure.es.master.fsv2 | Master nodes now use 4x the CPU as they had when based on “azure.master.e32sv3” config. This will help boost the overall performance and stability of clusters, as master nodes have a critical role in maintaining cluster state and controlling workloads. | +| azure.es.ml.fsv2 | ML nodes now use 2x the CPU as they had when based on “azure.ml.d64sv3” config. | +| azure.es.coordinating.fsv2 | Coordinating nodes now use 2x the CPU as they had when based on “azure.coordinating.d64sv3” config. | +| azure.kibana.fsv2 | Kibana nodes now use 4x the CPU as they had when based on “azure.kibana.e32sv3” config. This ensures a more performant Kibana and helps with some client side aggregation, as well as responsive UI. | +| azure.apm.fsv2 | APM nodes now use 4x the CPU as they had when based on “azure.apm.e32sv3” config. | +| azure.integrationsserver.fsv2 | Integrations Server nodes now use 4x the CPU as they had when based on “azure.integrationsserver.e32sv3” config. | +| azure.enterprisesearch.fsv2 | Enterprisesearch Server nodes now use 2x the CPU as they had when based on “azure.enterprisesearch.d64sv3” config. | + + +## Selecting the right configuration for you [ech-azure-configuration-choose] + +While far from being a comprehensive guide for performance tuning, the following advice is provided for selecting the hot tier instance configuration: + +| Deployment template | Hot data tier instance configuration | Notes | +| --- | --- | --- | +| Storage Optimized | azure.es.datahot.edsv4 | Good for most ingestion use cases with 7-10 days of data available for fast access. Also good for light search use cases without heavy indexing or CPU needs. | +| CPU Optimized | azure.es.datahot.fsv2 | Suitable for ingestion use cases with 1-4 days of data available for fast access and for search use cases with indexing and querying workloads. Provides the most CPU resources per unit of RAM. | +| Vector Search Optimized | azure.es.datahot.lsv3 | Optimized for applications that leverage Vector Search and/or Generative AI. Also the optimal choice for utilizing ELSER for semantic search applications. Broadly suitable for all semantic search, text embedding, image search, and other Vector Search use cases. | +| General Purpose | azure.es.datahot.ddv4 | Suitable for ingestion use cases with 5-7 days of data available for fast access. Also good for search workloads with less-frequent indexing and medium to high querying loads. Provides a balance of storage, memory, and CPU. | + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-configure-deployment-settings.md b/deploy-manage/deploy/elastic-cloud/ech-configure-deployment-settings.md new file mode 100644 index 000000000..7ea48596a --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-configure-deployment-settings.md @@ -0,0 +1,45 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-configure-deployment-settings.html +--- + +# What deployment settings are available? [ech-configure-deployment-settings] + +The following deployment settings are available: + + +## Cloud provider [echcloud_provider] + +Selects a cloud platform where your {{es}} clusters, {{kib}} instance, and other {{stack}} components will be hosted. Elasticsearch Add-On for Heroku currently supports Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. + + +## Region [echregion] + +Regions represent data centers in a geographic location, where your deployment will be located. When choosing a region, the general rule is to choose one as close to your application servers as possible in order to minimize network delays. + +::::{tip} +You can select your cloud platform and region only when you create a new deployment, so pick ones that works for you. They cannot be changed later. Different deployments can use different platforms and regions. +:::: + + + +## Version [echversion] + +Elastic Stack uses a versions code that is constructed of three numbers separated by dots: the leftmost number is the number of the major release, the middle number is the number of the minor release and the rightmost number is the number of the maintenance release (e.g., 8.3.2 means major release 8, minor release 3 and maintenance release 2). + +You might sometimes notice additional versions listed in the user interface beyond the versions we currently support and maintain, such as [release candidate builds](ech-version-policy.md#ech-release-builds) and older versions. If a version is listed in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body), it can be deployed. + +To learn about how we support {{es}} versions in Elasticsearch Add-On for Heroku, check [Version Policy](ech-version-policy.md). + +You can always upgrade {{es}} versions, but you cannot downgrade. To learn more about upgrading versions of {{es}} and best practices for major version upgrades, check [Version Upgrades](../../upgrade/deployment-or-cluster.md). + + +## Snapshot source [echsnapshot_source] + +To create a deployment from a snapshot, select the snapshot source. You need to [configure snapshots](../../tools/snapshot-and-restore.md) and establish a snapshot lifecycle management policy and repository before you can restore from a snapshot. The snapshot options depend on the stack version the deployment is running. + + +## Name [echname] + +This setting allows you to assign a more human-friendly name to your cluster which will be used for future reference in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). Common choices are dev, prod, test, or something more domain specific. + diff --git a/deploy-manage/deploy/elastic-cloud/ech-configure-settings.md b/deploy-manage/deploy/elastic-cloud/ech-configure-settings.md new file mode 100644 index 000000000..6f932bfe3 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-configure-settings.md @@ -0,0 +1,52 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-configure-settings.html +--- + +# Configure your deployment [ech-configure-settings] + +You might want to change the configuration of your deployment to: + +* Add features, such as machine learning or APM (application performance monitoring). +* Increase or decrease capacity by changing the amount of reserved memory and storage for different parts of your deployment. +* Enable [autoscaling](../../autoscaling.md) so that the available resources for deployment components, such as data tiers and machine learning nodes, adjust automatically as the demands on them change over time. +* Enable high availability by adjusting the number of availability zones that parts of your deployment run on. +* Upgrade to new versions of {{es}}. You can upgrade from one major version to another, such as from 7.17.27 to 8.17.1, or from one minor version to another, such as 8.6 to 8.7. You can’t downgrade versions. +* Change what plugins are available on your {{es}} cluster. + +::::{note} +During the free trial, {{ess}} deployments are restricted to a fixed size. You can resize your deployments when your trial is converted into a paid subscription. +:::: + + +You can change the configuration of a running deployment from the **Configuration** pane in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). + +With the exception of major version upgrades for Elastic Stack products, Elasticsearch Add-On for Heroku can perform configuration changes without having to interrupt your deployment. You can continue searching and indexing. The changes can also be done in bulk. For example: in one action you can add more memory, upgrade, adjust the number of {{es}} plugins and adjust the number of availability zones. + +We perform all of these changes by creating instances with the new configurations that join your existing deployment before removing the old ones. For example: if you are changing your {{es}} cluster configuration, we create new {{es}} nodes, recover your indexes, and start routing requests to the new nodes. Only when all new {{es}} nodes are ready, do we bring down the old ones. + +By doing it this way, we reduce the risk of making configuration changes. If any of the new instances have a problems, the old ones are still there, processing requests. + +::::{note} +If you use a Platform-as-a-Service provider like Heroku, the administration console is slightly different and does not allow you to make changes that will affect the price. That must be done in the platform provider’s add-on system. You can still do things like change {{es}} version or plugins. +:::: + + +To change the {{es}} cluster in your deployment: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the deployments page, select your deployment. + + Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From your deployment menu, select **{{es}}** and then **Edit**. +4. Let the user interface guide you through the cluster configuration for your cluster. For a full list of the supported settings, check [What Deployment Settings Are Available?](ech-configure-deployment-settings.md) + + If you are changing an existing deployment, you can make multiple changes to your {{es}} cluster with a single configuration update, such as changing the capacity and upgrading to a new {{es}} version in one step. + +5. Save your changes. The new configuration takes a few moments to create. + +Review the changes to your configuration on the **Activity** page, with a tab for {{es}} and one for {{kib}}. + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-customize-deployment-components.md b/deploy-manage/deploy/elastic-cloud/ech-customize-deployment-components.md new file mode 100644 index 000000000..ddb9f7663 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-customize-deployment-components.md @@ -0,0 +1,140 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-customize-deployment-components.html +--- + +# How can I customize the components of my deployment? [ech-customize-deployment-components] + +When you create or edit an existing deployment, you can fine-tune the capacity, add extensions, and select additional features. + + +### Autoscaling [ech-customize-autoscaling] + +Autoscaling reduces some of the manual effort required to manage a deployment by adjusting the capacity as demands on the deployment change. Currently, autoscaling is supported to scale {{es}} data tiers upwards, and to scale machine learning nodes both upwards and downwards. Check [Deployment autoscaling](../../autoscaling.md) to learn more. + + +### {{es}} [ech-cluster-size] + +Depending upon how much data you have and what queries you plan to run, you need to select a cluster size that fits your needs. There is no silver bullet for deciding how much memory you need other than simply testing it. The [cluster performance metrics](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) can tell you if your cluster is sized appropriately. You can also [enable deployment monitoring](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) for more detailed performance metrics. Fortunately, you can change the amount of memory allocated to the cluster later without any downtime for HA deployments. + +To change a cluster’s topology, from deployment management, select **Edit deployment** from the **Actions** dropdown. Next, select a storage and RAM setting from the **Size per zone** drop-down list, and save your changes. When downsizing the cluster, make sure to have enough resources to handle the current load, otherwise your cluster will be under stress. + +:::{image} ../../../images/cloud-heroku-ec-capacity.png +:alt: Capacity slider to adjust {{es}} cluster size +::: + +Currently, half the memory is assigned to the JVM heap (a bit less when monitoring is activated). For example, on a 32 GB cluster, 16 GB are allotted to heap. The disk-to-RAM ratio currently is 1:24, meaning that you get 24 GB of storage space for each 1 GB of RAM. All clusters are backed by SSD drives. + +::::{tip} +For production systems, we recommend not using less than 4 GB of RAM for your cluster, which assigns 2 GB to the JVM heap. +:::: + + +The CPU resources assigned to a cluster are relative to the size of your cluster, meaning that a 32 GB cluster gets twice as much CPU resources as a 16 GB cluster. All clusters are guaranteed their share of CPU resources, as we do not overcommit resources. Smaller clusters up to and including 8 GB of RAM benefit from temporary CPU boosting to improve performance when needed most. + + +### Fault tolerance [ech-high-availability] + +High availability is achieved by running a cluster with replicas in multiple data centers (availability zones), to prevent against downtime when infrastructure problems occur or when resizing or upgrading deployments. We offer the options of running in one, two, or three data centers. + +:::{image} ../../../images/cloud-heroku-ec-fault-tolerance.png +:alt: High availability features +::: + +Running in two data centers or availability zones is our default high availability configuration. It provides reasonably high protection against infrastructure failures and intermittent network problems. You might want three data centers if you need even higher fault tolerance. Just one zone might be sufficient, if the cluster is mainly used for testing or development. + +::::{important} +Some [regions](ech-reference-regions.md) might have only two availability zones. +:::: + + +Like many other changes, you change the level of fault tolerance while the cluster is running. For example, when you prepare a new cluster for production use, you can first run it in a single data center and then add another data center right before deploying to production. + +While multiple data centers or availability zones increase a cluster’s fault tolerance, they do not protect against problematic searches that cause nodes to run out of memory. For a cluster to be highly reliable and available, it is also important to [have enough memory](../../../troubleshoot/monitoring/high-memory-pressure.md). + +The node capacity you choose is per data center. The reason for this is that there is no point in having two data centers if the failure of one will result in a cascading error because the remaining data center cannot handle the total load. Through the allocation awareness in {{es}}, we configure the nodes so that your {{es}} cluster will automatically allocate replicas between each availability zone. + + +### Sharding [echsharding] + +You can get an at-a-glance status of all the shards in the deployment on the **{{es}}** page. + +:::{image} ../../../images/cloud-heroku-ec-shard-activity.gif +:alt: Shard activity +::: + +We recommend that you read [Size your shards](../../production-guidance/optimize-performance/size-shards.md) before you change the number of shards. + +## Manage user settings and extensions [echmanage_user_settings_and_extensions] + +Here, you can configure user settings, extensions, and system settings (older versions only). + +### User settings [ech-user-settings] + +Set specific configuration parameters to change how {{es}} and other Elastic products run. User settings are appended to the appropriate YAML configuration file, but not all settings are supported in Elasticsearch Add-On for Heroku. + +For more information, refer to [Edit your user settings](edit-stack-settings.md). + + +#### Extensions [echextensions] + +Lists the official plugins available for your selected {{es}} version, as well as any custom plugins and user bundles with dictionaries or scripts. + +The reason we do not list the version chosen on this page is because we reserve the option to change it when necessary. That said, we will not force a cluster restart for a simple plugin upgrade unless there are severe issues with the current version. In most cases, plugin upgrades are applied lazily, in other words when something else forces a restart like you changing the plan or {{es}} runs out of memory. + +::::{tip} +Only Gold and Platinum subscriptions have access to uploading custom plugins. All subscription levels, including Standard, can upload scripts and dictionaries. +:::: + + + +### {{kib}} [echkib] + +A {{kib}} instance is created automatically as part of every deployment. + +::::{tip} +If you use a version before 5.0 or if your deployment didn’t include a {{kib}} instance initially, there might not be a {{kib}} endpoint URL shown, yet. To enable {{kib}}, select **Enable**. Enabling {{kib}} provides you with an endpoint URL, where you can access {{kib}}. It can take a short while to provision {{kib}} right after you select **Enable**, so if you get an error message when you first access the endpoint URL, try again. +:::: + + +Selecting **Open** will log you in to {{kib}} using single sign-on (SSO). For versions older than 7.9.2, you need to log in to {{kib}} with the `elastic` superuser. The password was provided when you created your deployment or [can be reset](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + +In production systems, you might need to control what {{es}} data users can access through {{kib}}. Refer to [Securing your deployment](../../security.md) to learn more. + + +### {{integrations-server}} [echintegrations_server] + +{{integrations-server}} connects observability and security data from Elastic Agents and APM to Elasticsearch. An {{integrations-server}} instance is created automatically as part of every deployment. + + +### {{ents}} [echents] + +{{ents}} enables you to add modern search to your application or connect and unify content across your workplace. An {{ents}} instance is created automatically as part of every deployment. + + +### Security [echsecurity] + +Here, you can configure features that keep your deployment secure: reset the password for the `elastic` user, set up traffic filters, and add settings to the {{es}} keystore. You can also set up remote connections to other deployments. + + +### Maintenance mode [ech-maintenance-mode] + +In maintenance mode, requests to your cluster are blocked during configuration changes. You use maintenance mode to perform corrective actions that might otherwise be difficult to complete. Maintenance mode lasts for the duration of a configuration change and is turned off after the change completes. + +We strongly recommend that you use maintenance mode when your cluster is overwhelmed by requests and you need to increase capacity. If your cluster is being overwhelmed because it is undersized for its workload, nodes might not respond to efforts to resize. Putting the cluster into maintenance mode as part of the configuration change can stop the cluster from becoming completely unresponsive during the configuration change, so that you can resolve the capacity issue. Without this option, configuration changes for clusters that are overwhelmed can take longer and are more likely to fail. + + +### Actions [echactions] + +There are a few actions you can perform from the **Actions** dropdown: + +* Restart {{es}} - Needed only rarely, but full cluster restarts can help with a suspected operational issue before reaching out to Elastic for help. +* Delete your deployment - For deployment that you no longer need and don’t want to be charged for any longer. Deleting a deployment removes the {{es}} cluster and all your data permanently. + +::::{important} +Use these actions with care. Deployments are not available while they restart and deleting a deployment does really remove the {{es}} cluster and all your data permanently. +:::: + + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-default-aws-configurations.md b/deploy-manage/deploy/elastic-cloud/ech-default-aws-configurations.md new file mode 100644 index 000000000..ade66cfc9 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-default-aws-configurations.md @@ -0,0 +1,81 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-default-aws-configurations.html +--- + +# Elasticsearch Add-On for Heroku AWS default provider instance configurations [ech-default-aws-configurations] + +Following are the preferred instance types / machine configurations, storage types, disk to memory ratios, and virtual CPU to RAM ratios for all instance configurations available on {{ess}} and provided by AWS. + +| Instance configuration | Preferred Instance Type or Machine Configuration1 | Storage Type1 | Disk:Memory Ratio2 | vCPU/RAM Ratio | +| --- | --- | --- | --- | --- | +| aws.es.datahot.i3 | i3 | NVMe | 30:1 | 0.138 | +| aws.es.datahot.i3en | i3en | NVMe | 80:1 | 0.133 | +| aws.es.datahot.m5d | m5d | NVMe | 10:1 | 0.267 | +| aws.es.datahot.m6gd | m6gd | NVMe | 15:1 | 0.267 | +| aws.es.datahot.c5d | c5d | NVMe | 12:1 | 0.529 | +| aws.es.datahot.c6gd | c6gd | NVMe | 30:1 | 0.533 | +| aws.es.datahot.r6gd | r6gd | NVMe | 6:1 | 0.133 | +| aws.es.datawarm.d2 | d2 | HDD | 160:1 | 0.138 | +| aws.es.datawarm.d3 | d3 | HDD | 190:1 | 0.133 | +| aws.es.datawarm.i3en | i3en | NVMe | 80:1 | 0.133 | +| aws.es.datacold.d2 | d2 | HDD | 160:1 | 0.138 | +| aws.es.datacold.d3 | d3 | HDD | 190:1 | 0.133 | +| aws.es.datacold.i3en | i3en | NVMe | 80:1 | 0.133 | +| aws.es.datafrozen.i3en | i3en | NVMe | 75:1 | 0.133 | + + +## Additional instances [ech-aws-additional-instances] + +Following are the preferred instance type / configuration and virtual CPU to RAM ratios for additional instance configurations available on {{ess}} and provided by AWS. + +| Instance configuration | Preferred Instance Type or Machine Configuration1 | vCPU/RAM Ratio | +| --- | --- | --- | +| aws.es.master.c5d | c5d | 0.529 | +| aws.es.master.c6gd | c6gd | 0.533 | +| aws.es.ml.c5d | c5d | 0.529 | +| aws.es.ml.m5d | m5d | 0.267 | +| aws.es.ml.m6gd | m6gd | 0.267 | +| aws.es.coordinating.m5d | m5d | 0.267 | +| aws.es.coordinating.m6gd | m6gd | 0.267 | +| aws.kibana.c5d | c5d | 0.529 | +| aws.kibana.c6gd | c6gd | 0.533 | +| aws.apm.c5d | c5d | 0.529 | +| aws.integrationsserver.c5d | c5d | 0.529 | +| aws.enterprisesearch.c5d | c5d | 0.529 | + +1 Preferred instance and storage types are subject to provider availability. To learn more about our provider instances, check the [AWS](https://aws.amazon.com/ec2/instance-types) reference page. + +2 Ratios are estimations. + +## Regional availability of instances per AWS region [aws-list-region] + +The following table contains the complete list of instances available in Elastic Cloud deployments per AWS region: + +| Regions | Instances | | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | C5d | C6gd | C5n | M5dn | D2 | D3 | I3 | I3en | M5d | M6gd | R6gd | +| Africa (Cape Town) | ✓ | | | | ✓ | | ✓ | ✓ | ✓ | | | +| Asia Pacific (Hong Kong) | ✓ | | | | ✓ | | ✓ | ✓ | ✓ | | | +| Asia Pacific (Mumbai) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Asia Pacific (Singapore) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Asia Pacific (Seoul) | ✓ | | | | ✓ | | ✓ | ✓ | ✓ | | | +| Asia Pacific (Sydney) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Asia Pacific (Tokyo) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Canada (Central) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | | ✓ | +| Europe (Frankfurt) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Europe (Zurich) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | | +| Europe (Ireland) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Europe (London) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | | +| Europe (Milan) | ✓ | | | | ✓ | | ✓ | ✓ | ✓ | | | +| Europe (Paris) | ✓ | ✓ | | | ✓ | | ✓ | ✓ | ✓ | | ✓ | +| Europe (Stockholm) | ✓ | ✓ | | | ✓ | | ✓ | ✓ | ✓ | ✓ | | +| Middle East (Bahrain) | ✓ | | | | ✓ | | ✓ | ✓ | ✓ | | | +| South America (São Paulo) | ✓ | | | | | | ✓ | ✓ | ✓ | | | +| US East (N. Virginia) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| US East (Ohio) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| US West (N. California) | ✓ | ✓ | | | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | +| US West (Oregon) | ✓ | ✓ | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| US East GovCloud (N. Virginia) | | | ✓ | ✓ | | | | ✓ | | | | + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-default-azure-configurations.md b/deploy-manage/deploy/elastic-cloud/ech-default-azure-configurations.md new file mode 100644 index 000000000..0c841b2a9 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-default-azure-configurations.md @@ -0,0 +1,63 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-default-azure-configurations.html +--- + +# Elasticsearch Add-On for Heroku Azure default provider instance configurations [ech-default-azure-configurations] + +Following are the preferred instance types / machine configurations, storage types, disk to memory ratios, and virtual CPU to RAM ratios for all instance configurations available on {{ess}} and provided by Azure. + +| Instance configuration | Preferred Instance Type or Machine Configuration1 | Storage Type1 | Disk:Memory Ratio2 | vCPU/RAM Ratio | +| --- | --- | --- | --- | --- | +| $$$azure.es.datahot.edsv4$$$ `azure.es.datahot.edsv4` | e8dsv4 | Standard Managed Disks (SSD) | 35:1 | 0.133 | +| $$$azure.es.datahot.ddv4$$$ `azure.es.datahot.ddv4` | d16dv4 | Standard Managed Disks (SSD) | 35:1 | 0.267 | +| $$$azure.es.datahot.fsv2$$$ `azure.es.datahot.fsv2` | f32sv2 | Standard Managed Disks (SSD) | 35:1 | 0.533 | +| $$$azure.es.datahot.lsv3$$$ `azure.es.datahot.lsv3` | l8sv3 | NVMe | 28:1 | 0.133 | +| $$$azure.es.datawarm.edsv4$$$ `azure.es.datawarm.edsv4` | e8dsv4 | Standard Managed Disks (HDD) | 200:1 | 0.133 | +| $$$azure.es.datacold.edsv4$$$ `azure.es.datacold.edsv4` | e8dsv4 | Standard Managed Disks (HDD) | 200:1 | 0.133 | +| $$$azure.es.datafrozen.edsv4$$$ `azure.es.datafrozen.edsv4` | e8dsv4 | Standard Managed Disks (SSD) | 90:1 | 0.133 | + + +## Additional instances [ech-additional-instances] + +Following are the preferred instance type / configuration and virtual CPU to RAM ratios for additional instance configurations available on {{ess}} and provided by Azure. + +| Instance configuration | Preferred Instance Type or Machine Configuration1 | vCPU/RAM Ratio | +| --- | --- | --- | +| $$$azure.es.master.fsv2$$$`azure.es.master.fsv2` | f32sv2 | 0.533 | +| $$$azure.es.ml.fsv2$$$`azure.es.ml.fsv2` | f32sv2 | 0.533 | +| $$$azure.es.coordinating.fsv2$$$`azure.es.coordinating.fsv2` | f32sv2 | 0.533 | +| $$$azure.kibana.fsv2$$$`azure.kibana.fsv2` | f32sv2 | 0.533 | +| $$$azure.apm.fsv2$$$`azure.apm.fsv2` | f32sv2 | 0.533 | +| $$$azure.integrationsserver.fsv2$$$`azure.integrationsserver.fsv2` | f32sv2 | 0.533 | +| $$$azure.enterprisesearch.fsv2$$$`azure.enterprisesearch.fsv2` | f32sv2 | 0.533 | + +1 Preferred instance and storage types are subject to provider availability. To learn more about our provider instances, check [AWS](https://aws.amazon.com/ec2/instance-types), [Azure](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/series/), and [GCP](https://cloud.google.com/compute/docs/machine-types) reference pages. + +2 Ratios are estimations. + +## Regional availability of instances per Azure region [ech-azure-list-region] + +The following table contains the complete list of instances available in Elastic Cloud deployments per Azure region: + +| Regions | Instances | | | | +| --- | --- | --- | --- | --- | +| | Edsv4 | Ddv4 | Fsv2 | Lsv3 | +| Australia East (New South Wales) | ✓ | ✓ | ✓ | ✓ | +| Brazil South (São Paulo) | ✓ | ✓ | ✓ | ✓ | +| Canada Central (Toronto) | ✓ | ✓ | ✓ | ✓ | +| Central India (Pune) | ✓ | ✓ | ✓ | ✓ | +| Central US (Iowa) | ✓ | ✓ | ✓ | | +| East US (Virginia) | ✓ | ✓ | ✓ | ✓ | +| East US 2 (Virginia) | ✓ | ✓ | ✓ | ✓ | +| France Central (Paris) | ✓ | ✓ | ✓ | ✓ | +| Japan East (Tokyo) | ✓ | ✓ | ✓ | ✓ | +| North Europe (Ireland) | ✓ | ✓ | ✓ | ✓ | +| South Africa North (Johannesburg) | ✓ | ✓ | ✓ | | +| South Central US (Texas) | ✓ | ✓ | ✓ | ✓ | +| South East Asia (Singapore) | ✓ | ✓ | ✓ | ✓ | +| UK South (London) | ✓ | ✓ | ✓ | ✓ | +| West Europe (Netherlands) | ✓ | ✓ | ✓ | ✓ | +| West US 2 (Washington) | ✓ | ✓ | ✓ | ✓ | + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-default-gcp-configurations.md b/deploy-manage/deploy/elastic-cloud/ech-default-gcp-configurations.md new file mode 100644 index 000000000..c6433a3db --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-default-gcp-configurations.md @@ -0,0 +1,69 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-default-gcp-configurations.html +--- + +# Elasticsearch Add-On for Heroku GCP default provider instance configurations [ech-default-gcp-configurations] + +Following are the preferred instance types / machine configurations, storage types, disk to memory ratios, and virtual CPU to RAM ratios for all instance configurations available on {{ess}} and provided by GCP. + +| Instance configuration | Preferred Instance Type or Machine Configuration1 | Storage Type1 | Disk:Memory Ratio2 | vCPU/RAM Ratio | +| --- | --- | --- | --- | --- | +| gcp.es.datahot.n2.68x10x45 | N2 | NVMe | 45:1 | 0.156 | +| gcp.es.datahot.n2.68x10x95 | N2 | NVMe | 95:1 | 0.156 | +| gcp.es.datahot.n2.68x16x45 | N2 | NVMe | 45:1 | 0.250 | +| gcp.es.datahot.n2.68x32x45 | N2 | NVMe | 45:1 | 0.500 | +| gcp.es.datahot.n2d.64x8x11 | N2d | NVMe | 11:1 | 0.133 | +| gcp.es.datawarm.n2.68x10x190 | N2 | Zonal standard persistent disk | 190:1 | 0.156 | +| gcp.es.datacold.n2.68x10x190 | N2 | Zonal standard persistent disk | 190:1 | 0.156 | +| gcp.es.datafrozen.n2.68x10x95 | N2 | NVMe | 95:1 | 0.156 | + + +## Additional instances [ech-gcp-additional-instances] + +Following are the preferred instance configuration and virtual CPU to RAM ratios for additional instance configurations available on {{ess}} and provided by GCP. + +| Instance configuration | Preferred Instance Type or Machine Configuration1 | vCPU/RAM Ratio | +| --- | --- | --- | +| gcp.es.master.n2.68x32x45 | N2 | 0.500 | +| gcp.es.ml.n2.68x16x45 | N2 | 0.250 | +| gcp.es.ml.n2.68x32x45 | N2 | 0.500 | +| gcp.es.coordinating.n2.68x16x45 | N2 | 0.250 | +| gcp.kibana.n2.68x32x45 | N2 | 0.500 | +| gcp.apm.n2.68x32x45 | N2 | 0.500 | +| gcp.integrationsserver.n2.68x32x45 | N2 | 0.500 | +| gcp.enterprisesearch.n2.68x32x45 | N2 | 0.500 | + +1 Preferred instance and storage types are subject to provider availability. To learn more about our provider instances, check the [GCP](https://cloud.google.com/compute/docs/machine-types) reference page. + +2 Ratios are estimations. + +## Regional availability of instances per GCP region [ech-gcp-list-region] + +The following table contains the complete list of instances available in Elastic Cloud deployments per GCP region: + +| Regions | Instances | | +| --- | --- | --- | +| | N2 | N2d | +| Asia Pacific East 1 (Taiwan) | ✓ | ✓ | +| Asia Pacific Northeast 1 (Tokyo) | ✓ | ✓ | +| Asia Pacific Northeast 3 (Seoul) | ✓ | ✓ | +| Asia Pacific South 1 (Mumbai) | ✓ | ✓ | +| Asia Pacific Southeast 1 (Singapore) | ✓ | ✓ | +| Asia Pacific Southeast 2 (Jakarta) | ✓ | | +| Australia Southeast 1 (Sydney) | ✓ | ✓ | +| Europe North 1 (Finland) | ✓ | ✓ | +| Europe West 1 (Belgium) | ✓ | ✓ | +| Europe West 2 (London) | ✓ | ✓ | +| Europe West 3 (Frankfurt) | ✓ | ✓ | +| Europe West 4 (Netherlands) | ✓ | ✓ | +| Europe West 9 (Paris) | ✓ | ✓ | +| ME West 1 (Tel Aviv) | ✓ | ✓ | +| North America Northeast 1 (Montreal) | ✓ | ✓ | +| South America East 1 (Sao Paulo) | ✓ | ✓ | +| US Central 1 (Iowa) | ✓ | ✓ | +| US East 1 (South Carolina) | ✓ | ✓ | +| US East 4 (N. Virginia) | ✓ | ✓ | +| US West 1 (Oregon) | ✓ | ✓ | + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-gcp-instance-configuration.md b/deploy-manage/deploy/elastic-cloud/ech-gcp-instance-configuration.md new file mode 100644 index 000000000..b08d7055e --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-gcp-instance-configuration.md @@ -0,0 +1,76 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-gcp-instance-configuration.html +--- + +# Elasticsearch Add-On for Heroku GCP instance configurations [ech-gcp-instance-configuration] + +Google Compute Engine (GCE) N2 general purpose VM types are now available for Elastic Cloud deployments in all supported [Google Cloud regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html#ec-gcp_regions). [N2](https://cloud.google.com/compute/docs/machine-types) VMs have a better mix of vCPU, RAM, and internal disk, and are up to 50% more cost effective when compared to N1 VM types. In addition to N2, we also provide N2D VMs across the Google Cloud regions. + +To learn about the GCE specific configurations, check: + +* [VM configurations](#ech-gcp-vm-configurations) +* [Selecting the right configuration for you](#ech-gcp-configuration-choose) +* [GCP default provider instance configurations](ech-default-gcp-configurations.md) +* [Regional availability of instances per GCP region](ech-default-gcp-configurations.md#ech-gcp-list-region) + +## VM configurations [ech-gcp-vm-configurations] + +For the Google Cloud infrastructure upgrade, rather than using default baseline configurations, [custom machine types](https://cloud.google.com/custom-machine-types) unique to Google Cloud are used so individual parameters of each VM can be fine tuned to fit the right blend of RAM:CPU:Disk. To accommodate the custom configuration, a new common nomenclature is introduced to help you easily identify each VM type. This will apply eventually to AWS and Azure instances as well, as we roll out newer versions of VMs for these providers. + +For example, Instance ID / SKU: `gcp.es.datahot.n2.68x10x45` + +| | | +| --- | --- | +| `gcp.*` | Denotes the cloud provider, GCP in this case or AWS/Azure in future cases. | +| `\*.es.datahot.*` | Denotes that this configuration is an Elasticsearch (`es`) cluster component that serves as a data node for hot content. Other options may be `datawarm`, `datacold`, `datafrozen` for data nodes, and `kibana`, `master`, and so on for other components. | +| `\*.n2.*` | Denotes that this configuration is running on the GCP N2 family. | +| `*.68x10x45` | Denotes the resource configuration, delimited by “x”.
* The first argument (`68`) denotes the total gross RAM capacity of the instance. Normally we use 4GB of that for utilities and therefore this configuration has a “usable RAM” of 64GB.
* The second argument (`10`) denotes the number of vCPUs allocated to the entire machine.
* The third argument denotes the ratio of RAM to storage capacity as in 1:X. In this case, for each 1GB of RAM, you will have 45 GB of disk to store Elasticsearch data. | + +The new configuration naming convention aligns with the [data tiers](https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tiers.html) intended for each configuration type, replacing prior naming conventions of “highio”, “highcpu”, and so on. The following table details the new configurations for data nodes and compares them with prior naming conventions where applicable. + +| New config name | Notes | +| --- | --- | +| gcp.es.datahot.n2.68x10x45 | This configuration replaces “highio”, which is based on N1 with 1:30 RAM:disk and similar RAM:CPU ratios. | +| gcp.es.datahot.n2.68x10x95 | This is a new configuration that is similar to the first, but with more disk space to allow for longer retention in ingest use cases, or larger catalog in search use cases. | +| gcp.es.datahot.n2.68x16x45 | This configuration replaces “highcpu”, which is based on N1 with 1:8 RAM:disk and similar RAM:CPU ratios. | +| gcp.es.datahot.n2.68x32x45 | This is a new configuration that provides double the CPU capacity compared to “highcpu” or [68-16-1:45] configuration. It is intended for high throughput ingest use cases or intensive search use cases. | +| gcp.es.datahot.n2d.64x8x11 | This is a new configuration powered by AMD processors which offers a better price-performance compared to Intel processors. | +| gcp.es.datawarm.n2.68x10x190, gcp.es.datacold.n2.68x10x190 | These configurations replace “highstorage”, which is based on N1 with 1:160 RAM:disk and similar RAM:CPU ratios. | +| gcp.es.datafrozen.n2.68x10x95 | This configuration replaces the (short lived) gcp.es.datafrozen.n2d.64x8x95 configuration we used for the frozen cache tier. n2d was based on the AMC epyc processor but we found that the Intel-based configuration provides a slightly better cost/performance ratio. We also tweaked the RAM/CPU ratios to align to other configurations and benchmarks. | + +For a detailed price list, check the [Elastic Cloud deployment pricing table](https://cloud.elastic.co/deployment-pricing-table?provider=gcp). For a detailed specification of the new configurations, check [Elasticsearch Service default GCP instance configurations](ech-default-gcp-configurations.md). + +The benefits of the new configurations are multifold: + +1. By using newer generations of N2 machines, there is a general boost of performance related to new chipsets and faster hardware. On average the boost we witnessed in select benchmarks can reach up to 15%, however, different workloads may exhibit different improvements. +2. The existing family types have been extended in terms of disk capacity which translates to a more cost effective infrastructure which in some cases can save up to 80% when calculating cost by disk capacity. +3. There are now more instance types to choose from in the hot tier. Rather than the traditional “highio” and “highcpu”, there are now four options to cover the hot data tier which allows to optimize cost/performance further. + +In addition to data nodes for storage and search, Elasticsearch nodes also have machine learning nodes, master nodes, and coordinating nodes. These auxiliary node types along with application nodes such as APM servers, Kibana, and Enterprise search have also been upgraded to the new N2 instance types. Both auxiliary node and application node configurations are based on Elasticsearch data node configuration types shown in the previous table. + +| New config name | Notes | +| --- | --- | +| gcp.es.master.n2.68x32x45 | Master nodes will now be based on the highest CPU rich configuration (68:32). In the past, master nodes were based on a configuration that had ¼ of the CPU for each unit of RAM (was called “highmem”). This will help boost the overall performance and stability of clusters, as master nodes have a critical role in maintaining cluster state and controlling workloads. | +| gcp.es.ml.n2.68x16x45 | ML nodes will maintain the same type of VM configuration as in the past, but will have a new name (and billing SKU) that is consistent with the rest of the naming. | +| gcp.es.ml.n2.68x32x45 | This is a new configuration that is similar to the “gcp.es.ml.n2.68x16x45” config but with 2x more CPU per unit of RAM and similar storage ratio. | +| gcp.es.coordinating.n2.68x16x45 | Same as ML nodes - no configuration change, just a new name. | +| gcp.kibana.n2.68x32x45 | Kibana nodes have been upgraded two steps up as well, to use 4x the CPU as they had when based on “highmem”. This ensures a more performant Kibana and helps with some client side aggregation, as well as responsive UI. | +| gcp.apm.n2.68x32x45 | Same upgrade for APM. Will now use 4x the CPU. | +| gcp.integrationsserver.n2.68x32x45 | Same upgrade for Integrations Server. Will now use 4x the CPU. | +| gcp.enterprisesearch.n2.68x32x45 | Same upgrade for Enterprise Search application servers. Will now use 4x the CPU. | + + +## Selecting the right configuration for you [ech-gcp-configuration-choose] + +While far from being a comprehensive guide for performance tuning, the following advice is provided for selecting the hot tier instance configuration: + +| Deployment template | Hot data tier instance configuration | Notes | +| --- | --- | --- | +| Storage Optimized | gcp.es.datahot.n2.68x10x45 | Consider this default configuration for ingest use cases that require ~7-10 days of retention, or for light search use cases that don’t have significant index changes or CPU utilization. | +| Storage Optimized (Dense) | gcp.es.datahot.n2.68x10x95 | Consider this dense storage option for ingest use cases that have a longer retention period of the hot tier, or for light search use cases that have a significant catalog size. | +| CPU Optimized | gcp.es.datahot.n2.68x32x45 | Consider this configuration for ingest use cases that require ~1-4 days of retention, or for heavyweight search use cases that require significant and consistent indexing or high query load. | +| Vector Search Optimized | gcp.es.datahot.n2d.64x8x11 | Optimized for applications that leverage Vector Search and/or Generative AI. Also the optimal choice for utilizing ELSER for semantic search applications. Broadly suitable for all semantic search, text embedding, image search, and other Vector Search use cases. | +| General Purpose | gcp.es.datahot.n2.68x16x45 | Consider this configuration for ingest use cases that require ~5-7 days of retention, or for moderate load search use cases that require occasional indexing or medium to high query load. | + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-get-help.md b/deploy-manage/deploy/elastic-cloud/ech-get-help.md new file mode 100644 index 000000000..2b52a94fb --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-get-help.md @@ -0,0 +1,65 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-get-help.html +--- + +# Getting help [ech-get-help] + +With your Elasticsearch Add-On for Heroku subscription, you get access to support from the creators of Elasticsearch, Kibana, Beats, Logstash, and much more. We’re here to help! + + +## How do I open a support case? [echhow_do_i_open_a_support_case] + +All roads lead to the Elastic Support Portal, where you can access to all your cases, subscriptions, and licenses. + +As an Elasticsearch Add-On for Heroku customer, you will receive an email with instructions how to log in to the Support Portal, where you can track both current and archived cases. If you are a new customer who just signed up for Elasticsearch Add-On for Heroku, it can take a few hours for your Support Portal access to be set up. If you have questions, reach out to us at `support@elastic.co`. + +::::{note} +With the release of the new Support Portal, even if you have an existing account, you might be prompted to update your password. +:::: + + +There are three ways you can get to the portal: + +* Go directly to the Support Portal: [http://support.elastic.co](http://support.elastic.co) +* From the Elasticsearch Add-On for Heroku Console: Go to the [Support page](https://cloud.elastic.co/support?page=docs&placement=docs-body) or select the support icon, that looks like a life preserver, on any page in the console. +* Contact us by email: `support@elastic.co` + + If you contact us by email, please use the email address that you registered with, so that we can help you more quickly. If you are using a distribution list as your registered email, you can also register a second email address with us. Just open a case to let us know the name and email address you would like to be added. + + +When opening a case, there are a few things you can do to get help faster: + +* Include the deployment ID that you want help with, especially if you have several deployments. The deployment ID can be found on the overview page for your cluster in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +* Describe the problem. Include any relevant details, including error messages you encountered, dates and times when the problem occurred, or anything else you think might be helpful. +* Upload any pertinent files. + + +## What level of support can I expect? [echwhat_level_of_support_can_i_expect] + +Support is governed by the [Elasticsearch Add-On for Heroku Standard Terms of Service](https://www.elastic.co/legal/terms-of-service/cloud). The level of support you can expect to receive applies to your Elasticsearch Add-On for Heroku environment only and depends on your subscription level: + +Elasticsearch Add-On for Heroku Standard subscriptions +: Support is provided by email or through the Elastic Support Portal. The main focus of support is to ensure your Elasticsearch Add-On for Heroku deployment shows a green status and is available. There is no guaranteed initial or ongoing response time, but we do strive to engage on every issue within three business days. We do not offer weekend coverage, so we respond Monday through Friday only. To learn more, check [Working with Elastic Support Elasticsearch Add-On for Heroku Standard](https://www.elastic.co/support/welcome/cloud). + +Elasticsearch Add-On for Heroku Gold and Platinum subscriptions +: Support is handled by email or through the Elastic Support Portal. Provides guaranteed response times for support issues, better support coverage hours, and support contacts at Elastic. Also includes support for how-to and development questions. The exact support coverage depends on whether you are a Gold or Platinum customer. To learn more, check [Elasticsearch Add-On for Heroku Premium Support Services Policy](https://www.elastic.co/legal/support_policy/cloud_premium). + +::::{note} +If you are in free trial, you are also eligible to get the Elasticsearch Service Standard level support for as long as the trial is active. +:::: + + +If you are on an Elasticsearch Add-On for Heroku Standard subscription and you are interested in moving to Gold or Platinum support, please [contact us](https://www.elastic.co/cloud/contact). We also recommend that you read our best practices guide for getting the most out of your support experience: [https://www.elastic.co/support/welcome](https://www.elastic.co/support/welcome). + + +## Join the community forums [echjoin_the_community_forums] + +Elasticsearch, Logstash, and Kibana enjoy the benefit of having vibrant and helpful communities. You have our assurance of high-quality support and single source of truth as an Elasticsearch Add-On for Heroku customer, but the Elastic community can also be a useful resource for you whenever you need it. + +::::{tip} +As of May 1, 2017, support for Elasticsearch Add-On for Heroku **Standard** customers has moved from the Discuss forum to our link: [Elastic Support Portal](https://support.elastic.co). You should receive login instructions by email. We will also monitor the forum and help you get into the Support Portal, in case you’re unsure where to go. +:::: + + +If you have any technical questions that are not for our Support team, hop on our [Elastic community forums](https://discuss.elastic.co/) and get answers from the experts in the community, including people from Elastic. diff --git a/deploy-manage/deploy/elastic-cloud/ech-getting-started-accessing.md b/deploy-manage/deploy/elastic-cloud/ech-getting-started-accessing.md new file mode 100644 index 000000000..807f7464c --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-getting-started-accessing.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started-accessing.html +--- + +# Access the console [ech-getting-started-accessing] + +You use the console to manage your cluster from a web browser. Tasks that are available from the console include upgrading versions, configuring security features, working with custom plugins, and more. + +:::{image} ../../../images/cloud-heroku-ech-console.png +:alt: [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) +::: + +To access the console in a browser from the Heroku CLI: + +```term +heroku addons:open foundelasticsearch --app MY_APP +Opening https://addons-sso.heroku.com/apps/e286f875-cbdb-47a9-b445-e94bnnnnnnnn/addons/9b883e93-3db3-4491-b620-c3dfnnnnnnnn... +``` + +Alternatively, you can access the console by visiting the [Heroku Dashboard](https://dashboard.heroku.com/), selecting your app, and opening the Elasticsearch link. + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-getting-started-installing-version.md b/deploy-manage/deploy/elastic-cloud/ech-getting-started-installing-version.md new file mode 100644 index 000000000..48d3c7fe4 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-getting-started-installing-version.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started-installing-version.html +--- + +# Install a specific version and plugins [ech-getting-started-installing-version] + +If you want your add-on to run a specific version of Elasticsearch, use the `--elasticsearch-version` parameter. We also provide many of the plugins that are available for Elasticsearch. You use the `--plugins` parameter to specify a comma-separated list of plugins that you want installed. + +To find which Elasticsearch versions and plugins are currently available, you can omit the version to default to the latest one and add plugins later on from the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). To use your own custom plugins, you can upload and select these plugins in the console as well. + +For example: Install the add-on version 6.8.23 and include the phonetic analysis plugin for MY_APP: + +```term +heroku addons:create foundelasticsearch --elasticsearch-version 6.8.23 --plugins analysis-phonetic --app MY_APP +``` + +After the add-on gets added, you can perform future version upgrades and plugin changes through the [console](ech-getting-started-accessing.md). + diff --git a/deploy-manage/deploy/elastic-cloud/ech-getting-started-installing.md b/deploy-manage/deploy/elastic-cloud/ech-getting-started-installing.md new file mode 100644 index 000000000..25b8a4400 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-getting-started-installing.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started-installing.html +--- + +# Install the add-on [ech-getting-started-installing] + +These steps walk you through installing the Elasticsearch Add-On for Heroku from the Heroku CLI. You can either install the latest default version of the add-on or you can install a specific version and include plugins at the same time. + + +## Before you begin [echbefore_you_begin] + +The installation steps in this section assume that you have a basic working knowledge of the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and are familiar with using the command line. To work with the Elasticsearch Add-On for Heroku from the command line, you need to have the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) already installed. + +If you prefer to install the add-on through your web browser, go to the [Elasticsearch add-on](https://elements.heroku.com/addons/foundelasticsearch) page in the Elements Marketplace, select **Install Elasticsearch**, pick the add-on plan you want, and select **Provision add-on**. + + +## Steps [echsteps] + +To install the latest add-on for MY_APP using the Heroku CLI: + +```term +heroku addons:create foundelasticsearch --app MY_APP +``` + +After the Elasticsearch Add-On for Heroku gets added, you can find the canonical URL you use to access your newly provisioned cluster in the configuration for the app. Look for the `FOUNDELASTICSEARCH_URL` setting when you grep on the output of the `heroku config` command: + +```term +heroku config --app MY_APP | grep FOUNDELASTICSEARCH_URL +FOUNDELASTICSEARCH_URL: https://74f176887fdef36bb51e6e37nnnnnnnn.us-east-1.aws.found.io +``` + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-getting-started-next-steps.md b/deploy-manage/deploy/elastic-cloud/ech-getting-started-next-steps.md new file mode 100644 index 000000000..1b3c02768 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-getting-started-next-steps.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started-next-steps.html +--- + +# Next steps [ech-getting-started-next-steps] + +Now that you have provisioned your first deployment, you’re ready to index data into the deployment and explore the advanced capabilities of Elasticsearch Add-On for Heroku. + + +## Index data [ech-ingest-data] + +It’s why you’re here right? You’re looking to solve an issue or improve your experience with your data. + +There are several ways to ingest data into the deployment: + +* Use the sample data available from the Kibana home page in versions 6.4.0 and later, without loading your own data. There are multiple data sets available and you can add them with one click. +* Got existing Elasticsearch data? Consider your [migration options](../../../manage-data/migrate.md). + + +## Increase security [ech-increase-security] + +You might want to add more layers of security to your deployment, such as: + +* Add more users to the deployment with third-party authentication providers and services like [SAML](../../users-roles/cluster-or-deployment-auth/saml.md), [OpenID Connect](../../users-roles/cluster-or-deployment-auth/openid-connect.md), or [Kerberos](../../users-roles/cluster-or-deployment-auth/kerberos.md). +* Do not use clients that only support HTTP to connect to Elastic Cloud. If you need to do so, you should use a reverse proxy setup. +* Create [traffic filters](../../security/traffic-filtering.md) and apply them to your deployments. +* If needed, you can [reset](../../users-roles/cluster-or-deployment-auth/built-in-users.md) the `elastic` password. + + +## Scale or adjust your deployment [echscale_or_adjust_your_deployment] + +You might find that you need a larger deployment for the workload. Or maybe you want to upgrade the Elasticsearch version for the latest features. Perhaps you’d like to add some plugins, enable APM, or machine learning. All of this can be done after provisioning by [changing your deployment configuration](cloud-hosted.md). + diff --git a/deploy-manage/deploy/elastic-cloud/ech-getting-started-removing.md b/deploy-manage/deploy/elastic-cloud/ech-getting-started-removing.md new file mode 100644 index 000000000..4d67196e6 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-getting-started-removing.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started-removing.html +--- + +# Remove the add-on [ech-getting-started-removing] + +::::{warning} +This action will destroy all associated data and cannot be undone. +:::: + + +To remove the add-on from MY_APP using the Heroku CLI: + +```term +heroku addons:destroy foundelasticsearch --app MY_APP + + ▸ WARNING: Destructive Action + ▸ This command will affect the app testing-heroku-es + ▸ To proceed, type MY_APP or re-run this command with + ▸ --confirm MY_APP + +> MY_APP +Destroying foundelasticsearch-trapezoidal-nnnnn on ⬢ MY_APP... done +``` + diff --git a/deploy-manage/deploy/elastic-cloud/ech-getting-started.md b/deploy-manage/deploy/elastic-cloud/ech-getting-started.md new file mode 100644 index 000000000..919f59199 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-getting-started.md @@ -0,0 +1,15 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started.html +--- + +# Introducing Elasticsearch Add-On for Heroku [ech-getting-started] + +This documentation applies to Heroku users who want to make use of the Elasticsearch Add-On for Heroku that is available from the [Heroku Dashboard](https://dashboard.heroku.com/) or that can be installed from the CLI. + +The add-on runs on the Elasticsearch Service and provides access to [Elasticsearch](https://www.elastic.co/products/elasticsearch), the open source, distributed, RESTful search engine. Many other features of the Elastic Stack are also readily available to Heroku users through the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) after you install the add-on. For example, you can use Kibana to visualize your Elasticsearch data. + +[Elasticsearch Machine Learning](https://www.elastic.co/guide/en/machine-learning/current/index.html), [Elastic Enterprise Search](https://www.elastic.co/guide/en/enterprise-search/current/index.html), [Elastic APM](https://www.elastic.co/guide/en/apm/guide/8.4/apm-overview.html) and [Elastic Fleet Server](https://www.elastic.co/guide/en/fleet/current/fleet-overview.html) are not supported by the Elasticsearch Add-On for Heroku. + +To learn more about what plans are available for Heroku users and their cost, check the [Elasticsearch add-on](https://elements.heroku.com/addons/foundelasticsearch) in the Elements Marketplace. + diff --git a/deploy-manage/deploy/elastic-cloud/ech-licensing.md b/deploy-manage/deploy/elastic-cloud/ech-licensing.md new file mode 100644 index 000000000..0947a8014 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-licensing.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-licensing.html +--- + +# Subscription levels [ech-licensing] + +For more information on what is available with different subscription levels, check [Elasticsearch Add-On for Heroku Subscriptions](https://www.elastic.co/elasticsearch/service/pricing). You are entitled to use all of the features in Elasticsearch Add-On for Heroku that match your subscription level. Please use them to your heart’s content. + +Your subscription determines [which features are available](https://www.elastic.co/subscriptions/cloud). For example, machine learning requires a Platinum or Private subscription and is not available if you upgrade to a Gold subscription. Similarly, SAML Single Sign-On requires an Enterprise subscription. + diff --git a/deploy-manage/deploy/elastic-cloud/ech-migrate-data-internal.md b/deploy-manage/deploy/elastic-cloud/ech-migrate-data-internal.md new file mode 100644 index 000000000..c4f132ce2 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-migrate-data-internal.md @@ -0,0 +1,97 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-migrate-data-internal.html +--- + +# Migrate internal indices [ech-migrate-data-internal] + +When you migrate your Elasticsearch data into a new infrastructure you may also want to migrate your Elasticsearch internal indices, specifically the `.kibana` index and the `.security` index. + +There are two ways to migrate the internal Elasticsearch indices: + +1. Reindex the indices from a remote cluster. +2. Restore the indices from a snapshot. + +To reindex internal indices from a remote cluster, you can follow the same steps that you use to reindex regular indices when you [migrate your Elasticsearch data indices](../../../manage-data/migrate.md#ech-reindex-remote). + +To restore internal indices from a snapshot, the procedure is a bit different from migrating Elasticsearch data indices. Use these steps to restore internal indices from a snapshot: + +1. On your old Elasticsearch cluster, choose an option to get the name of your snapshot repository bucket: + + ```sh + GET /_snapshot + GET /_snapshot/_all + ``` + +2. Get the snapshot name: + + ```sh + GET /_snapshot/NEW-REPOSITORY-NAME/_all + ``` + + The output for each entry provides a `"snapshot":` value which is the snapshot name. + + ``` + { + "snapshots": [ + { + "snapshot": "scheduled-1527616008-instance-0000000004", + ``` + +3. To restore internal Elasticsearch indices, you need to register the snapshot repository in `read-only` mode. To do so, first add the authentication information for the repository to the Elasticsearch Add-On for Heroku keystore, following the steps for [AWS S3](../../tools/snapshot-and-restore/ech-aws-custom-repository.md#ech-snapshot-secrets-keystore), [Google Cloud Storage](../../tools/snapshot-and-restore/ech-gcs-snapshotting.md#ech-configure-gcs-keystore), or [Azure Blog storage](../../tools/snapshot-and-restore/ech-azure-snapshotting.md#ech-configure-azure-keystore). +4. To register a read-only repository, open the Elasticsearch [API console](ech-api-console.md) or the Kibana [Dev Tools page](../../../explore-analyze/query-filter/tools.md) and run the [Read-only URL repository](../../tools/snapshot-and-restore/read-only-url-repository.md) API call. +5. Once the repository has been registered and verified, you are ready to restore the internal indices to your new cluster, either all at once or individually. + + * **Restore all internal indices** + + Run the following API call to restore all internal indices from a snapshot to the cluster: + + ```sh + POST /_snapshot/repo/snapshot/_restore + { + "indices": ".*", + "ignore_unavailable": true, + "include_global_state": false, + "include_aliases": false, + "rename_pattern": ".(.+)", + "rename_replacement": "restored_security_$1" + } + ``` + + * **Restore an individual internal index** + + ::::{warning} + When restoring internal indices, ensure that the `include_aliases` parameter is set to `false`. Not doing so will make Kibana inaccessible. If you do run the restore without `include_aliases`, the restored index can be deleted or the alias reference to it can be removed. This will have to be done from either the API console or a curl command as Kibana will not be accessible. + :::: + + + Run the following API call to restore one internal index from a snapshot to the cluster: + + ```sh + POST /_snapshot/repo/snapshot/_restore + { + "indices": ".kibana", + "ignore_unavailable": true, + "include_global_state": false, + "include_aliases": false, + "rename_pattern": ".(.+)", + "rename_replacement": "restored_security_$1" + } + ``` + + Next, the restored index needs to be reindexed into the internal index, as shown: + + ```sh + POST _reindex + { + "source": { + "index": "restored_kibana" + }, + "dest": { + "index": ".kibana" + } + } + ``` + + +Your internal Elasticsearch index or indices should now be available in your new Elasticsearch cluster. Once verified, the `restored_*` indices are safe to delete. diff --git a/deploy-manage/deploy/elastic-cloud/ech-migrate-data2.md b/deploy-manage/deploy/elastic-cloud/ech-migrate-data2.md new file mode 100644 index 000000000..d1900c2d5 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-migrate-data2.md @@ -0,0 +1,164 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-migrate-data2.html +--- + +# Migrate your Elasticsearch data [ech-migrate-data2] + +You might have switched to Elasticsearch Add-On for Heroku for any number of reasons and you’re likely wondering how to get your existing Elasticsearch data into your new infrastructure. Along with easily creating as many new deployments with Elasticsearch clusters that you need, you have several options for moving your data over. Choose the option that works best for you: + +* Index your data from the original source, which is the simplest method and provides the greatest flexibility for the Elasticsearch version and ingestion method. +* Reindex from a remote cluster, which rebuilds the index from scratch. +* Restore from a snapshot, which copies the existing indices. + +One of the many advantages of Elasticsearch Add-On for Heroku is that you can spin up a deployment quickly, try out something, and then delete it if you don’t like it. This flexibility provides the freedom to experiment while your existing production cluster continues to work. + + +## Before you begin [echbefore_you_begin_3] + +Depending on which option that you choose, you might have limitations or need to do some preparation beforehand. + +Indexing from the source +: The new cluster must be the same size as your old one, or larger, to accommodate the data. + +Reindex from a remote cluster +: The new cluster must be the same size as your old one, or larger, to accommodate the data. Depending on your security settings for your old cluster, you might need to temporarily allow TCP traffic on port 9243 for this procedure. + +Restore from a snapshot +: The new cluster must be the same size as your old one, or larger, to accommodate the data. The new cluster must also be an Elasticsearch version that is compatible with the old cluster (check [Elasticsearch snapshot version compatibility](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html#snapshot-restore-version-compatibility) for details). If you have not already done so, you will need to [set up snapshots for your old cluster](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html) using a repository that can be accessed from the new cluster. + +Migrating internal Elasticsearch indices +: If you are migrating internal Elasticsearch indices from another cluster, specifically the `.kibana` index or the `.security` index, there are two options: + + * Use the steps on this page to reindex the internal indices from a remote cluster. The steps for reindexing internal indices and regular, data indices are the same. + * Check [Migrating internal indices](../../../manage-data/migrate/migrate-internal-indices.md) to restore the internal Elasticsearch indices from a snapshot. + + +::::{warning} +Before you migrate your Elasticsearch data, [define your index mappings](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html) on the new cluster. Index mappings are unable to migrate during reindex operations. +:::: + + + +## Index from the source [ech-index-source] + +If you still have access to the original data source, outside of your old Elasticsearch cluster, you can load the data from there. This might be the simplest option, allowing you to choose the Elasticsearch version and take advantage of the latest features. You have the option to use any ingestion method that you want—​Logstash, Beats, the Elasticsearch clients, or whatever works best for you. + +If the original source isn’t available or has other issues that make it non-viable, there are still two more migration options, getting the data from a remote cluster or restoring from a snapshot. + + +## Reindex from a remote cluster [ech-reindex-remote] + +Through the Elasticsearch reindex API, you can connect your new Elasticsearch Add-On for Heroku deployment remotely to your old Elasticsearch cluster. This pulls the data from your old cluster and indexes it into your new one. Reindexing essentially rebuilds the index from scratch and it can be more resource intensive to run. + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Select a deployment or create one. +3. If the old Elasticsearch cluster is on a remote host (any type of host accessible over the internet), you need to make sure that the host can be accessed. Access is determined by the Elasticsearch `reindex.remote.whitelist` user setting. + + Domains matching the pattern `["*.io:*", "*.com:*"]` are allowed by default, so if your remote host URL matches that pattern you do not need to explicitly define `reindex.remote.whitelist`. + + Otherwise, if your remote endpoint is not covered by the default settings, adjust the setting to add the remote Elasticsearch cluster as an allowed host: + + 1. From your deployment menu, go to the **Edit** page. + 2. In the **Elasticsearch** section, select **Manage user settings and extensions**. For deployments with existing user settings, you may have to expand the **Edit elasticsearch.yml** caret for each node type instead. + 3. Add the following `reindex.remote.whitelist: [REMOTE_HOST:PORT]` user setting, where `REMOTE_HOST` is a pattern matching the URL for the remote Elasticsearch host that you are reindexing from, and PORT is the host port number. Do not include the `https://` prefix. + + Note that if you override the parameter it replaces the defaults: `["*.io:*", "*.com:*"]`. If you still want these patterns to be allowed you need to specify them explicitly in the value. + + For example: + + `reindex.remote.whitelist: ["*.us-east-1.aws.found.io:9243", "*.com:*"]` + + 4. Save your changes. + +4. From the **API Console** or in the Kibana Console app, create the destination index on Elasticsearch Add-On for Heroku. +5. Copy the index from the remote cluster: + + ```sh + POST _reindex + { + "source": { + "remote": { + "host": "https://REMOTE_ELASTICSEARCH_ENDPOINT:PORT", + "username": "USER", + "password": "PASSWORD" + }, + "index": "INDEX_NAME", + "query": { + "match_all": {} + } + }, + "dest": { + "index": "INDEX_NAME" + } + } + ``` + +6. Verify that the new index is present: + + ```sh + GET INDEX-NAME/_search?pretty + ``` + +7. You can remove the reindex.remote.whitelist user setting that you added previously. + + +## Restore from a snapshot [ech-restore-snapshots] + +If you cannot connect to a remote index for whatever reason, such as if it’s in a non-working state, you can try restoring from the most recent working snapshot. + +1. On your old Elasticsearch cluster, choose an option to get the name of your snapshot repository bucket: + + ```sh + GET /_snapshot + GET /_snapshot/_all + ``` + +2. Get the snapshot name: + + ```sh + GET /_snapshot/NEW-REPOSITORY-NAME/_all + ``` + + The output for each entry provides a `"snapshot":` value which is the snapshot name. + + ```json + { + "snapshots": [ + { + "snapshot": "scheduled-1527616008-instance-0000000004", + ... + }, + ... + ] + } + ``` + +3. From the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) of the **new** Elasticsearch cluster, add the snapshot repository. For details, check our guidelines for [Amazon Web Services (AWS) Storage](../../tools/snapshot-and-restore/ech-aws-custom-repository.md), [Google Cloud Storage (GCS)](../../tools/snapshot-and-restore/ech-gcs-snapshotting.md), or [Azure Blob Storage](../../tools/snapshot-and-restore/ech-azure-snapshotting.md). + + ::::{important} + If you’re migrating [searchable snapshots](../../tools/snapshot-and-restore/searchable-snapshots.md), the repository name must be identical in the source and destination clusters. + :::: + + + ::::{important} + If source cluster is still writing to the repository, you need to set the destination cluster’s repository connection to `readonly:true` to avoid data corruption. Refer to [backup a repository](../../tools/snapshot-and-restore/self-managed.md#snapshots-repository-backup) for details. + :::: + +4. Start the Restore process. + + 1. Open Kibana and go to **Management** > **Snapshot and Restore**. + 2. Under the **Snapshots** tab, you can find the available snapshots from your newly added snapshot repository. Select any snapshot to view its details, and from there you can choose to restore it. + 3. Select **Restore**. + 4. Select the indices you wish to restore. + 5. Configure any additional index settings. + 6. Select **Restore snapshot** to begin the process. + +5. Verify that the new index is restored in your Elasticsearch Add-On for Heroku deployment with this query: + + ```sh + GET INDEX_NAME/_search?pretty + ``` + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-migrating.md b/deploy-manage/deploy/elastic-cloud/ech-migrating.md new file mode 100644 index 000000000..0fd582300 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-migrating.md @@ -0,0 +1,42 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-migrating.html +--- + +# Migrate between plans [ech-migrating] + +Plans for the Elasticsearch Add-On for Heroku differ based on: + +* How much memory and disk space are available +* How many data centers your cluster is replicated across to achieve high availability + +Available memory is an important factor for performance when sizing your Elasticsearch cluster, and replicating across multiple data centers is important for the resilience of production applications. + +To learn more about what plans are available for Heroku users, check the [Elasticsearch add-on](https://elements.heroku.com/addons/foundelasticsearch) in the Elements Marketplace. + +You should time the migration to a new plan to ensure proper application function during the migration process. A cluster that is already overwhelmed with requests will take much longer to migrate to a larger capacity; if your workload warrants a plan change to increase capacity, migrate to a larger plan early. + +To migrate to a new plan, use the `heroku addons:upgrade` command and include one of the available plans: + +```term +foundelasticsearch:dachs-standard +foundelasticsearch:beagle-standard +foundelasticsearch:dachs-ha +foundelasticsearch:boxer-standard +foundelasticsearch:beagle-ha +foundelasticsearch:labrador-standard +foundelasticsearch:boxer-ha +foundelasticsearch:husky-standard +foundelasticsearch:labrador-ha +foundelasticsearch:husky-ha +``` + +For example: Migrate from the smallest, default `dachs-standard` plan to the larger `beagle-ha` plan that includes high availability for MY_APP: + +```term +heroku addons:upgrade foundelasticsearch:beagle-ha --app MY_APP +Changing foundelasticsearch-defined-nnnnn on MY_APP from foundelasticsearch:dachs-standard to foundelasticsearch:beagle-ha... done, $201/month +``` + +Upgrading to a new plan may involve extending the existing cluster with new nodes and migrating data from the old nodes to the new ones. When the migration is finished, the old nodes are shut down and removed from the cluster. For HA clusters, you can continue to search and index documents while this plan change is happening. + diff --git a/deploy-manage/deploy/elastic-cloud/ech-reference-hardware.md b/deploy-manage/deploy/elastic-cloud/ech-reference-hardware.md new file mode 100644 index 000000000..f62ed513f --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-reference-hardware.md @@ -0,0 +1,36 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-reference-hardware.html +--- + +# Elasticsearch Add-On for Heroku hardware [ech-reference-hardware] + +:::{image} ../../../images/cloud-heroku-ec-cloud-platform-hardware.png +:alt: A banner showing a plane trailing several stylized UI sliders superimposed over cloud hardware +::: + +Use this information to better understand how Elasticsearch Add-On for Heroku instance configurations (for example `azure.es.datahot.ddv4`, `gcp.es.datahot.n2.68x10x45`, or `aws.es.datahot.c6gd`) relate to the underlying cloud provider hardware that we use when you create your deployment. + + +## Instance configurations [ech-getting-started-configurations] + +Deployments use a range of virtualized hardware resources from a cloud provider, such as Amazon EC2 (AWS), Google Compute Platform (GCP) or Microsoft Azure. Instance configurations enable the products and features of the Elastic Stack to run on suitable resources that support their intended purpose. For example, if you have a logging use case that benefits from large amounts of slower but more cost-efficient storage space, you can use large spindle drives rather than more expensive SSD storage. Each instance configuration provides a combination of CPU resources, memory, and storage, all of which you can scale from small to very large. + +::::{note} +All instances, regardless of the region or provider, are set to UTC timezone. +:::: + + +To understand the naming convention of instance configuration per cloud provider, refer to [Azure instance configurations](ech-azure-instance-configuration.md), [GCP instance configurations](ech-gcp-instance-configuration.md) and [AWS instance configurations](ech-aws-instance-configuration.md). + +::::{tip} +Instance configurations are an Elasticsearch Add-On for Heroku abstraction of virtualized resources from the provider, but you might recognize the underlying hardware they build on in the instance configuration name. We use *instance types* on AWS and Azure, and *custom machine types* on GCP. Elasticsearch Add-On for Heroku instance configurations are not the same as AWS instance types. +:::: + + + + + + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-reference-regions.md b/deploy-manage/deploy/elastic-cloud/ech-reference-regions.md new file mode 100644 index 000000000..3083a1edc --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-reference-regions.md @@ -0,0 +1,29 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-reference-regions.html +--- + +# Elasticsearch Add-On for Heroku regions [ech-reference-regions] + +A region is the geographic area where the data center of the cloud provider that hosts your deployment is located. Use the information listed here to decide which Elasticsearch Add-On for Heroku region to use. Your choice should be based on: + +* Your geographic proximity to the region. Picking a region that is closer to you typically reduces latency for indexing and search requests. +* The features that we support for the region. Not all regions support the same set of features. + +Elasticsearch Add-On for Heroku handles all hosting details for you, no additional accounts with the underlying cloud provider required. The region you select cannot be changed after you create a deployment. If you want to use a different region later on, you can create a new deployment and reindex your data into it. + +::::{tip} +If you are not sure what to pick, choose a region that is geographically close to you to reduce latency. You should always use HTTPS to connect to the Elastic stack components of your deployment. +:::: + + + +## Amazon Web Services (AWS) regions [echamazon_web_services_aws_regions] + +The following AWS regions are available: + +| Region | Name | Supports | +| --- | --- | --- | +| eu-west-1 | EU (Ireland) | HTTPS only | +| us-east-1 | US East (N. Virginia) | HTTPS only | + diff --git a/deploy-manage/deploy/elastic-cloud/ech-restrictions.md b/deploy-manage/deploy/elastic-cloud/ech-restrictions.md new file mode 100644 index 000000000..316c84efd --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-restrictions.md @@ -0,0 +1,132 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-restrictions.html +--- + +# Restrictions and known problems [ech-restrictions] + +When using Elasticsearch Add-On for Heroku, there are some limitations you should be aware of: + +* [Elasticsearch Add-On for Heroku](#ech-restrictions-heroku) +* [Security](#ech-restrictions-security) +* [Elasticsearch and Kibana plugins](#ech-restrictions-plugins) +* [Kibana](#ech-restrictions-kibana) +* [APM Agent central configuration with Private Link or traffic filters](#ech-restrictions-apm-traffic-filters) +* [Fleet with Private Link or traffic filters](#ech-restrictions-fleet-traffic-filters) +* [Enterprise Search in Kibana](#ech-restrictions-enterprise-search-kibana-integration-traffic-filters) +* [Restoring a snapshot across deployments](#ech-snapshot-restore-enterprise-search-kibana-across-deployments) +* [Migrate Fleet-managed {{agents}} across deployments by restoring a snapshot](#ech-migrate-elastic-agent) +* [Regions and Availability Zones](#ech-regions-and-availability-zone) +* [Known problems](#ech-known-problems) + +For limitations related to logging and monitoring, check the [Restrictions and limitations](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) section of the logging and monitoring page. + +Occasionally, we also publish information about [Known problems](#ech-known-problems) with our Elasticsearch Add-On for Heroku or the Elastic Stack. + +To learn more about the features that are supported by Elasticsearch Add-On for Heroku, check [Elastic Cloud Subscriptions](https://www.elastic.co/cloud/elasticsearch-service/subscriptions?page=docs&placement=docs-body). + + +## Elasticsearch Add-On for Heroku [ech-restrictions-heroku] + +Not all features of our Elasticsearch Service are available to Heroku users. Specifically, you cannot create additional deployments or use different deployment templates. + +Generally, if a feature is shown as available in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body), you can use it. + + +## Security [ech-restrictions-security] + +* File and LDAP realms cannot be used. The Native realm is enabled, but the realm configuration itself is fixed in {{ecloud}}. Alternatively, authentication protocols such as SAML, OpenID Connect, or Kerberos can be used. +* Client certificates, such as PKI certificates, are not supported. +* IPv6 is not supported. + + +## Transport client [ech-restrictions-transport-client] + +* The transport client is not considered thread safe in a cloud environment. We recommend that you use the Java REST client instead. This restriction relates to the fact that your deployments hosted on Elasticsearch Add-On for Heroku are behind proxies, which prevent the transport client from communicating directly with Elasticsearch clusters. +* The transport client is not supported over [private link connections](../../security/aws-privatelink-traffic-filters.md). Use the Java REST client instead, or connect over the public internet. +* The transport client does not work with Elasticsearch clusters at version 7.6 and later that are hosted on Cloud. Transport client continues to work with Elasticsearch clusters at version 7.5 and earlier. Note that the transport client was deprecated with version 7.0 and will be removed with 8.0. + + +## Elasticsearch and Kibana plugins [ech-restrictions-plugins] + +* Kibana plugins are not supported. +* Elasticsearch plugins, are not enabled by default for security purposes. Please reach out to support if you would like to enable Elasticsearch plugins support on your account. +* Some Elasticsearch plugins do not apply to Elasticsearch Add-On for Heroku. For example, you won’t ever need to change discovery, as Elasticsearch Add-On for Heroku handles how nodes discover one another. +* In Elasticsearch 5.0 and later, site plugins are no longer supported. This change does not affect the site plugins Elasticsearch Add-On for Heroku might provide out of the box, such as Kopf or Head, since these site plugins are serviced by our proxies and not Elasticsearch itself. +* In Elasticsearch 5.0 and later, site plugins such as Kopf and Paramedic are no longer provided. We recommend that you use our [cluster performance metrics](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md), [X-Pack monitoring features](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) and Kibana’s (6.3+) [Index Management UI](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-mgmt.html) if you want more detailed information or perform index management actions. + + +## Private Link and SSO to Kibana URLs [ech-restrictions-traffic-filters-kibana-sso] + +Currently you can’t use SSO to login directly from {{ecloud}} into Kibana endpoints that are protected by Private Link traffic filters. However, you can still SSO into Private Link protected Kibana endpoints individually using the [SAML](../../users-roles/cluster-or-deployment-auth/saml.md) or [OIDC](../../users-roles/cluster-or-deployment-auth/openid-connect.md) protocol from your own identity provider, just not through the {{ecloud}} console. Stack level authentication using the {{es}} username and password should also work with `{{kibana-id}}.{vpce|privatelink|psc}.domain` URLs. + + +## PDF report generation using Alerts or Watcher webhooks [ech-restrictions-traffic-filters-watcher] + +* PDF report automatic generation via Alerts is not possible on Elastic Cloud. +* PDF report generation isn’t possible for deployments running on Elastic stack version 8.7.0 or before that are protected by traffic filters. This limitation doesn’t apply to public webhooks such as Slack, PagerDuty, and email. For deployments running on Elastic stack version 8.7.1 and beyond, [PDF report automatic generation via Watcher webhook](../../../explore-analyze/report-and-share/automating-report-generation.md#use-watcher) is possible using the `xpack.notification.webhook.additional_token_enabled` configuration setting to bypass traffic filters. + + +## Kibana [ech-restrictions-kibana] + +* The maximum size of a single {{kib}} instance is 8GB. This means, {{kib}} instances can be scaled up to 8GB before they are scaled out. For example, when creating a deployment with a {{kib}} instance of size 16GB, then 2x8GB instances are created. If you face performance issues with {{kib}} PNG or PDF reports, the recommendations are to create multiple, smaller dashboards to export the data, or to use a third party browser extension for exporting the dashboard in the format you need. +* Running an external Kibana in parallel to Elasticsearch Add-On for Heroku’s Kibana instances may cause errors, for example [`Unable to decrypt attribute`](../../../explore-analyze/alerts/kibana/alerting-common-issues.md#rule-cannot-decrypt-api-key), due to a mismatched [`xpack.encryptedSavedObjects.encryptionKey`](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#security-encrypted-saved-objects-settings) as Elasticsearch Add-On for Heroku does not [allow users to set](edit-stack-settings.md) nor expose this value. While workarounds are possible, this is not officially supported nor generally recommended. + + +## APM Agent central configuration with PrivateLink or traffic filters [ech-restrictions-apm-traffic-filters] + +If you are using APM 7.9.0 or older: + +* You cannot use [APM Agent central configuration](https://www.elastic.co/guide/en/kibana/current/agent-configuration.html) if your deployment is secured by [traffic filters](../../security/traffic-filtering.md). +* If you access your APM deployment over [PrivateLink](../../security/aws-privatelink-traffic-filters.md), to use APM Agent central configuration you need to allow access to the APM deployment over public internet. + + +## Fleet with PrivateLink or traffic filters [ech-restrictions-fleet-traffic-filters] + +* You cannot use Fleet 7.13.x if your deployment is secured by [traffic filters](../../security/traffic-filtering.md). Fleet 7.14.0 and later works with traffic filters (both Private Link and IP filters). +* If you are using Fleet 8.12+, using a remote {{es}} output with a target cluster that has [traffic filters](../../security/traffic-filtering.md) enabled is not currently supported. + + +## Enterprise Search in Kibana [ech-restrictions-enterprise-search-kibana-integration-traffic-filters] + +Enterprise Search’s management interface in Kibana does not work with traffic filters with 8.3.1 and older, it will return an `Insufficient permissions` (403 Forbidden) error. In Kibana 8.3.2, 8.4.0 and higher, the Enterprise Search management interface works with traffic filters. + + +## Restoring a snapshot across deployments [ech-snapshot-restore-enterprise-search-kibana-across-deployments] + +Kibana and Enterprise Search do not currently support restoring a snapshot of their indices across Elastic Cloud deployments. + +* [Kibana uses encryption keys](https://www.elastic.co/guide/en/kibana/current/using-kibana-with-security.html#security-configure-settings) in various places, ranging from encrypting data in some areas of reporting, alerts, actions, connector tokens, ingest outputs used in Fleet and Synthetics monitoring to user sessions. +* [Enterprise Search uses encryption keys](https://www.elastic.co/guide/en/enterprise-search/current/encryption-keys.html) when storing content source synchronization credentials, API tokens and other sensitive information. +* Currently, there is not a way to retrieve the values of Kibana and Enterprise Search encryption keys, or set them in the target deployment before restoring a snapshot. As a result, once a snapshot is restored, Kibana and Enterprise Search will not be able to decrypt the data required for some Kibana and Enterprise Search features to function properly in the target deployment. +* If you have already restored a snapshot across deployments and now have broken Kibana saved objects or Enterprise Search features in the target deployment, you will have to recreate all broken configurations and objects, or create a new setup in the target deployment instead of using snapshot restore. + +A snapshot taken using the default `found-snapshots` repository can only be restored to deployments in the same region. If you need to restore snapshots across regions, create the destination deployment, connect to the [custom repository](../../tools/snapshot-and-restore/elastic-cloud-hosted.md), and then [restore from a snapshot](../../tools/snapshot-and-restore/restore-snapshot.md). + +When restoring from a deployment that’s using searchable snapshots, you must not delete the snapshots in the source deployment even after they are successfully restored in the destination deployment. + + +## Migrate Fleet-managed {{agents}} across deployments by restoring a snapshot [ech-migrate-elastic-agent] + +There are situations where you may need or want to move your installed {{agents}} from being managed in one deployment to being managed in another deployment. + +In {{ecloud}}, you can migrate your {{agents}} by taking a snapshot of your source deployment, and restoring it on a target deployment. + +To make a seamless migration, after restoring from a snapshot there are some additional steps required, such as updating settings and resetting the agent policy. Check [Migrate Elastic Agents](https://www.elastic.co/guide/en/fleet/current/migrate-elastic-agent.html) for details. + + +## Regions and Availability Zones [ech-regions-and-availability-zone] + +* The AWS `us-west-1` region is limited to two availability zones for ES data nodes and one (tiebreaker only) virtual zone (as depicted by the `-z` in the AZ (`us-west-1z`). Deployment creation with three availability zones for Elasticsearch data nodes for hot, warm, and cold tiers is not possible. This includes scaling an existing deployment with one or two AZs to three availability zones. The virtual zone `us-west-1z` can only hold an Elasticsearch tiebreaker node (no data nodes). The workaround is to use a different AWS US region that allows three availability zones, or to scale existing nodes up within the two availability zones. +* The AWS `eu-central-2` region is limited to two availability zones for CPU Optimized (ARM) Hardware profile ES data node and warm/cold tier. Deployment creation with three availability zones for Elasticsearch data nodes for hot (for CPU Optimized (ARM) profile), warm and cold tiers is not possible. This includes scaling an existing deployment with one or two AZs to three availability zones. The workaround is to use a different AWS region that allows three availability zones, or to scale existing nodes up within the two availability zones. + + +## Known problems [ech-known-problems] + +* There is a known problem affecting clusters with versions 7.7.0 and 7.7.1 due to [a bug in Elasticsearch](https://github.com/elastic/elasticsearch/issues/56739). Although rare, this bug can prevent you from running plans. If this occurs we recommend that you retry the plan, and if that fails please contact support to get your plan through. Because of this bug we recommend you to upgrade to version 7.8 and higher, where the problem has already been addressed. +* A known issue can prevent direct rolling upgrades from Elasticsearch version 5.6.10 to version 6.3.0. As a workaround, we have removed version 6.3.0 from the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) for new cluster deployments and for upgrading existing ones. If you are affected by this issue, check [Rolling upgrades from 5.6.x to 6.3.0 fails with "java.lang.IllegalStateException: commit doesn’t contain history uuid"](https://elastic.my.salesforce.com/articles/Support_Article/Rolling-upgrades-to-6-3-0-from-5-x-fails-with-java-lang-IllegalStateException-commit-doesn-t-contain-history-uuid?popup=false&id=kA0610000005JFG) in our Elastic Support Portal. If these steps do not work or you do not have access to the Support Portal, you can contact `support@elastic.co`. + + +## Repository Analysis API is unavailable in Elastic Cloud [ech-repository-analyis-unavailable] + +* The Elasticsearch [Repository analysis API](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html) is not available in {{ecloud}} due to deployments defaulting to having [operator privileges](../../users-roles/cluster-or-deployment-auth/operator-privileges.md) enabled that prevent non-operator privileged users from using it along with a number of other APIs. diff --git a/deploy-manage/deploy/elastic-cloud/ech-service-status.md b/deploy-manage/deploy/elastic-cloud/ech-service-status.md new file mode 100644 index 000000000..9a8718c66 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-service-status.md @@ -0,0 +1,30 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-service-status.html +--- + +# Service status [ech-service-status] + +Elasticsearch Add-On for Heroku is a hosted service for the Elastic Stack that runs on different cloud platforms, such as Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. Like any service, it might undergo availability changes from time to time. When availability changes, Elastic makes sure to provide you with a current service status. + +To check current and past service availability, go to [Cloud Status](https://cloud-status.elastic.co/) page. + + +## Subscribe to updates [echsubscribe_to_updates] + +Don’t want to check the service status page manually? You can get notified about changes to the service status automatically. + +To receive service status updates: + +1. Go to the [Cloud Status](https://cloud-status.elastic.co/) page and select **SUBSCRIBE TO UPDATES**. +2. Select one of the following methods to be notified of status updates: + + * Email + * Twitter + * Atom and RSS feeds + + +After you subscribe to updates, you are notified whenever a service status update is posted. + + + diff --git a/deploy-manage/deploy/elastic-cloud/ech-version-policy.md b/deploy-manage/deploy/elastic-cloud/ech-version-policy.md new file mode 100644 index 000000000..2ee4d36e7 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-version-policy.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-version-policy.html +--- + +# Version policy [ech-version-policy] + +This section describes our version policy for Elasticsearch Add-On for Heroku, including: + +* [What Elastic Stack versions are available](#ech-version-policy-available) +* [When we make new Elastic Stack versions available](#ech-version-policy-new) +* [When we might force an upgrade or restart to keep your cluster safe](#ech-version-policy-critical) +* [What release candidates and cutting edge builds we make available](#ech-release-builds) +* [What happens when a version reaches its end-of-life (EOL)](#ech-version-policy-eol) + + +## Available Elastic Stack versions [ech-version-policy-available] + +Elastic Stack uses a versions code that is constructed of three numbers separated by dots: the leftmost number is the number of the major release, the middle number is the number of the minor release and the rightmost number is the number of the maintenance release (e.g., 8.3.2 means major release 8, minor release 3 and maintenance release 2). + +You might sometimes notice additional versions listed in the user interface beyond the versions we currently support and maintain, such as [release candidate builds](#ech-release-builds) and older versions. If a version is listed in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body), it can be deployed. + + +## New Elastic Stack versions [ech-version-policy-new] + +Whenever a new Elastic Stack version is released, we do our best to provide the new version on our hosted service at the same time. We send you an email and add a notice to the console, recommending an upgrade. You’ll need to decide whether to upgrade to the new version with new features and bug fixes or to stay with a version you know works for you a while longer. + +There can be [breaking changes](https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes.html) in some new versions of Elasticsearch that break what used to work in older versions. Before upgrading, you’ll want to check if the new version introduces any changes that might affect your applications. A breaking change might be a function that was previously deprecated and that has been removed in the latest version, for example. If you have an application that depends on the removed function, the application will need to be updated to continue working with the new version of Elasticsearch. + +To learn more about upgrading to newer versions of the Elastic Stack on our hosted service, check [Upgrade Versions](../../upgrade/deployment-or-cluster.md). + + +## Upgrades or restart for critical issues [ech-version-policy-critical] + +We reserve the right to force upgrade or restart a cluster immediately and without notice in advance if there is a critical security or stability issue. Such upgrades happen only within minor versions. + +A forced upgrade or restart might become necessary in a situation that: + +* Bypasses Shield, where knowing only the cluster endpoint is sufficient to gain access to data. +* Disrupts our ability to effectively manage a cluster in disaster scenarios +* Impairs stability to the point where we cannot guarantee cluster node or data integrity +* Impairs or risks impairing our infrastructure + + +## Release candidates and cutting-edge releases [ech-release-builds] + +Interested in kicking the tires of Elasticsearch releases at the cutting edge? We sometimes make release candidate builds and other cutting-edge releases available in Elasticsearch Add-On for Heroku for you to try out. + +::::{warning} +Remember that cutting-edge releases are used to test new function fully. These releases might still have issues and might be less stable than the GA version. There’s also no guaranteed upgrade path to the GA version when it becomes available. +:::: + + +If you’re interested in trying out one of these cutting-edge releases, we don’t recommended upgrading an existing deployment directly. Instead, use a copy of your existing data with a test deployment, first. + +Cutting-edge releases do not remain available forever. Once the GA version of Elasticsearch is released, your deployment needs to be removed after a grace period. We cannot guarantee that you will be able to upgrade to the GA version when it becomes available. + + +## Version Policy and Product End of Life [ech-version-policy-eol] + +For Elasticsearch Service, we follow the [Elastic Version Maintenance and Support Policy](https://www.elastic.co/support/eol), which defines the support and maintenance policy of the Elastic Stack. diff --git a/deploy-manage/deploy/elastic-cloud/ech-whats-new.md b/deploy-manage/deploy/elastic-cloud/ech-whats-new.md new file mode 100644 index 000000000..3012262e1 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-whats-new.md @@ -0,0 +1,37 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-whats-new.html +--- + +# What���s new with the Elastic Stack [ech-whats-new] + +As soon as the latest Elastic Stack version is released, we make it available to you. + +From the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body), you can upgrade your existing deployments to the latest versions of the Elastic Stack. To learn more about the best practices to use when upgrading, refer to [Upgrade versions](../../upgrade/deployment-or-cluster.md). + +Check our [Version policy](ech-version-policy.md) to learn about when and how new Elastic Stack versions are made available. + +Check the Release Notes to get the recent updates for each product. + +Elasticsearch + +* [Elasticsearch 8.x Release Notes](https://www.elastic.co/guide/en/elasticsearch/reference/current/es-release-notes.html) +* [Elasticsearch 7.x Release Notes](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/es-release-notes.html) +* [Elasticsearch 6.x Release Notes](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/es-release-notes.html) +* [Elasticsearch 5.x Release Notes](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/es-release-notes.html) + +Kibana + +* [Kibana 8.x Release Notes](https://www.elastic.co/guide/en/kibana/current/release-notes.html) +* [Kibana 7.x Release Notes](https://www.elastic.co/guide/en/kibana/7.17/release-notes.html) +* [Kibana 6.x Release Notes](https://www.elastic.co/guide/en/kibana/6.8/release-notes.html) +* [Kibana 5.x Release Notes](https://www.elastic.co/guide/en/kibana/5.6/release-notes.html) + +APM + +* [APM Release Notes](https://www.elastic.co/guide/en/apm/guide/current/release-notes.html) + +Enterprise Search + +* [Enterprise Search Release Notes](https://www.elastic.co/guide/en/enterprise-search/current/changelog.html) + diff --git a/deploy-manage/deploy/elastic-cloud/ech-working-with-elasticsearch.md b/deploy-manage/deploy/elastic-cloud/ech-working-with-elasticsearch.md new file mode 100644 index 000000000..4ca5d5406 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/ech-working-with-elasticsearch.md @@ -0,0 +1,144 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-working-with-elasticsearch.html +--- + +# Manage data from the command line [ech-working-with-elasticsearch] + +Learn how to index, update, retrieve, search, and delete documents in an {{es}} cluster from the command line. + +::::{tip} +If you are looking for a user interface for {{es}} and your data, head on over to [Kibana](ech-access-kibana.md)! Not only are there amazing visualization and index management tools, Kibana includes realistic sample data sets to play with so that you can get to know what you *could* do with your data. +:::: + + + +## Before you begin [echbefore_you_begin_2] + +To find out what the ELASTICSEARCH_URL is for your {{es}} cluster, grep on the output of the `heroku config` command for your app: + +```term +heroku config --app MY_APP | grep ELASTICSEARCH_URL +ELASTICSEARCH_URL: https://74f176887fdef36bb51e6e37nnnnnnnn.us-east-1.aws.found.io +``` + +These examples use the `elastic` user. If you didn’t copy down the password for the `elastic` user, you can [reset the password](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + +To use these examples, you also need to have the [curl](http://curl.haxx.se/) command installed. + + +## Indexing [echindexing] + +To index a document into {{es}}, `POST` your document: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc -XPOST -H 'Content-Type: application/json' -d '{ + "title": "One", "tags": ["ruby"] +}' +``` + +To show that the operation worked, {{es}} returns a JSON response that looks like `{"_index":"my_index","_type":"_doc","_id":"0KNPhW4BnhCSymaq_3SI","_version":1,"result":"created","_shards":{"total":2,"successful":2,"failed":0},"_seq_no":0,"_primary_term":1}`. + +In this example, the index `my_index` is created dynamically when the first document is inserted into it. All documents in {{es}} have a `type` and an `id`, which is echoed as `"_type":"_doc"` and `_id":"0KNPhW4BnhCSymaq_3SI` in the JSON response. If no ID is specified during indexing, a random `id` is generated. + + +### Bulk indexing [echbulk_indexing] + +To achieve the best possible performance, use the bulk API. + +To index some additional documents with the bulk API: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc/_bulk -XPOST -H 'Content-Type: application/json' -d ' +{"index": {}} +{"title": "Two", "tags": ["ruby", "python"] } +{"index": {}} +{"title": "Three", "tags": ["java"] } +{"index": {}} +{"title": "Four", "tags": ["ruby", "php"] } +' +``` + +Elasticsearch returns a JSON response similar to this one: + +```json +{"took":694,"errors":false,"items":[{"index":{"_index":"my_index","_type":"_doc","_id":"0aNqhW4BnhCSymaqFHQn","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"_seq_no":0,"_primary_term":1,"status":201}},{"index":{"_index":"my_index","_type":"_doc","_id":"0qNqhW4BnhCSymaqFHQn","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"_seq_no":1,"_primary_term":1,"status":201}},{"index":{"_index":"my_index","_type":"_doc","_id":"06NqhW4BnhCSymaqFHQn","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"_seq_no":2,"_primary_term":1,"status":201}}]} +``` + + +## Updating [echupdating] + +To update an existing document in {{es}}, `POST` the updated document to `http://ELASTICSEARCH_URL/my_index/_doc/ID`, where the ID is the `_id` of the document. + +For example, to update the last document indexed from the previous example with `"_id":"06NqhW4BnhCSymaqFHQn"`: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc/06NqhW4BnhCSymaqFHQn -XPOST -H 'Content-Type: application/json' -d '{ + "title": "Four updated", "tags": ["ruby", "php", "python"] +}' +``` + +The JSON response shows that the version counter for the document got incremented to `_version":2` to reflect the update. + + +## Retrieving documents [echretrieving_documents] + +To take a look at a specific document you indexed, here the last document we updated with the ID `0KNPhW4BnhCSymaq_3SI`: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc/06NqhW4BnhCSymaqFHQn +``` + +This request didn’t include `GET`, as the method is implied if you don’t specify anything else. If the document you are looking for exists, {{es}} returns `found":true` along with the document as part of the JSON response. Otherwise, the JSON response contains `"found":false`. + + +## Searching [echsearching] + +You issue search requests for documents with one of these {{es}} endpoints: + +```term +https://ELASTICSEARCH_URL/_search +https://ELASTICSEARCH_URL/INDEX_NAME/_search +``` + +Either a `GET` or a `POST` request with some URI search parameters works, or omit the method to default to `GET` request: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc/_search?q=title:T* +``` + +For an explanation of the allowed parameters, check [URI Search](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-uri-request.html). + +To make {{es}} return a more human readable JSON response, add `?pretty=true` to the request: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc/_search?pretty=true -H 'Content-Type: application/json' -d '{ + "query": { + "query_string": {"query": "*"} + } +}' +``` + +For performance reasons, `?pretty=true` is not recommended in production. You can verify the performance difference yourself by checking the `took` field in the JSON response which tells you how long Elasticsearch took to evaluate the search in milliseconds. When we tested these examples ourselves, the difference was `"took" : 4` against `"took" : 18`, a substantial difference. + +For a full explanation of how the request body is structured, check [Elasticsearch Request Body documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html). You can also execute multiple queries in one request with the [Multi Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html). + + +## Deleting [echdeleting] + +You delete documents from {{es}} by sending `DELETE` requests. + +To delete a single document by ID from an earlier example: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index/_doc/06NqhW4BnhCSymaqFHQn -XDELETE +``` + +To delete a whole index, here `my_index`: + +```term +curl -u USER:PASSWORD https://ELASTICSEARCH_URL/my_index -XDELETE +``` + +The JSON response returns `{"acknowledged":true}` to indicate that the index deletion was a success. + diff --git a/deploy-manage/deploy/elastic-cloud/echservice_status_api.md b/deploy-manage/deploy/elastic-cloud/echservice_status_api.md new file mode 100644 index 000000000..2161122fe --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/echservice_status_api.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/echservice_status_api.html +--- + +# Service Status API [echservice_status_api] + +If you want a more programmatical method of ingesting our Service Status updates, we also expose some API endpoints that you can avail of. + +For more information and to get started, go to our [Service Status API](https://status.elastic.co/api/) page. + diff --git a/deploy-manage/deploy/elastic-cloud/echsubscribe_to_individual_regionscomponents.md b/deploy-manage/deploy/elastic-cloud/echsubscribe_to_individual_regionscomponents.md new file mode 100644 index 000000000..b8f072d56 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/echsubscribe_to_individual_regionscomponents.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/echsubscribe_to_individual_regionscomponents.html +--- + +# Subscribe to Individual Regions/Components [echsubscribe_to_individual_regionscomponents] + +If you want to know about specific status updates, rather than all of them, you can adjust your preferences by using the following steps (this is used to both sign up a new email and adjust an existing subscription) . Go to the [Cloud Status](https://cloud-status.elastic.co/) page and select **SUBSCRIBE TO UPDATES**. . Enter your email address and click **SUBSCRIBE VIA EMAIL**. . You will be brought to a page with a list of Components + +Here you can either select all, select none, and customise as you require. This way, you’ll only be notified about the status updates that are important to you. + diff --git a/deploy-manage/deploy/elastic-cloud/edit-stack-settings.md b/deploy-manage/deploy/elastic-cloud/edit-stack-settings.md new file mode 100644 index 000000000..8208c90e5 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/edit-stack-settings.md @@ -0,0 +1,48 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html + - https://www.elastic.co/guide/en/cloud/current/ec-editing-user-settings.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-add-user-settings.html + - https://www.elastic.co/guide/en/cloud/current/ec-manage-kibana-settings.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-manage-kibana-settings.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-editing-user-settings.html + - https://www.elastic.co/guide/en/cloud/current/ec-manage-apm-settings.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-manage-apm-settings.html + - https://www.elastic.co/guide/en/cloud/current/ec-manage-appsearch-settings.html + - https://www.elastic.co/guide/en/cloud/current/ec-manage-enterprise-search-settings.html +--- + +# Edit stack settings + +% What needs to be done: Refine + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-add-user-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-editing-user-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-add-user-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-manage-kibana-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-manage-kibana-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-editing-user-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-manage-apm-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-manage-apm-settings.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-manage-appsearch-settings.md +% Notes: specify cluster 8.x or lower +% - [ ] ./raw-migrated-files/cloud/cloud/ec-manage-enterprise-search-settings.md +% Notes: specify cluster 8.x or lower + +$$$ec-add-user-settings$$$ + +$$$ech-es-elasticsearch-settings$$$ + +$$$xpack-monitoring-history-duration$$$ + +$$$ech-edit-apm-standalone-settings$$$ + +$$$ech-apm-settings$$$ + +$$$csp-strict$$$ + +$$$ec-appsearch-settings$$$ + +$$$ec-es-elasticsearch-settings$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/find-cloud-id.md b/deploy-manage/deploy/elastic-cloud/find-cloud-id.md new file mode 100644 index 000000000..1dceab74e --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/find-cloud-id.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html +--- + +# Find your Cloud ID [ec-cloud-id] + +The Cloud ID reduces the number of steps required to start sending data from Beats or Logstash to your hosted Elasticsearch cluster on Elasticsearch Service. Because we made it easier to send data, you can start exploring visualizations in Kibana on Elasticsearch Service that much more quickly. + +:::{image} ../../../images/cloud-ec-ce-cloud-id-beats-logstash.png +:alt: Exploring data from Beats or Logstash in Kibana after sending it to a hosted Elasticsearch cluster +::: + +The Cloud ID works by assigning a unique ID to your hosted Elasticsearch cluster on Elasticsearch Service. All deployments automatically get a Cloud ID. + +You include your Cloud ID along with your Elasticsearch Service user credentials (defined in `cloud.auth`) when you run Beats or Logstash locally, and then let Elasticsearch Service handle all of the remaining connection details to send the data to your hosted cluster on Elasticsearch Service safely and securely. + +:::{image} ../../../images/cloud-ec-ce-cloud-id.png +:alt: The Cloud ID and `elastic` user information shown when you create a deployment +::: + + +## What are Beats and Logstash? [ec_what_are_beats_and_logstash] + +Not sure why you need Beats or Logstash? Here’s what they do: + +* [Beats](https://www.elastic.co/products/beats) is our open source platform for single-purpose data shippers. The purpose of Beats is to help you gather data from different sources and to centralize the data by shipping it to Elasticsearch. Beats install as lightweight agents and ship data from hundreds or thousands of machines to your hosted Elasticsearch cluster on Elasticsearch Service. If you want more processing muscle, Beats can also ship to Logstash for transformation and parsing before the data gets stored in Elasticsearch. +* [Logstash](https://www.elastic.co/products/logstash) is an open source, server-side data processing pipeline that ingests data from a multitude of sources simultaneously, transforms it, and then sends it to your favorite place where you stash things, here your hosted Elasticsearch cluster on Elasticsearch Service. Logstash supports a variety of inputs that pull in events from a multitude of common sources — logs, metrics, web applications, data stores, and various AWS services — all in continuous, streaming fashion. + + +## Before you begin [ec_before_you_begin_3] + +To use the Cloud ID, you need: + +* A deployment with an Elasticsearch cluster to send data to. +* Beats or Logstash, installed locally wherever you want to send data from. +* To configure Beats or Logstash, you need: + + * The unique Cloud ID for your deployment, available from the deployment overview page. + * A user ID and password that has permission to send data to your cluster. + + In our examples, we use the `elastic` superuser that every Elasticsearch cluster comes with. The password for the `elastic` user is provided when you create a deployment (and can also be [reset](../../users-roles/cluster-or-deployment-auth/built-in-users.md) if you forget it). On a production system, you should adapt these examples by creating a user that can write to and access only the minimally required indices. For each Beat, review the specific feature and role table, similar to the one in [Metricbeat](https://www.elastic.co/guide/en/beats/metricbeat/current/feature-roles.html) documentation. + + + +## Configure Beats with your Cloud ID [ec-cloud-id-beats] + +The following example shows how you can send operational data from Metricbeat to Elasticsearch Service by using the Cloud ID. Any of the available Beats will work, but we had to pick one for this example. + +::::{tip} +For others, you can learn more about [getting started](https://www.elastic.co/guide/en/beats/libbeat/current/getting-started.html) with each Beat. +:::: + + +To get started with Metricbeat and Elasticsearch Service: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. [Create a new deployment](create-an-elastic-cloud-hosted-deployment.md) and copy down the password for the `elastic` user. +3. On the deployment overview page, copy down the Cloud ID. +4. Set up the Beat of your choice, such as [Metricbeat version 7.17](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-installation-configuration.html). +5. [Configure the Beat output to send to Elastic Cloud](https://www.elastic.co/guide/en/beats/metricbeat/current/configure-cloud-id.html). + + ::::{note} + Make sure you replace the values for `cloud.id` and `cloud.auth` with your own information. + :::: + +6. Open Kibana and explore! + +Metricbeat creates a data view (formerly *index pattern*) with defined fields, searches, visualizations, and dashboards that you can start exploring in Kibana. Look for information related to system metrics, such as CPU usage, utilization rates for memory and disk, and details for processes. + diff --git a/deploy-manage/deploy/elastic-cloud/google-cloud-platform-marketplace.md b/deploy-manage/deploy/elastic-cloud/google-cloud-platform-marketplace.md new file mode 100644 index 000000000..33c5f5b46 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/google-cloud-platform-marketplace.md @@ -0,0 +1,72 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-billing-gcp.html +--- + +# Google Cloud Platform Marketplace [ec-billing-gcp] + +Subscribe to Elasticsearch Service directly from the Google Cloud Platform (GCP). You then have the convenience of viewing your Elasticsearch Service subscription as part of your GCP bill, and you do not have to supply any additional credit card information to Elastic. + +Some differences exist when you subscribe to Elasticsearch Service through the GCP Marketplace: + +* There is no trial period. Billing starts when you subscribe to Elasticsearch Service. +* Existing Elasticsearch Service organizations cannot be converted to use the GCP Marketplace. +* Pricing for an Elasticsearch Service subscription through the GCP Marketplace follows the pricing outlined on the [Elasticsearch Service on Elastic Cloud](https://console.cloud.google.com/marketplace/product/endpoints/elasticsearch-service.gcpmarketplace.elastic.co) page in the GCP Marketplace. Pricing is based the Elastic Cloud [Billing Dimensions](../../cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.md). +* To access your billing information at any time go to **Account & Billing**. You can also go to **Account & Billing** and then **Usage** to view your usage hours and units per hour. + +::::{important} +Only one Elasticsearch Service organization can be subscribed through GCP Marketplace per GCP billing account. +:::: + + +To subscribe to Elasticsearch Service through the GCP Marketplace: + +1. Log in to your Google Cloud Platform account. +2. Go to the [Elastic Cloud (Elasticsearch Service)](https://console.cloud.google.com/marketplace/product/elastic-prod/elastic-cloud) page in the GCP Marketplace. +3. On the Elastic Cloud page select **Subscribe**, where you will be directed to another page. There is only one plan—the Elastic plan—and it’s pre-selected. The billing account you are logged into will be pre-selected for this purchase, though you can change it at this time. +4. Accept the terms of service (TOS) and select **Subscribe**. +5. When you are presented with a pop-up that specifies that "Your order request has been sent to Elastic" choose **Sign up with Elastic** to continue. +6. After choosing to sign up, a new window will appear. Do one of the following: + + * Create a new, unique user account for an Elasticsearch Service Elastic Cloud organization. + * Log in with an existing user account that’s associated with an Elastic Cloud trial. This links the billing account used for the purchase on GCP Marketplace to the existing Elastic organization. + +7. After signing up, check your inbox to verify the email address you signed up with. Upon verification, you will be asked to create a password, and once created your organization will be set up and you will be logged into it. + + ::::{note} + Immediately after your first login to Elastic Cloud you may briefly see a banner on the Elastic Cloud user console saying that your account is disconnected. There is sometimes a short delay in activation, but refreshing the page is generally enough time to allow its completion. If this issue persists, please contact support. + :::: + + + You are ready to [create your first deployment](create-an-elastic-cloud-hosted-deployment.md). + + +If you have existing deployments that you want to migrate to your new marketplace account, we recommend using a custom repository to take a snapshot. Then restore that snapshot to a new deployment in your new marketplace account. Check [Snapshot and restore with custom repositories](../../tools/snapshot-and-restore/elastic-cloud-hosted.md) for details. + +::::{tip} +Your new account is automatically subscribed to the Enterprise subscription level. You can [change your subscription level](../../cloud-organization/billing/manage-subscription.md). +:::: + + + +## Changes to your Billing Account [ec-billing-gcp-account-change] + +::::{important} +To prevent downtime, do not remove the currently used billing account before the switch to the new billing account has been confirmed by Elastic. +:::: + + +Elasticsearch Service subscriptions through GCP Marketplace are associated with a GCP billing account. In order to change the billing account associated with an Elasticsearch Service organization: + +* for customers under a Private Offer contract: please reach out to Elastic support and provide the GCP Billing Account, as well as the contact of any reseller information for approval. +* for pay-as-you-go customers: you need to have purchased and subscribed to Elastic Cloud on the new billing account using the details above—but do not create a new Elastic user or organization (that is, you can skip Steps 5 and 6 in the subscription instructions, above). Once you successfully subscribed with the new billing account, you can contact Elastic support and provide the new billing account ID you wish to move to, which you can find from [GCP’s billing page](https://console.cloud.google.com/billing). The ID is in the format `000000-000000-000000`. + +If you cancel your Elasticsearch Service order on GCP through the [marketplace orders page](https://console.cloud.google.com/marketplace/orders) before the switch to the new billing account has been done, any running deployments will immediately enter a degraded state known as maintenance mode and they will be scheduled for termination in five days. + +If you already unsubscribed before the new billing account has been set up, you can subscribe again from the previously used billing account, which will cancel the termination and restore the deployments to a functional state. + + +## Native GCP integrations [ec-gcp-marketplace-native] + +You can ingest data from Google Pub/Sub to the Elastic Stack very easily from the Google Cloud Console. You can use the [Metricbeat Google Cloud Platform module](../../../solutions/observability/cloud/monitor-google-cloud-platform-gcp.md) or the [GCP Dataflow Templates](../../../solutions/observability/cloud/gcp-dataflow-templates.md). + diff --git a/deploy-manage/deploy/elastic-cloud/heroku.md b/deploy-manage/deploy/elastic-cloud/heroku.md new file mode 100644 index 000000000..e5b337984 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/heroku.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-getting-started.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-about.html +--- + +# Heroku + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/336 + +% Scope notes: Refactor this documentation to make it as minimal as possible, working with marketplaces team + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-getting-started.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-about.md \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/keep-track-of-deployment-activity.md b/deploy-manage/deploy/elastic-cloud/keep-track-of-deployment-activity.md new file mode 100644 index 000000000..f16dc754e --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/keep-track-of-deployment-activity.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-activity-page.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-activity-page.html +--- + +# Keep track of deployment activity + +% What needs to be done: Lift-and-shift + +% Scope notes: This belongs here or in Maintenance. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-activity-page.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-activity-page.md \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/manage-deployments-using-elastic-cloud-api.md b/deploy-manage/deploy/elastic-cloud/manage-deployments-using-elastic-cloud-api.md new file mode 100644 index 000000000..7ec769046 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/manage-deployments-using-elastic-cloud-api.md @@ -0,0 +1,379 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-api-deployment-crud.html +--- + +# Manage deployments using the Elastic Cloud API [ec-api-deployment-crud] + +The following examples demonstrate Create, Read, Update and Delete operations on a `deployments` resource. If you haven’t created an API Key yet, you can follow the [Authentication documentation](../../api-keys/elastic-cloud-api-keys.md). + + +## Listing your deployments [ec_listing_your_deployments] + +List the details about all of your Elasticsearch Service deployments. + +```sh +curl \ +-H "Authorization: ApiKey $EC_API_KEY" \ +https://api.elastic-cloud.com/api/v1/deployments +``` + + +## Getting details about a particular deployment [ec_getting_details_about_a_particular_deployment] + +List the details about a particular deployment identified by `id`. + +```sh +curl \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID" +``` + + +## Using the API to create your first deployment [ec_using_the_api_to_create_your_first_deployment] + +When you create a new deployment through the API, you have two options: + +1. **Use default values.** The simplest option is to create the deployment using a set of default values that are gathered automatically from a deployment template specified in the API request. +2. **Configure the deployment settings manually.** With this option, the API request to create a new deployment is very descriptive, with many settings to tweak. If you use this option we recommend that you configure your desired deployment in the Elastic Cloud UI and copy the JSON payload. + + +### Create a deployment using default values [ec-api-examples-deployment-simple] + +This example requires minimal information in the API payload, and creates a deployment with default settings and a default name. You just need to specify one of the [available deployment templates](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) in your API request header and the deployment is created using default settings from that template. + +```sh +curl -XPOST \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments?template_id=gcp-general-purpose" \ +-d ' +{ + "version": "8.17.1",<1> + "region": "gcp-europe-west1"<2> +} +' +``` + +1. Optional: You can specify a version for the deployment. If this field is omitted a default version is used. +2. Required: One of the [available regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) must be provided in the request. + + +A `resource` field can be included in this request (check the following, manual example for the field details). When a `resource` is present, the content of the request is used instead of any default values provided by the the deployment template. + + +### Create a deployment [ec_create_a_deployment] + +This example creates a new deployment named "my-first-api-deployment" with the following characteristics: + +* Version 8.17.1 of the Elastic Stack +* Elasticsearch cluster in two zones with 4 GB of memory for each node +* 1 GB single zone Kibana instance, 1 GB Integrations Server instance, and 2GB Enterprise Search instance + +```sh +curl -XPOST \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments" \ +-d ' +{ + "resources": { + "elasticsearch": [ + { + "region": "gcp-us-central1", <1> + "ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + { + "zone_count": 2, <2> + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "instance_configuration_id": "gcp.es.datahot.n2.68x16x45", <3> + "node_roles": [ + "master", + "ingest", + "transform", + "data_hot", + "remote_cluster_client", + "data_content" + ], + "id": "hot_content", + "size": { + "value": 4096, <4> + "resource": "memory" + } + }, + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "instance_configuration_id": "gcp.es.datawarm.n2.68x10x190", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "id": "warm", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "instance_configuration_id": "gcp.es.datacold.n2.68x10x190", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "id": "cold", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "instance_configuration_id": "gcp.es.datafrozen.n2.68x10x95", + "node_roles": [ + "data_frozen" + ], + "id": "frozen", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 3, + "instance_configuration_id": "gcp.es.master.n2.68x32x45", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "id": "master", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 2, + "instance_configuration_id": "gcp.es.coordinating.n2.68x16x45", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "id": "coordinating", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "instance_configuration_id": "gcp.es.ml.n2.68x32x45", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "id": "ml", + "size": { + "resource": "memory", + "value": 0 + } + } + ], + "elasticsearch": { + "version": "8.17.1", + "enabled_built_in_plugins": [] + }, + "deployment_template": { + "id": "gcp-general-purpose-v3" <5> + } + } + } + ], + "kibana": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-central1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.kibana.n2.68x32x45", + "zone_count": 1, <6> + "size": { + "resource": "memory", + "value": 1024 <7> + } + } + ], + "kibana": { + "version": "8.17.1" + } + }, + "ref_id": "main-kibana" + } + ], + "integrations_server": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-central1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.integrationsserver.n2.68x32x45", + "zone_count": 1, <8> + "size": { + "resource": "memory", + "value": 1024 <9> + } + } + ], + "integrations_server": { + "version": "8.17.1" + } + }, + "ref_id": "main-integrations_server" + } + ], + "enterprise_search": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-central1", + "plan": { + "cluster_topology": [ + { + "node_type": { + "connector": true, + "appserver": true, + "worker": true + }, + "instance_configuration_id": "gcp.enterprisesearch.n2.68x32x45", + "zone_count": 1, <10> + "size": { + "resource": "memory", + "value": 2048 <11> + } + } + ], + "enterprise_search": { + "version": "8.17.1" + } + }, + "ref_id": "main-enterprise_search" + } + ] + }, + "name": "my-first-api-deployment" +} +' +``` + +1. [Available Regions](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) +2. Availability zones for the Elasticsearch cluster +3. [Available instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) +4. Memory allocated for each Elasticsearch node +5. [Available templates](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) +6. Availability zones for Kibana +7. Memory allocated for Kibana +8. Availability zones for Integrations Server +9. Memory allocated for Integrations Server +10. Availability zones for Enterprise Search +11. Memory allocated for Enterprise Search + + +::::{tip} +You can get the payload easily from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) **Create Deployment** page, customize the regions, zones, memory allocated for each components, and then select **Equivalent API request**. +:::: + + + +## Using the API to create deployment with non EOL versions [ec_using_the_api_to_create_deployment_with_non_eol_versions] + +You are able to create deployments with *non* [End-of-life (EOL) versions](available-stack-versions.md#ec-version-policy-eol) via API, which are not selectable in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) UI. You can simply replace the version number in the above example. + + +## Update a deployment [ec_update_a_deployment] + +Modify the Elasticsearch resource by increasing the amount of memory to 8 GB. + +```sh +curl -XPUT \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID" \ +-d ' +{ + "name": "my-first-api-deployment-with-new-name", <1> + "prune_orphans": false, + "resources": { + "elasticsearch": [ + { + "region": "gcp-us-central1", + "ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "instance_configuration_id": "gcp.es.datahot.n2.68x16x45", + "node_roles": [ + "data_hot", + "data_content", + "master", + "ingest", + "remote_cluster_client", + "transform" + ], + "id": "hot_content", + "size": { + "value": 8192, <2> + "resource": "memory" + } + } + ], + "elasticsearch": { + "version": "8.17.1" + }, + "deployment_template": { + "id": "gcp-general-purpose-v3" + } + } + } + ] + } +} +' +``` + +1. Give the deployment a new name +2. Increase the amount of memory allocated for each Elasticsearch node to 8 GB + + +::::{tip} +You can get the payload easily from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) deployment **Edit** page, customize the zone count, memory allocated for each components, and then select **Equivalent API request**. +:::: + + +A 200 status code means that the configuration change was accepted. diff --git a/deploy-manage/deploy/elastic-cloud/manage-deployments.md b/deploy-manage/deploy/elastic-cloud/manage-deployments.md new file mode 100644 index 000000000..2bf452927 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/manage-deployments.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-manage-deployment.html +--- + +# Manage deployments [ec-manage-deployment] + +Sometimes you might need to make changes to the entire deployment, a specific component, or just a single data tier. + +* Make adjustments to specific deployment components, such as an [Integrations Server](manage-integrations-server.md), [APM & Fleet Server](switch-from-apm-to-integrations-server-payload.md#ec-manage-apm-and-fleet), [Enterprise Search](https://www.elastic.co/guide/en/cloud/current/ec-enable-enterprise-search.html), [Watcher](../../../explore-analyze/alerts/watcher.md), or [Kibana](access-kibana.md#ec-enable-kibana2). +* [Enable logging and monitoring](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) of the deployment performance. +* [Disable a data tier](../../../manage-data/lifecycle/index-lifecycle-management.md). +* [Restart](../../maintenance/start-stop-services/restart-cloud-hosted-deployment.md), [stop routing](../../maintenance/ece/start-stop-routing-requests.md), or [delete your deployment](../../uninstall/delete-a-cloud-deployment.md). +* [Upgrade the Elastic Stack version](../../upgrade/deployment-or-cluster.md) for the deployment. + + + + + + + + + diff --git a/deploy-manage/deploy/elastic-cloud/manage-integrations-server.md b/deploy-manage/deploy/elastic-cloud/manage-integrations-server.md new file mode 100644 index 000000000..4082a1208 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/manage-integrations-server.md @@ -0,0 +1,254 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-manage-integrations-server.html +--- + +# Manage your Integrations server [ec-manage-integrations-server] + +For deployments that are version 8.0 and later, you have the option to add a combined [Application Performance Monitoring (APM) Server](https://www.elastic.co/guide/en/apm/guide/current/apm-overview.html) and [Fleet Server](https://www.elastic.co/guide/en/fleet/current/fleet-overview.html) to your deployment. APM allows you to monitor software services and applications in real time, turning that data into documents stored in the Elasticsearch cluster. Fleet allows you to centrally manage Elastic Agents on many hosts. + +As part of provisioning, the APM Server and Fleet Server are already configured to work with Elasticsearch and Kibana. At the end of provisioning, you are shown the secret token to configure communication between the APM Server and the backend [APM Agents](https://www.elastic.co/guide/en/apm/agent/index.html). The APM Agents get deployed within your services and applications. + +From the deployment **Integrations Server** page you can also: + +* Get the URL to complete the APM agent configuration. +* Use the `elastic` credentials to go to the APM area of Kibana. Step by step instructions to configure a variety of agents are available right in Kibana. After that, you can use the pre-built, dedicated dashboards and the APM tab to visualize the data that is sent back from the APM Agents. +* Use the `elastic` credentials to go to the Fleet area of Kibana. Step by step instructions to download and install Elastic Agent on your hosts are available right in Kibana. After that, you can manage enrolled Elastic Agents on the **Agents** tab, and the data shipped back from those Elastic Agents on the **Data streams** tab. +* Access the Integrations Server logs and metrics. +* Stop and restart your Integrations Server. +* Upgrade your Integrations Server version if it is out of sync with your Elasticsearch cluster. +* Fully remove the Integrations Server, delete it from the disk, and stop the charges. + +::::{important} +The APM secret token can no longer be reset from the Elasticsearch Service UI. Check [Secret token](https://www.elastic.co/guide/en/apm/guide/current/secret-token.html) for instructions on managing a secret token. Note that resetting the token disrupts your APM service and restarts the server. When the server restarts, you’ll need to update all of your agents with the new token. +:::: + + +## Enable Integrations Server through the API [ec-integrations-server-api-example] + +This example demonstrates how to use the Elasticsearch Service RESTful API to create a deployment with Integrations Server enabled. + +For more information on how to manage Integrations Server from the UI, check [Manage your Integrations Server]() + + +#### Requirements [ec_requirements_2] + +Integrations Server can be enabled only on new deployments, starting with Elastic Stack version 8.0. + +It’s possible to enable Integrations Server on an existing deployment with version 8.0 only if [APM & Fleet Server](switch-from-apm-to-integrations-server-payload.md#ec-manage-apm-and-fleet) hasn’t been previously enabled on the deployment. + + +#### API request example [ec_api_request_example_2] + +Run this example API request to create a deployment with Integrations Server: + + +```sh +curl -XPOST \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments" \ +-d ' +{ + "resources": { + "elasticsearch": [ + { + "region": "eu-west-1", + "settings": { + "dedicated_masters_threshold": 6 + }, + "plan": { + "autoscaling_enabled": false, + "cluster_topology": [ + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "hot" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.es.datahot.i3", + "node_roles": [ + "master", + "ingest", + "transform", + "data_hot", + "remote_cluster_client", + "data_content" + ], + "id": "hot_content", + "size": { + "resource": "memory", + "value": 8192 + } + }, + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "warm" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.es.datawarm.d3", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "id": "warm", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.es.datacold.d3", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "id": "cold", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "aws.es.datafrozen.i3en", + "node_roles": [ + "data_frozen" + ], + "id": "frozen", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 3, + "instance_configuration_id": "aws.es.master.c5d", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "id": "master", + "size": { + "resource": "memory", + "value": 0 + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "zone_count": 2, + "instance_configuration_id": "aws.es.coordinating.m5d", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "id": "coordinating", + "size": { + "resource": "memory", + "value": 0 + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "zone_count": 1, + "instance_configuration_id": "aws.es.ml.m5d", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "id": "ml", + "size": { + "resource": "memory", + "value": 0 + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + } + ], + "elasticsearch": { + "version": "8.0.0" + }, + "deployment_template": { + "id": "aws-storage-optimized" + } + }, + "ref_id": "main-elasticsearch" + } + ], + "kibana": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "eu-west-1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "aws.kibana.c5d", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "kibana": { + "version": "8.0.0" + } + }, + "ref_id": "main-kibana" + } + ], + "integrations_server": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "eu-west-1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "aws.integrations_server.c5d", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "integrations_server": { + "version": "8.0.0" + } + }, + "ref_id": "main-integrations_server" + } + ] + }, + "name": "My deployment", + "metadata": { + "system_owned": false + } +} +' +``` + + diff --git a/deploy-manage/deploy/elastic-cloud/manage-plugins-extensions-through-api.md b/deploy-manage/deploy/elastic-cloud/manage-plugins-extensions-through-api.md new file mode 100644 index 000000000..aa430c804 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/manage-plugins-extensions-through-api.md @@ -0,0 +1,498 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-plugins-guide.html +--- + +# Manage plugins and extensions through the API [ec-plugins-guide] + +This guide provides a full list of tasks for managing [plugins and extensions](add-plugins-extensions.md) in Elasticsearch Service, using the API. + +* [Create an extension](#ec-extension-guide-create) +* [Add an extension to a deployment plan](#ec-extension-guide-add-plan) +* [Get an extension](#ec-extension-guide-get-extension) +* [Update the name of an existing extension](#ec-extension-guide-update-name) +* [Update the type of an existing extension](#ec-extension-guide-update-type) +* [Update the version of an existing bundle](#ec-extension-guide-update-version-bundle) +* [Update the version of an existing plugin](#ec-extension-guide-update-version-plugin) +* [Update the file associated to an existing extension](#ec-extension-guide-update-file) +* [Upgrade Elasticsearch](#ec-extension-guide-upgrade-elasticsearch) +* [Delete an extension](#ec-extension-guide-delete) + + +## Create an extension [ec-extension-guide-create] + +There are two methods to create an extension. You can: + +1. Stream the file from a publicly-accessible download URL. +2. Upload the file from a local file path. + +::::{note} +For plugins larger than 200MB the download URL option **must** be used. Plugins larger than 8GB cannot be uploaded with either method. +:::: + + +These two examples are for the `plugin` extension type. For bundles, change `extension_type` to `bundle`. + +For plugins, `version` must match (exactly) the `elasticsearch.version` field defined in the plugin’s `plugin-descriptor.properties` file. Check [Help for plugin authors](https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugin-authors.html#plugin-authors) for details. For plugins larger than 5GB, the `plugin-descriptor.properties` file needs to be at the top of the archive. This ensures that the our verification process is able to detect that it is an Elasticsearch plugin; otherwise the plugin will be rejected by the API. This order can be achieved by specifying at time of creating the ZIP file: `zip -r name-of-plugin.zip plugin-descriptor.properties *`. + +For bundles, we recommend setting `version` using wildcard notation that matches the major version of the Elasticsearch deployment. For example, if Elasticsearch is on version 8.4.3, simply set `8.*` as the version. The value `8.*` means that the bundle is compatible with all 8.x versions of Elasticsearch. + +$$$ec-extension-guide-create-option1$$$ +**Option 1: Stream the file from a publicly-accessible download URL** + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "download_url" : "https://my_site/custom-plugin-8.4.3.zip", + "extension_type" : "plugin", + "name" : "custom-plugin", + "version" : "8.4.3" +}' +``` + +The single POST request creates an extension with the metadata, validates, and streams the file from the `download_url` specified. The accepted protocols for `download_url` are `http` and `https`. + +::::{note} +The `download_url` must be directly and publicly accessible. There is currently no support for redirection or authentication unless it contains security credentials/tokens expected by your HTTP service as part of the URL. Otherwise, use the following Option 2 to upload the file from a local path. +:::: + + +::::{note} +When the file is larger than 5GB, the request may timeout after 2-5 minutes, but streaming will continue on the server. Check the Extensions page in the Cloud UI after 5-10 minutes to make sure that the plugin has been created. A successfully created plugin will contain correct name, type, version, size, and last modified information. +:::: + + +$$$ec-extension-guide-create-option2$$$ +**Option 2: Upload the file from a local file path** + +This option requires a two step process. First, create the metadata for the extension: + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "extension_type": "plugin", + "name": "custom-plugin", + "version" : "8.4.3" +}' +``` + +```sh +{ + "url": "repo://4226448541", + "version": "8.4.3", + "extension_type": "plugin", + "id": "4226448541", + "name": "custom-plugin" +} +``` + +The response returns a `url` you can reference later in the plan (the numeric value in the `url` is the `EXTENSION_ID`). Use this `EXTENSION_ID` in the following PUT call: + +```sh +curl -v -X PUT "https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID" \ +-H 'Content-type:application/zip' \ +-H "Authorization: ApiKey $CLOUD_API_KEY" \ +-H 'Expect:' \ +-T "/path_to/custom-plugin-8.4.3.zip" +``` + +::::{note} +When using curl, always use the `-T` option. DO NOT use `-F` (we have seen inconsistency in curl behavior across systems; using `-F` can result in partially uploaded or truncated files). +:::: + + +The above PUT request uploads the file from the local path specified. This request is synchronous. An HTTP 200 response indicates that the file has been successfully uploaded and is ready for use. + +```sh +{ + "url": "repo://2286113333", + "version": "8.4.3", + "extension_type": "plugin", + "id": "2286113333", + "name": "custom-plugin" +} +``` + + +## Add an extension to a deployment plan [ec-extension-guide-add-plan] + +Once the extension is created and uploaded, you can add the extension using its `EXTENSION_ID` in an [update deployment API call](https://www.elastic.co/docs/api/doc/cloud/operation/operation-update-deployment). + +The following are examples of a GCP plan. Your specific deployment plan will be different. The important parts related to extensions are in the `user_plugins` object. + +```sh +{ + "name": "Extensions", + "prune_orphans": false, + "resources": { + "elasticsearch": [ + { + "region": "gcp-us-central1", + "ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + + ... + + ], + "elasticsearch": { + "version": "8.4.3", + "enabled_built_in_plugins": [ ], + "user_bundles": [ + { + "name": "custom-plugin", + "url": "repo://2286113333", + "elasticsearch_version": "8.4.3" + } + ] + }, + "deployment_template": { + "id": "gcp-storage-optimized-v3" + } + } + } + ] + } +} +``` + +You can use the [cat plugins API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-plugins.html) to confirm that the plugin has been deployed successfully to Elasticsearch. + +The previous examples are for plugins. For bundles, use the `user_bundles` construct instead. + +```sh + "user_bundles": [ + { + "elasticsearch_version": "8.*", + "name": "custom-bundle", + "url": "repo://5886113212" + } + ] +``` + + +## Get an extension [ec-extension-guide-get-extension] + +You can use the GET call to retrieve information about an extension. + +To list all extensions for the account: + +```sh +curl -X GET \ + https://api.elastic-cloud.com/api/v1/deployments/extensions \ + -H 'Content-Type: application/json' \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ +``` + +To get a specific extension: + +```sh +curl -X GET \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ +``` + +The previous GET calls support an optional `include_deployments` parameter. When set to `true`, the call also returns the deployments that currently have the extension in-use: + +```sh +curl -X GET \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID?include_deployments=true \ + -H 'Content-Type: application/json' \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ +``` + +For example, the previous call returns: + +```sh +{ + "name": "custom-plugin", + "url": "repo://2286113333", + "extension_type": "plugin", + "deployments": [ + "f91f3a9360a74e9d8c068cd2698c92ea" + ], + "version": "8.4.3", + "id": "2286113333" +} +``` + + +## Update the name of an existing extension [ec-extension-guide-update-name] + +To update the name of an existing extension, simply update the name field without uploading a new file. You do not have to specify the `download_url` when only making metadata changes to an extension. + +Example using the [Option 1](#ec-extension-guide-create-option1) create an extension method: + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "extension_type" : "plugin", + "name": "custom-plugin-07012020", + "version" : "8.4.3" +}' +``` + +Example using the [Option 2](#ec-extension-guide-create-option2) create an extension method: + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "extension_type" : "plugin", + "name": "custom-plugin-07012020", + "version" : "8.4.3" +}' +``` + +Updating the name of an existing extension does not change its `EXTENSION_ID`. + + +## Update the type of an existing extension [ec-extension-guide-update-type] + +Updating `extension_type` has no effect. You cannot change the extension’s type (`plugin` versus `bundle`) after the initial creation of a plugin. + + +## Update the version of an existing bundle [ec-extension-guide-update-version-bundle] + +For bundles, we recommend setting `version` using wildcard notation that matches the major version of the Elasticsearch deployment. For example, if Elasticsearch is on version 8.4.3, simply set `8.*` as the version. The value `8.*` means that the bundle is compatible with all 7.x versions of Elasticsearch. + +For example, if the bundle was previously uploaded with the version `8.4.2`, simply update the version field. You no longer have to specify the `download_url` when only making metadata changes to a bundle. + +Example using the [Option 1](#ec-extension-guide-create-option1) create an extension method: + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "extension_type" : "bundle", + "name": "custom-bundle", + "version" : "8.*" +}' +``` + +Example using the [Option 2](#ec-extension-guide-create-option2) create an extension method: + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "extension_type" : "bundle", + "name": "custom-bundle", + "version" : "8.*" +}' +``` + +Updating the name of an existing extension does not change its `EXTENSION_ID`. + + +## Update the version of an existing plugin [ec-extension-guide-update-version-plugin] + +For plugins, `version` must match (exactly) the `elasticsearch.version` field defined in the plugin’s `plugin-descriptor.properties` file. Check [Help for plugin authors](https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugin-authors.html#plugin-authors) for details. If you change the version, the associated plugin file *must* also be updated accordingly. + + +## Update the file associated to an existing extension [ec-extension-guide-update-file] + +You may want to update an uploaded file for an existing extension without performing an Elasticsearch upgrade. If you are updating the extension to prepare for an Elasticsearch upgrade, check the [Upgrade Elasticsearch](#ec-extension-guide-upgrade-elasticsearch) scenario later on this page. + +This example is for the `plugin` extension type. For bundles, change `extension_type` to `bundle`. + +If you used [Option 1](#ec-extension-guide-create-option1) to create the extension, simply re-run the POST request with the `download_url` pointing to the location of your updated extension file. + +```sh +curl -X POST \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "download_url" : "https://my_site/custom-plugin-8.4.3-10212022.zip", + "extension_type" : "plugin", + "name": "custom-plugin-10212022", + "version" : "8.4.3" +}' +``` + +If you used [Option 2](#ec-extension-guide-create-option2) to create the extension, simply re-run the PUT request with the `file` parameter pointing to the location of your updated extension file. + +```sh +curl -v -X PUT "https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID" \ +-H 'Content-type:application/zip' \ +-H "Authorization: ApiKey $CLOUD_API_KEY" \ +-H 'Expect:' \ +-T "/path_to/custom-plugin-8.4.3-10212022.zip" +``` + +::::{important} +If you are not making any other plan changes and simply updating an extension file, you need to issue a no-op plan so that Elasticsearch will make use of this new file. A *no-op* (no operation) plan triggers a rolling restart on the deployment, applying the same (unchanged) plan as the current plan. +:::: + + +Updating the file of an existing extension or bundle does not change its `EXTENSION_ID`. + + +## Upgrade Elasticsearch [ec-extension-guide-upgrade-elasticsearch] + +When you upgrade Elasticsearch in a deployment, you must ensure that: + +* Bundles are on versions that are compatible with the Elasticsearch version that you are upgrading to. +* Plugins match (exactly) the Elasticsearch upgrade version. + +**To prepare existing bundle and update the plan:** + +1. **Update the bundle version to be compatible with the Elasticsearch upgrade version.** + + Bundles using wildcard notation for versions (for example, `7.*`, `8.*`) in their extension metadata are compatible with all minor versions of the same Elasticsearch major version. In other words, if you are performing a patch (for example, from `8.4.2` to `8.4.3`) or a minor (for example `8.3.0` to `8.4.3`) version upgrade of Elasticsearch and you are already using `8.*` as the `version` for the extension, you are ready for the Elasticsearch upgrade and can proceed to Step 2. + + However, if you are using a specific `version` for bundles, or upgrading to a major version, you must update the metadata of the extension to specify the matching Elasticsearch `version` that you are upgrading to, or use the wildcard syntax described in the previous paragraph. For example, if you are upgrading from version 7.x to 8.x, set `version` to `8.*` before the upgrade. Refer to [Update the version of an existing bundle](#ec-extension-guide-update-version-bundle). + +2. **Update the bundle reference as part of an upgrade plan.** + + Submit a plan change that performs the following operations in a *single* [update deployment API](https://www.elastic.co/docs/api/doc/cloud/operation/operation-update-deployment) call: + + * Upgrade the version of Elasticsearch to the upgrade version (for example, `8.4.3`). + * Update reference to the existing bundle to be compatible with Elasticsearch upgrade version (for example, `8.*`). + + This triggers a rolling upgrade plan change to the later Elasticsearch version and updates the reference to the bundle at the same time. + + The following example shows the upgrade of an Elasticsearch deployment and its bundle. You can also upgrade other deployment resources within the same plan change. + + Update `resources.elasticsearch.plan.elasticsearch.version` and `resources.elasticsearch.plan.cluster_topology.elasticsearch.user_bundles.elasticsearch_version` accordingly. + + ```sh + { + "name": "Extensions", + "prune_orphans": false, + "resources": { + "elasticsearch": [ + { + "region": "gcp-us-central1", + "ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + ... + ], + "elasticsearch": { + "version": "8.4.3", + "enabled_built_in_plugins": [], + "user_bundles": [ + { + "elasticsearch_version": "7.*", + "name": "custom-bundle", + "url": "repo://5886113212" + } + ] + + }, + "deployment_template": { + "id": "gcp-storage-optimized-v3" + } + } + } + ] + } + } + ``` + + +**To create a new plugin and update the plan:** + +Unlike bundles, plugins *must* match the Elasticsearch version down to the patch level (for example, `8.4.3`). When upgrading Elasticsearch to a new patch, minor, or major version, update the version in the extension metadata and update the extension file. The following example updates an existing plugin and upgrades the Elasticsearch deployment from version 8.3.0 to 8.4.3. + +1. **Create a new plugin that matches the Elasticsearch upgrade version.** + + Follow the steps in [Get an extension](#ec-extension-guide-get-extension) to create a new extension with a `version` metadata field and the plugin’s `elasticsearch.version` field in `plugin-descriptor.properties` that matches the Elasticsearch upgrade version (for example, `8.4.3`). + +2. **Remove the old plugin and add the new plugin to the upgrade plan.** + + Submit a plan change that performs the following operations in a *single* [update deployment API](https://www.elastic.co/docs/api/doc/cloud/operation/operation-update-deployment) call: + + * Upgrade the version of Elasticsearch to the upgrade version (for example, `8.4.3`). + * Remove reference to the the plugin on the older version (for example, `8.3.0`) from the plan. + * Add reference to the new plugin on the upgrade version (for example, `8.4.3`) to the plan. + + This triggers a rolling upgrade plan change to the later Elasticsearch version, removes reference to the older plugin, and deploys your updated plugin at the same time. + + The following example shows the upgrade of an Elasticsearch deployment and its plugin. You can also upgrade other deployment resources within the same plan change. + + Update deployment plans, update `resources.elasticsearch.plan.elasticsearch.version` and `resources.elasticsearch.plan.cluster_topology.elasticsearch.user_plugins.elasticsearch_version` accordingly. + + ```sh + { + "name": "Extensions", + "prune_orphans": false, + "resources": { + "elasticsearch": [ + { + "region": "gcp-us-central1", + "ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + ... + ], + "elasticsearch": { + "version": "8.4.3", + "enabled_built_in_plugins": [], + "user_plugins": [ + { + "elasticsearch_version": "8.4.3", + "name": "custom-plugin", + "url": "repo://4226448541" + } + ] + + }, + "deployment_template": { + "id": "gcp-storage-optimized-v3" + } + } + } + ] + } + } + ``` + + You can use the [cat plugins API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-plugins.html) to confirm that the plugin has been upgraded successfully to Elasticsearch. + + + +## Delete an extension [ec-extension-guide-delete] + +You can delete an extension simply by calling a DELETE against the EXTENSION_ID of interest: + +```sh +curl -X DELETE \ + https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \ + -H "Authorization: ApiKey $CLOUD_API_KEY" \ + -H 'Content-Type: application/json' +``` + +Only extensions not currently referenced in a deployment plan can be deleted. If you attempt to delete an extension that is in use, you will receive an HTTP 400 Bad Request error like the following, indicating the deployments that are currently using the extension. + +```sh +{ + "errors": [ + { + "message": "Cannot delete extension [EXTENSION_ID]. It is used by deployments [DEPLOYMENT_NAME].", + "code": "extensions.extension_in_use" + } + ] +} +``` + +To remove an extension reference from a deployment plan, simply update the deployment with the extension reference deleted from the `user_plugins` or `user_bundles` arrays. Check [Add an extension to a deployment plan](#ec-extension-guide-add-plan) for where these are specified in the plan. + diff --git a/deploy-manage/deploy/elastic-cloud/project-settings.md b/deploy-manage/deploy/elastic-cloud/project-settings.md new file mode 100644 index 000000000..db3ba9972 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/project-settings.md @@ -0,0 +1,25 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/serverless/current/project-and-management-settings.html + - https://www.elastic.co/guide/en/serverless/current/elasticsearch-manage-project.html +--- + +# Project settings + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/337 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/docs-content/serverless/project-and-management-settings.md +% Notes: anything that isn't deduplicated from +% - [ ] ./raw-migrated-files/docs-content/serverless/elasticsearch-manage-project.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$elasticsearch-manage-project-search-ai-lake-settings$$$ + +$$$elasticsearch-manage-project-search-power-settings$$$ + +$$$project-features-add-ons$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/regions.md b/deploy-manage/deploy/elastic-cloud/regions.md new file mode 100644 index 000000000..0f55d6fb3 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/regions.md @@ -0,0 +1,29 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/regions.html +--- + +# Regions [regions] + +A region is the geographic area where the data center of the cloud provider that hosts your project is located. Review the available Elastic Cloud Serverless regions to decide which region to use. If you aren’t sure which region to pick, choose one that is geographically close to you to reduce latency. + +Elastic Cloud Serverless handles all hosting details for you. You are unable to change the region after you create a project. + +::::{note} +Currently, a limited number of Amazon Web Services (AWS) regions are available. More regions for AWS, as well as Microsoft Azure and Google Cloud Platform (GCP), will be added in the future. + +:::: + + + +## Amazon Web Services (AWS) regions [regions-amazon-web-services-aws-regions] + +The following AWS regions are currently available: + +| Region | Name | +| --- | --- | +| ap-southeast-1 | Asia Pacific (Singapore) | +| eu-west-1 | Europe (Ireland) | +| us-east-1 | US East (N. Virginia) | +| us-west-2 | US West (Oregon) | + diff --git a/deploy-manage/deploy/elastic-cloud/restrictions-known-problems.md b/deploy-manage/deploy/elastic-cloud/restrictions-known-problems.md new file mode 100644 index 000000000..50a541168 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/restrictions-known-problems.md @@ -0,0 +1,156 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-restrictions.html +--- + +# Restrictions and known problems [ec-restrictions] + +When using Elasticsearch Service, there are some limitations you should be aware of: + +* [Security](#ec-restrictions-security) +* [APIs](#ec-restrictions-apis) +* [Transport client](#ec-restrictions-transport-client) +* [Elasticsearch and Kibana plugins](#ec-restrictions-plugins) +* [Watcher](#ec-restrictions-watcher) +* [Kibana](#ec-restrictions-kibana) +* [APM Agent central configuration with Private Link or traffic filters](#ec-restrictions-apm-traffic-filters) +* [Fleet with Private Link or traffic filters](#ec-restrictions-fleet-traffic-filters) +* [Enterprise Search in Kibana](#ec-restrictions-enterprise-search-kibana-integration-traffic-filters) +* [Restoring a snapshot across deployments](#ec-snapshot-restore-enterprise-search-kibana-across-deployments) +* [Migrate Fleet-managed {{agents}} across deployments by restoring a snapshot](#ec-migrate-elastic-agent) +* [Regions and Availability Zones](#ec-regions-and-availability-zone) +* [Known problems](#ec-known-problems) + +For limitations related to logging and monitoring, check the [Restrictions and limitations](../../monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md#ec-restrictions-monitoring) section of the logging and monitoring page. + +Occasionally, we also publish information about [Known problems](#ec-known-problems) with our Elasticsearch Service or the Elastic Stack. + +To learn more about the features that are supported by Elasticsearch Service, check [Elastic Cloud Subscriptions](https://www.elastic.co/cloud/elasticsearch-service/subscriptions?page=docs&placement=docs-body). + + +## Security [ec-restrictions-security] + +* File and LDAP realms cannot be used. The Native realm is enabled, but the realm configuration itself is fixed in {{ecloud}}. Alternatively, authentication protocols such as SAML, OpenID Connect, or Kerberos can be used. +* Client certificates, such as PKI certificates, are not supported. +* IPv6 is not supported. + + +## APIs [ec-restrictions-apis] + +The following restrictions apply when using APIs in Elasticsearch Service: + +Elasticsearch Service API +: The Elasticsearch Service API is subject to a restriction on the volume of API requests that can be submitted per user, per second. Check [Rate limiting](https://www.elastic.co/guide/en/cloud/current/ec-api-rate-limiting.html) for details. + +$$$ec-restrictions-apis-elasticsearch$$$ + +Elasticsearch APIs +: The Elasticsearch APIs do not natively enforce rate limiting. However, all requests to the Elasticsearch cluster are subject to Elasticsearch configuration settings, such as the [network HTTP setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#http-settings) `http:max_content_length` which restricts the maximum size of an HTTP request body. This setting has a default value of 100MB, hence restricting API request payloads to that size. This setting is not currently configurable in Elasticsearch Service. For a list of which Elasticsearch settings are supported on Cloud, check [Add Elasticsearch user settings](edit-stack-settings.md). To learn about using the Elasticsearch APIs in Elasticsearch Service, check [Access the Elasticsearch API console](https://www.elastic.co/guide/en/cloud/current/ec-api-console.html). And, for full details about the Elasticsearch APIs and their endpoints, check the [Elasticsearch API reference documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html). + +$$$ec-restrictions-apis-kibana$$$ + +Kibana APIs +: There are no rate limits restricting your use of the Kibana APIs. However, Kibana features are affected by the [Kibana configuration settings](../self-managed/configure.md), not all of which are supported in Elasticsearch Service. For a list of what settings are currently supported, check [Add Kibana user settings](edit-stack-settings.md). For all details about using the Kibana APIs, check the [Kibana API reference documentation](https://www.elastic.co/guide/en/kibana/current/api.html). + + +## Transport client [ec-restrictions-transport-client] + +* The transport client is not considered thread safe in a cloud environment. We recommend that you use the Java REST client instead. This restriction relates to the fact that your deployments hosted on Elasticsearch Service are behind proxies, which prevent the transport client from communicating directly with Elasticsearch clusters. +* The transport client is not supported over [private link connections](../../security/aws-privatelink-traffic-filters.md). Use the Java REST client instead, or connect over the public internet. +* The transport client does not work with Elasticsearch clusters at version 7.6 and later that are hosted on Cloud. Transport client continues to work with Elasticsearch clusters at version 7.5 and earlier. Note that the transport client was deprecated with version 7.0 and will be removed with 8.0. + + +## Elasticsearch and Kibana plugins [ec-restrictions-plugins] + +* Kibana plugins are not supported. +* Elasticsearch plugins, are not enabled by default for security purposes. Please reach out to support if you would like to enable Elasticsearch plugins support on your account. +* Some Elasticsearch plugins do not apply to Elasticsearch Service. For example, you won’t ever need to change discovery, as Elasticsearch Service handles how nodes discover one another. +* In Elasticsearch 5.0 and later, site plugins are no longer supported. This change does not affect the site plugins Elasticsearch Service might provide out of the box, such as Kopf or Head, since these site plugins are serviced by our proxies and not Elasticsearch itself. +* In Elasticsearch 5.0 and later, site plugins such as Kopf and Paramedic are no longer provided. We recommend that you use our [cluster performance metrics](../../monitor/stack-monitoring.md), [X-Pack monitoring features](../../monitor/stack-monitoring.md) and Kibana’s (6.3+) [Index Management UI](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-mgmt.html) if you want more detailed information or perform index management actions. + + +## Watcher [ec-restrictions-watcher] + +Watcher encryption Key Setup is not supported. + +Changing the default throttle period is not possible. You can specify a throttle period per watch, however. + +Watcher comes preconfigured with a directly usable email account provided by Elastic. However, this account can’t be reconfigured and is subject to some limitations. For more information on the limits of the Elastic mail server, check the [cloud email service limits](../../../explore-analyze/alerts/watcher.md#ec-cloud-email-service-limits) + +Alternatively, a custom mail server can be configured as described in [Configuring a custom mail server](../../../explore-analyze/alerts/watcher.md#ec-watcher-custom-mail-server) + + +## Private Link and SSO to Kibana URLs [ec-restrictions-traffic-filters-kibana-sso] + +Currently you can’t use SSO to login directly from {{ecloud}} into Kibana endpoints that are protected by Private Link traffic filters. However, you can still SSO into Private Link protected Kibana endpoints individually using the [SAML](../../users-roles/cluster-or-deployment-auth/saml.md) or [OIDC](../../users-roles/cluster-or-deployment-auth/openid-connect.md) protocol from your own identity provider, just not through the {{ecloud}} console. Stack level authentication using the {{es}} username and password should also work with `{{kibana-id}}.{vpce|privatelink|psc}.domain` URLs. + + +## PDF report generation using Alerts or Watcher webhooks [ec-restrictions-traffic-filters-watcher] + +* PDF report automatic generation via Alerts is not possible on Elastic Cloud. +* PDF report generation isn’t possible for deployments running on Elastic stack version 8.7.0 or before that are protected by traffic filters. This limitation doesn’t apply to public webhooks such as Slack, PagerDuty, and email. For deployments running on Elastic stack version 8.7.1 and beyond, [PDF report automatic generation via Watcher webhook](../../../explore-analyze/report-and-share/automating-report-generation.md#use-watcher) is possible using the `xpack.notification.webhook.additional_token_enabled` configuration setting to bypass traffic filters. + + +## Kibana [ec-restrictions-kibana] + +* The maximum size of a single {{kib}} instance is 8GB. This means, {{kib}} instances can be scaled up to 8GB before they are scaled out. For example, when creating a deployment with a {{kib}} instance of size 16GB, then 2x8GB instances are created. If you face performance issues with {{kib}} PNG or PDF reports, the recommendations are to create multiple, smaller dashboards to export the data, or to use a third party browser extension for exporting the dashboard in the format you need. +* Running an external Kibana in parallel to Elasticsearch Service’s Kibana instances may cause errors, for example [`Unable to decrypt attribute`](../../../explore-analyze/alerts/kibana/alerting-common-issues.md#rule-cannot-decrypt-api-key), due to a mismatched [`xpack.encryptedSavedObjects.encryptionKey`](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#security-encrypted-saved-objects-settings) as Elasticsearch Service does not [allow users to set](edit-stack-settings.md) nor expose this value. While workarounds are possible, this is not officially supported nor generally recommended. + + +## APM Agent central configuration with PrivateLink or traffic filters [ec-restrictions-apm-traffic-filters] + +If you are using APM 7.9.0 or older: + +* You cannot use [APM Agent central configuration](https://www.elastic.co/guide/en/kibana/current/agent-configuration.html) if your deployment is secured by [traffic filters](../../security/traffic-filtering.md). +* If you access your APM deployment over [PrivateLink](../../security/aws-privatelink-traffic-filters.md), to use APM Agent central configuration you need to allow access to the APM deployment over public internet. + + +## Fleet with PrivateLink or traffic filters [ec-restrictions-fleet-traffic-filters] + +* You cannot use Fleet 7.13.x if your deployment is secured by [traffic filters](../../security/traffic-filtering.md). Fleet 7.14.0 and later works with traffic filters (both Private Link and IP filters). +* If you are using Fleet 8.12+, using a remote {{es}} output with a target cluster that has [traffic filters](../../security/traffic-filtering.md) enabled is not currently supported. + + +## Enterprise Search in Kibana [ec-restrictions-enterprise-search-kibana-integration-traffic-filters] + +Enterprise Search’s management interface in Kibana does not work with traffic filters with 8.3.1 and older, it will return an `Insufficient permissions` (403 Forbidden) error. In Kibana 8.3.2, 8.4.0 and higher, the Enterprise Search management interface works with traffic filters. + + +## Restoring a snapshot across deployments [ec-snapshot-restore-enterprise-search-kibana-across-deployments] + +Kibana and Enterprise Search do not currently support restoring a snapshot of their indices across Elastic Cloud deployments. + +* [Kibana uses encryption keys](https://www.elastic.co/guide/en/kibana/current/using-kibana-with-security.html#security-configure-settings) in various places, ranging from encrypting data in some areas of reporting, alerts, actions, connector tokens, ingest outputs used in Fleet and Synthetics monitoring to user sessions. +* [Enterprise Search uses encryption keys](https://www.elastic.co/guide/en/enterprise-search/current/encryption-keys.html) when storing content source synchronization credentials, API tokens and other sensitive information. +* Currently, there is not a way to retrieve the values of Kibana and Enterprise Search encryption keys, or set them in the target deployment before restoring a snapshot. As a result, once a snapshot is restored, Kibana and Enterprise Search will not be able to decrypt the data required for some Kibana and Enterprise Search features to function properly in the target deployment. +* If you have already restored a snapshot across deployments and now have broken Kibana saved objects or Enterprise Search features in the target deployment, you will have to recreate all broken configurations and objects, or create a new setup in the target deployment instead of using snapshot restore. + +A snapshot taken using the default `found-snapshots` repository can only be restored to deployments in the same region. If you need to restore snapshots across regions, create the destination deployment, connect to the [custom repository](../../tools/snapshot-and-restore/elastic-cloud-hosted.md), and then [restore from a snapshot](../../tools/snapshot-and-restore/restore-snapshot.md). + +When restoring from a deployment that’s using searchable snapshots, you must not delete the snapshots in the source deployment even after they are successfully restored in the destination deployment. Refer to [Restore snapshots containing searchable snapshots indices across clusters](../../tools/snapshot-and-restore/ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md) for more information. + + +## Migrate Fleet-managed {{agents}} across deployments by restoring a snapshot [ec-migrate-elastic-agent] + +There are situations where you may need or want to move your installed {{agents}} from being managed in one deployment to being managed in another deployment. + +In {{ecloud}}, you can migrate your {{agents}} by taking a snapshot of your source deployment, and restoring it on a target deployment. + +To make a seamless migration, after restoring from a snapshot there are some additional steps required, such as updating settings and resetting the agent policy. Check [Migrate Elastic Agents](https://www.elastic.co/guide/en/fleet/current/migrate-elastic-agent.html) for details. + + +## Regions and Availability Zones [ec-regions-and-availability-zone] + +* The AWS `us-west-1` region is limited to two availability zones for ES data nodes and one (tiebreaker only) virtual zone (as depicted by the `-z` in the AZ (`us-west-1z`). Deployment creation with three availability zones for Elasticsearch data nodes for hot, warm, and cold tiers is not possible. This includes scaling an existing deployment with one or two AZs to three availability zones. The virtual zone `us-west-1z` can only hold an Elasticsearch tiebreaker node (no data nodes). The workaround is to use a different AWS US region that allows three availability zones, or to scale existing nodes up within the two availability zones. +* The AWS `eu-central-2` region is limited to two availability zones for CPU Optimized (ARM) Hardware profile ES data node and warm/cold tier. Deployment creation with three availability zones for Elasticsearch data nodes for hot (for CPU Optimized (ARM) profile), warm and cold tiers is not possible. This includes scaling an existing deployment with one or two AZs to three availability zones. The workaround is to use a different AWS region that allows three availability zones, or to scale existing nodes up within the two availability zones. + + +## Known problems [ec-known-problems] + +* There is a known problem affecting clusters with versions 7.7.0 and 7.7.1 due to [a bug in Elasticsearch](https://github.com/elastic/elasticsearch/issues/56739). Although rare, this bug can prevent you from running plans. If this occurs we recommend that you retry the plan, and if that fails please contact support to get your plan through. Because of this bug we recommend you to upgrade to version 7.8 and higher, where the problem has already been addressed. +* A known issue can prevent direct rolling upgrades from Elasticsearch version 5.6.10 to version 6.3.0. As a workaround, we have removed version 6.3.0 from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) for new cluster deployments and for upgrading existing ones. If you are affected by this issue, check [Rolling upgrades from 5.6.x to 6.3.0 fails with "java.lang.IllegalStateException: commit doesn’t contain history uuid"](https://elastic.my.salesforce.com/articles/Support_Article/Rolling-upgrades-to-6-3-0-from-5-x-fails-with-java-lang-IllegalStateException-commit-doesn-t-contain-history-uuid?popup=false&id=kA0610000005JFG) in our Elastic Support Portal. If these steps do not work or you do not have access to the Support Portal, you can contact `support@elastic.co`. + + +## Repository Analysis API is unavailable in Elastic Cloud [ec-repository-analyis-unavailable] + +* The Elasticsearch [Repository analysis API](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html) is not available in {{ecloud}} due to deployments defaulting to having [operator privileges](../../users-roles/cluster-or-deployment-auth/operator-privileges.md) enabled that prevent non-operator privileged users from using it along with a number of other APIs. diff --git a/deploy-manage/deploy/elastic-cloud/serverless.md b/deploy-manage/deploy/elastic-cloud/serverless.md new file mode 100644 index 000000000..cf5538c38 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/serverless.md @@ -0,0 +1,17 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/serverless/current/intro.html + - https://www.elastic.co/guide/en/serverless/current/general-serverless-status.html +--- + +# Serverless + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/337 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/docs-content/serverless/intro.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-serverless-status.md +% Notes: also in troubleshooting \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/subscribe-from-marketplace.md b/deploy-manage/deploy/elastic-cloud/subscribe-from-marketplace.md new file mode 100644 index 000000000..faca749d1 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/subscribe-from-marketplace.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-marketplaces.html +--- + +# Subscribe from a marketplace [ec-marketplaces] + +Subscribe to Elasticsearch Service from a marketplace. Your subscription gets billed together with other services that you’re already using, and can contribute towards your spend commitment with cloud providers. You can subcribe to Elasticsearch Service from any of the following: + +* [AWS Marketplace](aws-marketplace.md) +* [Azure Marketplace](azure-native-isv-service.md) +* [GCP Marketplace](google-cloud-platform-marketplace.md) + + + + + + + diff --git a/deploy-manage/deploy/elastic-cloud/switch-from-apm-to-integrations-server-payload.md b/deploy-manage/deploy/elastic-cloud/switch-from-apm-to-integrations-server-payload.md new file mode 100644 index 000000000..47005dcd3 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/switch-from-apm-to-integrations-server-payload.md @@ -0,0 +1,424 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-integrations-server-apm-switch.html +--- + +# Switch from APM to Integrations Server payload [ec-integrations-server-apm-switch] + +This example shows how to use the Elasticsearch Service RESTful API to switch from using [APM & Fleet Server](#ec-manage-apm-and-fleet) to [Integrations Server](manage-integrations-server.md). + + +### Requirements [ec_requirements_3] + +Given a deployment that is using an APM & Fleet Server with Elastic Stack version 8.0 or later, it is possible to start using Integrations Server instead by updating the deployment with an Integrations Server payload. Switching from APM & Fleet Server to Integrations Server in this way ensures that the endpoints and credentials currently used by APM Server and Fleet Server remain the same after the switch. + +In order to start using the Integrations Server payload, you first need to enable the APM integration for Elastic Agent by following the steps in [Switch to the Elastic APM integration](https://www.elastic.co/guide/en/apm/guide/current/apm-integration-upgrade-steps-ess.html). + + +### API request example [ec_api_request_example_3] + +The example shows how to use the API to create a deployment with APM with version 8.0 and update the deployment to switch to Integrations Server. + + +#### Create a deployment with APM [ec_create_a_deployment_with_apm] + +::::{note} +When creating a deployment with version 8.0 using an APM payload, the APM integration for Elastic Agent is enabled by default. +:::: + + +The following creates a deployment that uses the `gcp-storage-optimized` deployment template in the `gcp-us-east4` region + +```sh +curl -XPOST \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments" \ +-d ' +{ + "resources": { + "apm": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-east4", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.apm.n2.68x32x45", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "apm": { + "version": "8.0.0" + } + }, + "ref_id": "main-apm" + } + ], + "elasticsearch": [ + { + "region": "gcp-us-east4", <1> + "settings": { + "dedicated_masters_threshold": 6 + }, + "plan": { + "autoscaling_enabled": false, + "cluster_topology": [ + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "hot" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "gcp.es.datahot.n2.68x10x45", + "node_roles": [ + "master", + "ingest", + "transform", + "data_hot", + "remote_cluster_client", + "data_content" + ], + "id": "hot_content", + "size": { + "resource": "memory", + "value": 8192 + } + }, + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "warm" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "gcp.es.datawarm.n2.68x10x190", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "id": "warm", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "gcp.es.datacold.n2.68x10x190", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "id": "cold", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + }, + "enabled_built_in_plugins": [] + }, + "instance_configuration_id": "gcp.es.datafrozen.n2.68x10x95", + "node_roles": [ + "data_frozen" + ], + "id": "frozen", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 3, + "instance_configuration_id": "gcp.es.master.n2.68x32x45", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "id": "master", + "size": { + "resource": "memory", + "value": 0 + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "zone_count": 2, + "instance_configuration_id": "gcp.es.coordinating.n2.68x16x45", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "id": "coordinating", + "size": { + "resource": "memory", + "value": 0 + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + }, + { + "zone_count": 1, + "instance_configuration_id": "gcp.es.ml.n2.68x16x45", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "id": "ml", + "size": { + "resource": "memory", + "value": 0 + }, + "elasticsearch": { + "enabled_built_in_plugins": [] + } + } + ], + "elasticsearch": { + "version": "8.0.0" + }, + "deployment_template": { + "id": "gcp-storage-optimized" <2> + } + }, + "ref_id": "main-elasticsearch" + } + ], + "enterprise_search": [], + "kibana": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-east4", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.kibana.n2.68x32x45", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "kibana": { + "version": "8.0.0" + } + }, + "ref_id": "main-kibana" + } + ] + }, + "name": "switch-to-integrations-server", + "metadata": { + "system_owned": false + } +} +' +``` + +1. The region where the deployment is created +2. The deployment template used by the deployment + + + +#### Identify the instance configuration to use for Integrations Server [ec_identify_the_instance_configuration_to_use_for_integrations_server] + +Once the deployment is created, find the `instance_configuration_id` for the Integrations Server payload. It must be supported by the deployment template used by the deployment created in the previous step. + +In the example above, the deployment was created using the `gcp-storage-optimized` deployment template in the `gcp-us-east4` region. + +To find the `instance_configuration_id`, fetch the deployment template using the template ID, the region, and the version used by the deployment (Integrations Server is supported on version 8.0 and higher). + +```sh +curl -XGET \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments/templates/gcp-storage-optimized?region=gcp-us-east4&show_instance_configurations=false&stack_version=8.0.0" +``` + +This returns a deployment template like the following: + +```json +{ + "description": "Good for most ingestion use cases with 7-10 days of data available for fast access. Also good for light search use cases without heavy indexing or CPU needs.", + "name": "Storage optimized", + "template_category_id": "storage-optimized", + "id": "gcp-storage-optimized", + "deployment_template": { + "resources": { + "integrations_server": [ + { + "elasticsearch_cluster_ref_id": "es-ref-id", + "region": "gcp-us-east4", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.integrationsserver.n2.68x32x45", <1> + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "integrations_server": {} + }, + "ref_id": "integrations_server-ref-id" + } + ], + "elasticsearch": [ + ... + ], + "enterprise_search": [ + ... + ], + "kibana": [ + ... + ], + "apm": [ + ... + ] + } + }, + "order": 1, + "system_owned": true, + "metadata": [ + ... + ] +} +``` + +1. The instance configuration ID to use in Integrations Server payload in the next step. + + + +#### Update deployment using the Integrations Server payload [ec_update_deployment_using_the_integrations_server_payload] + +Finally, to switch to Integrations Server, update the deployment using the Integrations Server payload, setting `instance_configuration_id` to the value identified in the previous step. + +```sh +curl -XPUT \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/deployments/" \ +-d ' +{ + "name": "switch-to-integrations-server", + "alias": "switch-to-integrations-server", + "prune_orphans": false, <2> + "metadata": { + "system_owned": false, + "hidden": false + }, + "resources": { + "integrations_server": [ + { + "region": "gcp-us-east4", + "ref_id": "main-integrations_server", + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.integrationsserver.n2.68x32x45", <1> + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "integrations_server": { + "version": "8.0.0" + }, + "transient": { + "strategy": { + "autodetect": {} + } + } + } + } + ] + } +} +' +``` + +1. Make sure to use the `instance_configuration_id` for Integrations Server from the deployment template. +2. Make sure `prune_orphans` is set to `false`. `prune_orphans` is an important parameter. It specifies how resources not included in the body of this PUT request should be handled. If `false`, those resources not included are kept intact. + + +## Manage your APM & Fleet Server [ec-manage-apm-and-fleet] + +::::{note} +Beginning with Elastic Stack version 8.0, [Integrations Server](manage-integrations-server.md) is replacing APM & Fleet Server. New deployments with version 8.0 will use Integrations Server automatically. Existing deployments using APM & Fleet Server will continue to use APM & Fleet Server after upgrading to version 8.0. +:::: + + +You have the option to add a combined [Application Performance Monitoring (APM) Server](https://www.elastic.co/guide/en/apm/guide/current/apm-overview.html) and [Fleet Server](https://www.elastic.co/guide/en/fleet/current/fleet-overview.html) to your deployment. APM allows you to monitor software services and applications in real time, turning that data into documents stored in the Elasticsearch cluster. Fleet allows you to centrally manage Elastic Agents on many hosts. + +As part of provisioning, the APM Server and Fleet Server are already configured to work with Elasticsearch and Kibana. At the end of provisioning, you are shown the secret token to configure communication between the APM Server and the backend [APM Agents](https://www.elastic.co/guide/en/apm/agent/index.html). The APM Agents get deployed within your services and applications. + +From the deployment **APM & Fleet** page you can also: + +* Get the URL to complete the APM agent configuration. +* Use the `elastic` credentials to go to the APM area of Kibana. Step by step instructions to configure a variety of agents are available right in Kibana. After that, you can use the pre-built, dedicated dashboards and the APM tab to visualize the data that is sent back from the APM Agents. +* Use the `elastic` credentials to go to the Fleet area of Kibana. Step by step instructions to download and install Elastic Agent on your hosts are available right in Kibana. After that, you can manage enrolled Elastic Agents on the **Agents** tab, and the data shipped back from those Elastic Agents on the **Data streams** tab. +* Reset the APM secret token. + + ::::{important} + Resetting the token disrupts your APM service and restarts the server. When the server restarts, you’ll need to update all of your agents with the new token. + :::: + +* Access the APM & Fleet logs and metrics. +* Stop and restart your APM & Fleet Server. +* Upgrade your APM & Fleet Server version if it is out of sync with your Elasticsearch cluster. +* Fully remove the APM & Fleet Server, delete it from the disk, and stop the charges. + + +### Upgrading to {{stack}} 8.0 [ec-upgrade-apm-stack-8] + +The following APM settings have been removed in {{stack}} version 8.0. This change is only relevant to users upgrading a standalone (legacy) deployment of APM Server to {{stack}} version 8.0. Check [Add APM user settings](../../../solutions/observability/apps/configure-apm-server.md) for more details. + +```yaml +apm-server.api_key.enabled +apm-server.api_key.limit +apm-server.ilm.* +apm-server.frontend.* +apm-server.register.* +apm-server.rum.allow_service_names +apm-server.rum.event_rate.lru_size +apm-server.rum.event_rate.limit +apm-server.rum.rate_limit +output.elasticsearch.bulk_max_size +output.elasticsearch.index +output.elasticsearch.indices +output.elasticsearch.pipeline +output.elasticsearch.pipelines +output.elasticsearch.worker +setup.* +queue.* +``` + + diff --git a/deploy-manage/deploy/elastic-cloud/tools-apis.md b/deploy-manage/deploy/elastic-cloud/tools-apis.md new file mode 100644 index 000000000..2210a9f78 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/tools-apis.md @@ -0,0 +1,19 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/serverless/current/elasticsearch-http-apis.html + - https://www.elastic.co/guide/en/tpec/current/index.html +--- + +# Tools and APIs + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/310 + +% Scope notes: elastic cloud control does this work for serverless/cloud together? + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/docs-content/serverless/elasticsearch-http-apis.md +% - [ ] https://www.elastic.co/guide/en/tpec/current/index.html +% Notes: reference only, this page wasn't migrated, but you can pull from the live URL if needed. \ No newline at end of file diff --git a/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md b/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md new file mode 100644 index 000000000..2930ec4d8 --- /dev/null +++ b/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md @@ -0,0 +1,28 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-custom-bundles.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-custom-bundles.html +--- + +# Upload custom plugins and bundles + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-custom-bundles.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-custom-bundles.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-add-your-plugin$$$ + +$$$ec-update-bundles-and-plugins$$$ + +$$$ec-update-bundles$$$ + +$$$ech-add-your-plugin$$$ + +$$$ech-update-bundles-and-plugins$$$ + +$$$ech-update-bundles$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/kibana-reporting-configuration.md b/deploy-manage/deploy/kibana-reporting-configuration.md new file mode 100644 index 000000000..806b6eb90 --- /dev/null +++ b/deploy-manage/deploy/kibana-reporting-configuration.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/secure-reporting.html + - https://www.elastic.co/guide/en/kibana/current/reporting-production-considerations.html +--- + +# Kibana reporting configuration + +% What needs to be done: Refine + +% GitHub issue: ??? PENDING TO ADD THE TASK TO AN ISSUE + +% Scope notes: Reporting documentation will be a bit spread: - how to use reporting in Explore and Analyze - how to configure reporting in Kibana configuration. - Reporting troubleshooting in troubleshooting. - All reporting settings in reference. The content linked is applicable to all deployment types but certaion parts are only valid for self-managed, so we need to find the best way to present this in the new IA. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/secure-reporting.md +% - [ ] ./raw-migrated-files/kibana/kibana/reporting-production-considerations.md \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed.md b/deploy-manage/deploy/self-managed.md new file mode 100644 index 000000000..bdecd1745 --- /dev/null +++ b/deploy-manage/deploy/self-managed.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/dependencies-versions.html +--- + +# Self-managed cluster [dependencies-versions] + +See [Elastic Stack Third-party Dependencices](https://artifacts.elastic.co/reports/dependencies/dependencies-current.md) for the complete list of dependencies for {{es}}. + diff --git a/deploy-manage/deploy/self-managed/access.md b/deploy-manage/deploy/self-managed/access.md new file mode 100644 index 000000000..fe6bf6e92 --- /dev/null +++ b/deploy-manage/deploy/self-managed/access.md @@ -0,0 +1,80 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/access.html +--- + +# Access [access] + +The fastest way to access {{kib}} is to use our hosted {{es}} Service. If you [installed {{kib}} on your own](install-kibana.md), access {{kib}} through the web application. + + +## Set up on cloud [_set_up_on_cloud] + +There’s no faster way to get started than with our hosted {{ess}} on Elastic Cloud: + +1. [Get a free trial](https://cloud.elastic.co/registration?page=docs&placement=docs-body). +2. Log into [Elastic Cloud](https://cloud.elastic.co?page=docs&placement=docs-body). +3. Click **Create deployment**. +4. Give your deployment a name. +5. Click **Create deployment** and download the password for the `elastic` user. + +That’s it! Now that you are up and running, it’s time to get some data into {{kib}}. {{kib}} will open as soon as your deployment is ready. + + +## Log on to the web application [log-on-to-the-web-application] + +If you are using a self-managed deployment, access {{kib}} through the web application on port 5601. + +1. Point your web browser to the machine where you are running {{kib}} and specify the port number. For example, `localhost:5601` or `http://YOURDOMAIN.com:5601`. + + To remotely connect to {{kib}}, set [server.host](configure.md#server-host) to a non-loopback address. + +2. Log on to your account. +3. Go to the home page, then click **{{kib}}**. +4. To make the {{kib}} page your landing page, click **Make this my landing page**. + + +## Check the {{kib}} status [status] + +The status page displays information about the server resource usage and installed plugins. + +To view the {{kib}} status page, use the status endpoint. For example, `localhost:5601/status`. + +:::{image} ../../../images/kibana-kibana-status-page-7_14_0.png +:alt: Kibana server status page +:class: screenshot +::: + +For JSON-formatted server status details, use the `localhost:5601/api/status` API endpoint. + + +## Troubleshoot {{kib}} UI error [not-ready] + +Troubleshoot the `Kibana Server is not Ready yet` error. + +1. From within a {{kib}} node, confirm the connection to {{es}}: + + ```sh + curl -XGET elasticsearch_ip_or_hostname:9200/ + ``` + +2. Guarantee the health of the three {{kib}}-backing indices. All indices must appear and display `status:green` and `status:open`: + + ```sh + curl -XGET elasticsearch_ip_or_hostname:9200/_cat/indices/.kibana,.kibana_task_manager,.kibana_security_session?v=true + ``` + + These {{kib}}-backing indices must also not have [index settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-get-settings.html) flagging `read_only_allow_delete` or `write` [index blocks](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-blocks.html). + +3. [Shut down all {{kib}} nodes](../../maintenance/start-stop-services/start-stop-kibana.md). +4. Choose any {{kib}} node, then update the config to set the [debug logging](../../monitor/logging-configuration/log-settings-examples.md#change-overall-log-level). +5. [Start the node](../../maintenance/start-stop-services/start-stop-kibana.md), then check the start-up debug logs for `ERROR` messages or other start-up issues. + + For example: + + * When {{kib}} is unable to connect to a healthy {{es}} cluster, errors like `master_not_discovered_exception` or `unable to revive connection` or `license is not available` errors appear. + * When one or more {{kib}}-backing indices are unhealthy, the `index_not_green_timeout` error appears. + + +You can find a Kibana health troubleshooting walkthrough in [this blog](https://www.elastic.co/blog/troubleshooting-kibana-health) or in [this video](https://www.youtube.com/watch?v=AlgGYcpGvOA). + diff --git a/deploy-manage/deploy/self-managed/air-gapped-install.md b/deploy-manage/deploy/self-managed/air-gapped-install.md new file mode 100644 index 000000000..47dd41ba1 --- /dev/null +++ b/deploy-manage/deploy/self-managed/air-gapped-install.md @@ -0,0 +1,80 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elastic-stack/current/air-gapped-install.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-install-offline.html +--- + +# Air gapped install + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/309 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/air-gapped-install.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-install-offline.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$air-gapped-self-managed-linux$$$ + +$$$air-gapped-elasticsearch$$$ + +$$$air-gapped-kibana$$$ + +$$$air-gapped-beats$$$ + +$$$air-gapped-logstash$$$ + +$$$air-gapped-elastic-agent$$$ + +$$$air-gapped-fleet$$$ + +$$$air-gapped-elastic-apm$$$ + +$$$air-gapped-elastic-maps-service$$$ + +$$$air-gapped-enterprise-search$$$ + +$$$air-gapped-elastic-package-registry$$$ + +$$$air-gapped-elastic-artifact-registry$$$ + +$$$air-gapped-elastic-endpoint-artifact-repository$$$ + +$$$air-gapped-machine-learning$$$ + +$$$air-gapped-kubernetes-and-openshift$$$ + +$$$air-gapped-k8s-os-elastic-kubernetes-operator$$$ + +$$$air-gapped-k8s-os-elastic-package-registry$$$ + +$$$air-gapped-k8s-os-elastic-artifact-registry$$$ + +$$$air-gapped-k8s-os-elastic-endpoint-artifact-repository$$$ + +$$$air-gapped-k8s-os-ironbank-secure-images$$$ + +$$$air-gapped-ece$$$ + +$$$air-gapped-elastic-package-registry-example$$$ + +$$$air-gapped-elastic-artifact-registry-example$$$ + +$$$air-gapped-epr-kubernetes-example$$$ + +$$$air-gapped-agent-integration-guide$$$ + +$$$air-gapped-agent-integration-terminology$$$ + +$$$air-gapped-agent-integration-configure$$$ + +$$$air-gapped-agent-integration-configure-kibana$$$ + +$$$air-gapped-agent-integration-configure-yml$$$ + +$$$air-gapped-agent-integration-configure-fleet-api$$$ + +$$$air-gapped-kibana-product-documentation$$$ diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-all-permission.md b/deploy-manage/deploy/self-managed/bootstrap-checks-all-permission.md new file mode 100644 index 000000000..12b8bf358 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-all-permission.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-all-permission.html +--- + +# All permission check [bootstrap-checks-all-permission] + +The all permission check ensures that the security policy used during bootstrap does not grant the `java.security.AllPermission` to Elasticsearch. Running with the all permission granted is equivalent to disabling the security manager. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-client-jvm.md b/deploy-manage/deploy/self-managed/bootstrap-checks-client-jvm.md new file mode 100644 index 000000000..51480cfce --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-client-jvm.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-client-jvm.html +--- + +# Client JVM check [bootstrap-checks-client-jvm] + +There are two different JVMs provided by OpenJDK-derived JVMs: the client JVM and the server JVM. These JVMs use different compilers for producing executable machine code from Java bytecode. The client JVM is tuned for startup time and memory footprint while the server JVM is tuned for maximizing performance. The difference in performance between the two VMs can be substantial. The client JVM check ensures that Elasticsearch is not running inside the client JVM. To pass the client JVM check, you must start Elasticsearch with the server VM. On modern systems and operating systems, the server VM is the default. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-discovery-configuration.md b/deploy-manage/deploy/self-managed/bootstrap-checks-discovery-configuration.md new file mode 100644 index 000000000..bd457015a --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-discovery-configuration.md @@ -0,0 +1,17 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-discovery-configuration.html +--- + +# Discovery configuration check [bootstrap-checks-discovery-configuration] + +By default, when Elasticsearch first starts up it will try and discover other nodes running on the same host. If no elected master can be discovered within a few seconds then Elasticsearch will form a cluster that includes any other nodes that were discovered. It is useful to be able to form this cluster without any extra configuration in development mode, but this is unsuitable for production because it’s possible to form multiple clusters and lose data as a result. + +This bootstrap check ensures that discovery is not running with the default configuration. It can be satisfied by setting at least one of the following properties: + +* `discovery.seed_hosts` +* `discovery.seed_providers` +* `cluster.initial_master_nodes` + +Note that you must [remove `cluster.initial_master_nodes` from the configuration of every node](important-settings-configuration.md#initial_master_nodes) after the cluster has started for the first time. Instead, configure `discovery.seed_hosts` or `discovery.seed_providers`. If you do not need any discovery configuration, for instance if running a single-node cluster, set `discovery.seed_hosts: []` to disable discovery and satisfy this bootstrap check. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-early-access.md b/deploy-manage/deploy/self-managed/bootstrap-checks-early-access.md new file mode 100644 index 000000000..d3b6b2193 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-early-access.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-early-access.html +--- + +# Early-access check [bootstrap-checks-early-access] + +The OpenJDK project provides early-access snapshots of upcoming releases. These releases are not suitable for production. The early-access check detects these early-access snapshots. To pass this check, you must start Elasticsearch on a release build of the JVM. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-file-descriptor.md b/deploy-manage/deploy/self-managed/bootstrap-checks-file-descriptor.md new file mode 100644 index 000000000..3f3f309ed --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-file-descriptor.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-file-descriptor.html +--- + +# File descriptor check [bootstrap-checks-file-descriptor] + +File descriptors are a Unix construct for tracking open "files". In Unix though, [everything is a file](https://en.wikipedia.org/wiki/Everything_is_a_file). For example, "files" could be a physical file, a virtual file (e.g., `/proc/loadavg`), or network sockets. Elasticsearch requires lots of file descriptors (e.g., every shard is composed of multiple segments and other files, plus connections to other nodes, etc.). This bootstrap check is enforced on OS X and Linux. To pass the file descriptor check, you might have to configure [file descriptors](file-descriptors.md). + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-heap-size.md b/deploy-manage/deploy/self-managed/bootstrap-checks-heap-size.md new file mode 100644 index 000000000..17265c22b --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-heap-size.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-heap-size.html +--- + +# Heap size check [bootstrap-checks-heap-size] + +By default, {{es}} automatically sizes JVM heap based on a node’s [roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) and total memory. If you manually override the default sizing and start the JVM with different initial and max heap sizes, the JVM may pause as it resizes the heap during system usage. If you enable [`bootstrap.memory_lock`](setup-configuration-memory.md#bootstrap-memory_lock), the JVM locks the initial heap size on startup. If the initial heap size is not equal to the maximum heap size, some JVM heap may not be locked after a resize. To avoid these issues, start the JVM with an initial heap size equal to the maximum heap size. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-max-file-size.md b/deploy-manage/deploy/self-managed/bootstrap-checks-max-file-size.md new file mode 100644 index 000000000..02e0a736f --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-max-file-size.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-max-file-size.html +--- + +# Max file size check [bootstrap-checks-max-file-size] + +The segment files that are the components of individual shards and the translog generations that are components of the translog can get large (exceeding multiple gigabytes). On systems where the max size of files that can be created by the Elasticsearch process is limited, this can lead to failed writes. Therefore, the safest option here is that the max file size is unlimited and that is what the max file size bootstrap check enforces. To pass the max file check, you must configure your system to allow the Elasticsearch process the ability to write files of unlimited size. This can be done via `/etc/security/limits.conf` using the `fsize` setting to `unlimited` (note that you might have to increase the limits for the `root` user too). + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-max-map-count.md b/deploy-manage/deploy/self-managed/bootstrap-checks-max-map-count.md new file mode 100644 index 000000000..d7a3af443 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-max-map-count.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-max-map-count.html +--- + +# Maximum map count check [bootstrap-checks-max-map-count] + +Continuing from the previous [point](max-size-virtual-memory-check.md), to use `mmap` effectively, Elasticsearch also requires the ability to create many memory-mapped areas. The maximum map count check checks that the kernel allows a process to have at least 262,144 memory-mapped areas and is enforced on Linux only. To pass the maximum map count check, you must configure `vm.max_map_count` via `sysctl` to be at least `262144`. + +Alternatively, the maximum map count check is only needed if you are using `mmapfs` or `hybridfs` as the [store type](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-store.html) for your indices. If you [do not allow](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-store.html#allow-mmap) the use of `mmap` then this bootstrap check will not be enforced. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-memory-lock.md b/deploy-manage/deploy/self-managed/bootstrap-checks-memory-lock.md new file mode 100644 index 000000000..a44f8830a --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-memory-lock.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-memory-lock.html +--- + +# Memory lock check [bootstrap-checks-memory-lock] + +When the JVM does a major garbage collection it touches every page of the heap. If any of those pages are swapped out to disk they will have to be swapped back in to memory. That causes lots of disk thrashing that Elasticsearch would much rather use to service requests. There are several ways to configure a system to disallow swapping. One way is by requesting the JVM to lock the heap in memory through `mlockall` (Unix) or virtual lock (Windows). This is done via the Elasticsearch setting [`bootstrap.memory_lock`](setup-configuration-memory.md#bootstrap-memory_lock). However, there are cases where this setting can be passed to Elasticsearch but Elasticsearch is not able to lock the heap (e.g., if the `elasticsearch` user does not have `memlock unlimited`). The memory lock check verifies that **if** the `bootstrap.memory_lock` setting is enabled, that the JVM was successfully able to lock the heap. To pass the memory lock check, you might have to configure [`bootstrap.memory_lock`](setup-configuration-memory.md#bootstrap-memory_lock). + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-onerror.md b/deploy-manage/deploy/self-managed/bootstrap-checks-onerror.md new file mode 100644 index 000000000..07ba5ec07 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-onerror.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-onerror.html +--- + +# OnError and OnOutOfMemoryError checks [bootstrap-checks-onerror] + +The JVM options `OnError` and `OnOutOfMemoryError` enable executing arbitrary commands if the JVM encounters a fatal error (`OnError`) or an `OutOfMemoryError` (`OnOutOfMemoryError`). However, by default, Elasticsearch system call filters (seccomp) are enabled and these filters prevent forking. Thus, using `OnError` or `OnOutOfMemoryError` and system call filters are incompatible. The `OnError` and `OnOutOfMemoryError` checks prevent Elasticsearch from starting if either of these JVM options are used and system call filters are enabled. This check is always enforced. To pass this check do not enable `OnError` nor `OnOutOfMemoryError`; instead, upgrade to Java 8u92 and use the JVM flag `ExitOnOutOfMemoryError`. While this does not have the full capabilities of `OnError` nor `OnOutOfMemoryError`, arbitrary forking will not be supported with seccomp enabled. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-serial-collector.md b/deploy-manage/deploy/self-managed/bootstrap-checks-serial-collector.md new file mode 100644 index 000000000..0817073a2 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-serial-collector.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-serial-collector.html +--- + +# Use serial collector check [bootstrap-checks-serial-collector] + +There are various garbage collectors for the OpenJDK-derived JVMs targeting different workloads. The serial collector in particular is best suited for single logical CPU machines or extremely small heaps, neither of which are suitable for running Elasticsearch. Using the serial collector with Elasticsearch can be devastating for performance. The serial collector check ensures that Elasticsearch is not configured to run with the serial collector. To pass the serial collector check, you must not start Elasticsearch with the serial collector (whether it’s from the defaults for the JVM that you’re using, or you’ve explicitly specified it with `-XX:+UseSerialGC`). Note that the default JVM configuration that ships with Elasticsearch configures Elasticsearch to use the G1GC garbage collector with JDK14 and later versions. For earlier JDK versions, the configuration defaults to the CMS collector. + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks-syscall-filter.md b/deploy-manage/deploy/self-managed/bootstrap-checks-syscall-filter.md new file mode 100644 index 000000000..4d677bf91 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks-syscall-filter.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-syscall-filter.html +--- + +# System call filter check [bootstrap-checks-syscall-filter] + +Elasticsearch installs system call filters of various flavors depending on the operating system (e.g., seccomp on Linux). These system call filters are installed to prevent the ability to execute system calls related to forking as a defense mechanism against arbitrary code execution attacks on Elasticsearch. The system call filter check ensures that if system call filters are enabled, then they were successfully installed. To pass the system call filter check you must fix any configuration errors on your system that prevented system call filters from installing (check your logs). + diff --git a/deploy-manage/deploy/self-managed/bootstrap-checks.md b/deploy-manage/deploy/self-managed/bootstrap-checks.md new file mode 100644 index 000000000..02ea62b72 --- /dev/null +++ b/deploy-manage/deploy/self-managed/bootstrap-checks.md @@ -0,0 +1,27 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/bootstrap-checks-xpack.html +--- + +# Bootstrap Checks + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/340 + +% Scope notes: This page shows Development vs Production modes. Very useful and needed during the installation. Should we put the child docs in REFERENCE material -> Elasticsearch Bootstrap Checks reference? + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/bootstrap-checks.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/bootstrap-checks-xpack.md +% Notes: FYI Colleen McGinnis removed "All children" because the linked page has no children + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$dev-vs-prod-mode$$$ + +$$$bootstrap-checks-tls$$$ + +$$$single-node-discovery$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/configure-elasticsearch.md b/deploy-manage/deploy/self-managed/configure-elasticsearch.md new file mode 100644 index 000000000..a33f0a689 --- /dev/null +++ b/deploy-manage/deploy/self-managed/configure-elasticsearch.md @@ -0,0 +1,170 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html +--- + +# Configure Elasticsearch [settings] + +{{es}} ships with good defaults and requires very little configuration. Most settings can be changed on a running cluster using the [Cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) API. + +The configuration files should contain settings which are node-specific (such as `node.name` and paths), or settings which a node requires in order to be able to join a cluster, such as `cluster.name` and `network.host`. + + +## Config files location [config-files-location] + +{{es}} has three configuration files: + +* `elasticsearch.yml` for configuring {es} +* `jvm.options` for configuring {{es}} JVM settings +* `log4j2.properties` for configuring {{es}} logging + +These files are located in the config directory, whose default location depends on whether or not the installation is from an archive distribution (`tar.gz` or `zip`) or a package distribution (Debian or RPM packages). + +For the archive distributions, the config directory location defaults to `$ES_HOME/config`. The location of the config directory can be changed via the `ES_PATH_CONF` environment variable as follows: + +```sh +ES_PATH_CONF=/path/to/my/config ./bin/elasticsearch +``` + +Alternatively, you can `export` the `ES_PATH_CONF` environment variable via the command line or via your shell profile. + +For the package distributions, the config directory location defaults to `/etc/elasticsearch`. The location of the config directory can also be changed via the `ES_PATH_CONF` environment variable, but note that setting this in your shell is not sufficient. Instead, this variable is sourced from `/etc/default/elasticsearch` (for the Debian package) and `/etc/sysconfig/elasticsearch` (for the RPM package). You will need to edit the `ES_PATH_CONF=/etc/elasticsearch` entry in one of these files accordingly to change the config directory location. + + +## Config file format [_config_file_format] + +The configuration format is [YAML](https://yaml.org/). Here is an example of changing the path of the data and logs directories: + +```yaml +path: + data: /var/lib/elasticsearch + logs: /var/log/elasticsearch +``` + +Settings can also be flattened as follows: + +```yaml +path.data: /var/lib/elasticsearch +path.logs: /var/log/elasticsearch +``` + +In YAML, you can format non-scalar values as sequences: + +```yaml +discovery.seed_hosts: + - 192.168.1.10:9300 + - 192.168.1.11 + - seeds.mydomain.com +``` + +Though less common, you can also format non-scalar values as arrays: + +```yaml +discovery.seed_hosts: ["192.168.1.10:9300", "192.168.1.11", "seeds.mydomain.com"] +``` + + +## Environment variable substitution [_environment_variable_substitution] + +Environment variables referenced with the `${...}` notation within the configuration file will be replaced with the value of the environment variable. For example: + +```yaml +node.name: ${HOSTNAME} +network.host: ${ES_NETWORK_HOST} +``` + +Values for environment variables must be simple strings. Use a comma-separated string to provide values that {{es}} will parse as a list. For example, {{es}} will split the following string into a list of values for the `${HOSTNAME}` environment variable: + +```yaml +export HOSTNAME="host1,host2" +``` + + +## Cluster and node setting types [cluster-setting-types] + +Cluster and node settings can be categorized based on how they are configured: + +$$$dynamic-cluster-setting$$$ + +Dynamic +: You can configure and update dynamic settings on a running cluster using the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). You can also configure dynamic settings locally on an unstarted or shut down node using `elasticsearch.yml`. + +Updates made using the cluster update settings API can be *persistent*, which apply across cluster restarts, or *transient*, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a `null` value using the API. + +If you configure the same setting using multiple methods, {{es}} applies the settings in following order of precedence: + +1. Transient setting +2. Persistent setting +3. `elasticsearch.yml` setting +4. Default setting value + +For example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting. However, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting. + +::::{tip} +If you use {{ess}}, use the [user settings](../elastic-cloud/edit-stack-settings.md) feature to configure all cluster settings. This method lets {{ess}} automatically reject unsafe settings that could break your cluster. + +If you run {{es}} on your own hardware, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) to configure dynamic cluster settings. Only use `elasticsearch.yml` for static cluster settings and node settings. The API doesn’t require a restart and ensures a setting’s value is the same on all nodes. + +:::: + + +::::{warning} +We no longer recommend using transient cluster settings. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration. + +:::: + + + +$$$static-cluster-setting$$$ + +Static +: Static settings can only be configured on an unstarted or shut down node using `elasticsearch.yml`. + + Static settings must be set on every relevant node in the cluster. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +$$$path-settings$$$ + +$$$ref-saml-settings$$$ + +$$$ref-oidc-settings$$$ + +$$$ref-kerberos-settings$$$ + +$$$hashing-settings$$$ + +$$$cluster-shard-limit$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/configure.md b/deploy-manage/deploy/self-managed/configure.md new file mode 100644 index 000000000..501069c3a --- /dev/null +++ b/deploy-manage/deploy/self-managed/configure.md @@ -0,0 +1,527 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/settings.html +--- + +# Configure [settings] + +The {{kib}} server reads properties from the `kibana.yml` file on startup. The location of this file differs depending on how you installed {{kib}}. For example, if you installed {{kib}} from an archive distribution (`.tar.gz` or `.zip`), by default it is in `$KIBANA_HOME/config`. By default, with package distributions (Debian or RPM), it is in `/etc/kibana`. The config directory can be changed via the `KBN_PATH_CONF` environment variable: + +```text +KBN_PATH_CONF=/home/kibana/config ./bin/kibana +``` + +The default host and port settings configure {{kib}} to run on `localhost:5601`. To change this behavior and allow remote users to connect, you’ll need to update your `kibana.yml` file. You can also enable SSL and set a variety of other options. + +Environment variables can be injected into configuration using `${MY_ENV_VAR}` syntax. By default, configuration validation will fail if an environment variable used in the config file is not present when Kibana starts. This behavior can be changed by using a default value for the environment variable, using the `${MY_ENV_VAR:defaultValue}` syntax. + +`console.ui.enabled` +: Toggling this causes the server to regenerate assets on the next startup, which may cause a delay before pages start being served. Set to `false` to disable Console. **Default: `true`** + +`csp.script_src` +: Add sources for the [Content Security Policy `script-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src). + +`csp.disableUnsafeEval` +: [8.7.0] Set this to `false` to add the [`unsafe-eval`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_eval_expressions) source expression to the `script-src` directive. **Default: `true`** + + When `csp.disableUnsafeEval` is set to `true`, Kibana will use a custom version of the Handlebars template library. Handlebars is used in various locations in the Kibana frontend where custom templates can be supplied by the user when for instance setting up a visualisation. If you experience any issues rendering Handlebars templates, please set this setting to `false` and [open an issue](https://github.com/elastic/kibana/issues/new/choose) in the Kibana GitHub repository. + + +`csp.worker_src` +: Add sources for the [Content Security Policy `worker-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/worker-src). + +`csp.style_src` +: Add sources for the [Content Security Policy `style-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src). + +`csp.connect_src` +: Add sources for the [Content Security Policy `connect-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src). + +`csp.default_src` +: Add sources for the [Content Security Policy `default-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src). + +`csp.font_src` +: Add sources for the [Content Security Policy `font-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/font-src). + +`csp.frame_src` +: Add sources for the [Content Security Policy `frame-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src). + +`csp.img_src` +: Add sources for the [Content Security Policy `img-src` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src). + +`csp.frame_ancestors` +: Add sources for the [Content Security Policy `frame-ancestors` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors). + + ::::{note} + The `frame-ancestors` directive can also be configured by using [`server.securityResponseHeaders.disableEmbedding`](#server-securityResponseHeaders-disableEmbedding). In that case, that takes precedence and any values in `csp.frame_ancestors` are ignored. + :::: + + +`csp.report_only.form_action` +: Add sources for the [Content Security Policy `form-action` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/form-action) in reporting mode. + +`csp.report_uri` +: Add sources for the [Content Security Policy `report-uri` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri). + +`csp.report_to:` +: Add sources for the [Content Security Policy `report-to` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to). + +$$$csp-strict$$$ `csp.strict` +: Blocks {{kib}} access to any browser that does not enforce even rudimentary CSP rules. In practice, this disables support for older, less safe browsers like Internet Explorer. For more information, refer to [Content Security Policy](../../security/secure-http-communications.md#csp-strict-mode). **Default: `true`** + +`csp.warnLegacyBrowsers` +: Shows a warning message after loading {{kib}} to any browser that does not enforce even rudimentary CSP rules, though {{kib}} is still accessible. This configuration is effectively ignored when [`csp.strict`](#csp-strict) is enabled. **Default: `true`** + +`permissionsPolicy.report_to:` +: Add sources for the [Permissions Policy `report-to` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy). + +$$$elasticsearch-maxSockets$$$ `elasticsearch.maxSockets` +: The maximum number of sockets that can be used for communications with {{es}}. **Default: `Infinity`** + +$$$elasticsearch-maxResponseSize$$$ `elasticsearch.maxResponseSize` +: Either `false` or a `byteSize` value. When set, responses from {{es}} with a size higher than the defined limit will be rejected. This is intended to be used as a circuit-breaker mechanism to avoid memory errors in case of unexpectedly high responses coming from {{es}}. **Default: `false`** + +$$$elasticsearch-maxIdleSockets$$$ `elasticsearch.maxIdleSockets` +: The maximum number of idle sockets to keep open between {{kib}} and {{es}}. If more sockets become idle, they will be closed. **Default: `256`** + +$$$elasticsearch-idleSocketTimeout$$$ `elasticsearch.idleSocketTimeout` +: The timeout for idle sockets kept open between {{kib}} and {{es}}. If the socket is idle for longer than this timeout, it will be closed. If you have a transparent proxy between {{kib}} and {{es}} be sure to set this value lower than or equal to the proxy’s timeout. **Default: `60s`** + +`elasticsearch.customHeaders` +: | Header names and values to send to {{es}}. Any custom headers cannot be overwritten by client-side headers, regardless of the [`elasticsearch.requestHeadersWhitelist`](#elasticsearch-requestHeadersWhitelist) configuration. **Default: `{}`** + +$$$elasticsearch-hosts$$$ `elasticsearch.hosts:` +: The URLs of the {{es}} instances to use for all your queries. All nodes listed here must be on the same cluster. **Default: `[ "http://localhost:9200" ]`** + + To enable SSL/TLS for outbound connections to {{es}}, use the `https` protocol in this setting. + + +$$$elasticsearch-publicBaseUrl$$$ `elasticsearch.publicBaseUrl:` +: The URL through which Elasticsearch is publicly accessible, if any. This will be shown to users in Kibana when they need connection details for your Elasticsearch cluster. + +$$$elasticsearch-pingTimeout$$$ `elasticsearch.pingTimeout` +: Time in milliseconds to wait for {{es}} to respond to pings. **Default: the value of the [`elasticsearch.requestTimeout`](#elasticsearch-requestTimeout) setting** + +$$$elasticsearch-requestHeadersWhitelist$$$ `elasticsearch.requestHeadersWhitelist` +: List of {{kib}} client-side headers to send to {{es}}. To send **no** client-side headers, set this value to [] (an empty list). Removing the `authorization` header from being whitelisted means that you cannot use [basic authentication](../../users-roles/cluster-or-deployment-auth/user-authentication.md#basic-authentication) in {{kib}}. **Default: `[ 'authorization', 'es-client-authentication' ]`** + +$$$elasticsearch-requestTimeout$$$ `elasticsearch.requestTimeout` +: Time in milliseconds to wait for responses from the back end or {{es}}. This value must be a positive integer. **Default: `30000`** + +`elasticsearch.shardTimeout` +: Time in milliseconds for {{es}} to wait for responses from shards. Set to 0 to disable. **Default: `30000`** + +`elasticsearch.compression` +: Specifies whether {{kib}} should use compression for communications with {{es}}. **Default: `false`** + +`elasticsearch.sniffInterval` +: Time in milliseconds between requests to check {{es}} for an updated list of nodes. **Default: `false`** + +`elasticsearch.sniffOnStart` +: Attempt to find other {{es}} nodes on startup. **Default: `false`** + +`elasticsearch.sniffOnConnectionFault` +: Update the list of {{es}} nodes immediately following a connection fault. **Default: `false`** + +$$$elasticsearch-ssl-alwaysPresentCertificate$$$ `elasticsearch.ssl.alwaysPresentCertificate` +: Controls {{kib}} behavior in regard to presenting a client certificate when requested by {{es}}. This setting applies to all outbound SSL/TLS connections to {{es}}, including requests that are proxied for end users. **Default: `false`** + + ::::{warning} + When {{es}} uses certificates to authenticate end users with a PKI realm and [`elasticsearch.ssl.alwaysPresentCertificate`](#elasticsearch-ssl-alwaysPresentCertificate) is `true`, proxied requests may be executed as the identity that is tied to the {{kib}} server. + :::: + + +$$$elasticsearch-ssl-cert-key$$$ `elasticsearch.ssl.certificate` and `elasticsearch.ssl.key` +: Paths to a PEM-encoded X.509 client certificate and its corresponding private key. These are used by {{kib}} to authenticate itself when making outbound SSL/TLS connections to {{es}}. For this setting to take effect, the `xpack.security.http.ssl.client_authentication` setting in {{es}} must be also be set to `"required"` or `"optional"` to request a client certificate from {{kib}}. + + ::::{note} + These settings cannot be used in conjunction with [`elasticsearch.ssl.keystore.path`](#elasticsearch-ssl-keystore-path). + :::: + + +$$$elasticsearch-ssl-certificateAuthorities$$$ `elasticsearch.ssl.certificateAuthorities` +: Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates, which make up a trusted certificate chain for {{es}}. This chain is used by {{kib}} to establish trust when making outbound SSL/TLS connections to {{es}}. + + In addition to this setting, trusted certificates may be specified via [`elasticsearch.ssl.keystore.path`](#elasticsearch-ssl-keystore-path) and/or [`elasticsearch.ssl.truststore.path`](#elasticsearch-ssl-truststore-path). + + +`elasticsearch.ssl.keyPassphrase` +: The password that decrypts the private key that is specified via [`elasticsearch.ssl.key`](#elasticsearch-ssl-cert-key). This value is optional, as the key may not be encrypted. + +$$$elasticsearch-ssl-keystore-path$$$ `elasticsearch.ssl.keystore.path` +: Path to a PKCS#12 keystore that contains an X.509 client certificate and it’s corresponding private key. These are used by {{kib}} to authenticate itself when making outbound SSL/TLS connections to {{es}}. For this setting, you must also set the `xpack.security.http.ssl.client_authentication` setting in {{es}} to `"required"` or `"optional"` to request a client certificate from {{kib}}. + + If the keystore contains any additional certificates, they are used as a trusted certificate chain for {{es}}. This chain is used by {{kib}} to establish trust when making outbound SSL/TLS connections to {{es}}. In addition to this setting, trusted certificates may be specified via [`elasticsearch.ssl.certificateAuthorities`](#elasticsearch-ssl-certificateAuthorities) and/or [`elasticsearch.ssl.truststore.path`](#elasticsearch-ssl-truststore-path). + + ::::{note} + This setting cannot be used in conjunction with [`elasticsearch.ssl.certificate`](#elasticsearch-ssl-cert-key) or [`elasticsearch.ssl.key`](#elasticsearch-ssl-cert-key). + :::: + + +`elasticsearch.ssl.keystore.password` +: The password that decrypts the keystore specified via [`elasticsearch.ssl.keystore.path`](#elasticsearch-ssl-keystore-path). If the keystore has no password, leave this as blank. If the keystore has an empty password, set this to `""`. + +$$$elasticsearch-ssl-truststore-path$$$ `elasticsearch.ssl.truststore.path` +: Path to a PKCS#12 trust store that contains one or more X.509 certificate authority (CA) certificates, which make up a trusted certificate chain for {{es}}. This chain is used by {{kib}} to establish trust when making outbound SSL/TLS connections to {{es}}. + + In addition to this setting, trusted certificates may be specified via [`elasticsearch.ssl.certificateAuthorities`](#elasticsearch-ssl-certificateAuthorities) and/or [`elasticsearch.ssl.keystore.path`](#elasticsearch-ssl-keystore-path). + + +`elasticsearch.ssl.truststore.password` +: The password that decrypts the trust store specified via [`elasticsearch.ssl.truststore.path`](#elasticsearch-ssl-truststore-path). If the trust store has no password, leave this as blank. If the trust store has an empty password, set this to `""`. + +$$$elasticsearch-ssl-verificationMode$$$ `elasticsearch.ssl.verificationMode` +: Controls the verification of the server certificate that {{kib}} receives when making an outbound SSL/TLS connection to {{es}}. Valid values are `"full"`, `"certificate"`, and `"none"`. Using `"full"` performs hostname verification, using `"certificate"` skips hostname verification, and using `"none"` skips verification entirely. **Default: `"full"`** + +$$$elasticsearch-user-passwd$$$ `elasticsearch.username` and `elasticsearch.password` +: If your {{es}} is protected with basic authentication, these settings provide the username and password that the {{kib}} server uses to perform maintenance on the {{kib}} index at startup. {{kib}} users still need to authenticate with {{es}}, which is proxied through the {{kib}} server. + +$$$elasticsearch-service-account-token$$$ `elasticsearch.serviceAccountToken` +: If your {{es}} is protected with basic authentication, this token provides the credentials that the {{kib}} server uses to perform maintenance on the {{kib}} index at startup. This setting is an alternative to `elasticsearch.username` and `elasticsearch.password`. + +`unifiedSearch.autocomplete.valueSuggestions.timeout` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Time in milliseconds to wait for autocomplete suggestions from {{es}}. This value must be a whole number greater than zero. **Default: `"1000"`** + +`unifiedSearch.autocomplete.valueSuggestions.terminateAfter` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Maximum number of documents loaded by each shard to generate autocomplete suggestions. This value must be a whole number greater than zero. **Default: `"100000"`** + + ::::{note} + To reload the [logging settings](https://www.elastic.co/guide/en/kibana/current/logging-settings.html), send a SIGHUP signal to {{kib}}. For more logging configuration options, see the [Configure Logging in {{kib}}](../../monitor/logging-configuration/kibana-logging.md) guide. + :::: + + +$$$logging-root$$$ `logging.root` +: The `root` logger has is a [dedicated logger](../../monitor/logging-configuration/kibana-logging.md#dedicated-loggers) and is pre-configured. The `root` logger logs at `info` level by default. If any other logging configuration is specified, `root` *must* also be explicitly configured. + +$$$logging-root-appenders$$$ `logging.root.appenders` +: A list of logging appenders to forward the root level logger instance to. By default `root` is configured with the `default` appender that logs to stdout with a `pattern` layout. This is the configuration that all custom loggers will use unless they’re re-configured explicitly. You can override the default behavior by configuring a different [appender](../../monitor/logging-configuration/kibana-logging.md#logging-appenders) to apply to `root`. + +$$$logging-root-level$$$ `logging.root.level` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Level at which a log record should be logged. Supported levels are: *all*, *fatal*, *error*, *warn*, *info*, *debug*, *trace*, *off*. Levels are ordered from *all* (highest) to *off* and a log record will be logged it its level is higher than or equal to the level of its logger, otherwise the log record is ignored. Use this value to [change the overall log level](../../monitor/logging-configuration/log-settings-examples.md#change-overall-log-level). **Default: `info`**. + + ::::{tip} + Set to `all` to log all events, including system usage information and all requests. Set to `off` to silence all logs. You can also use the logging [cli commands](../../monitor/logging-configuration/_cli_configuration.md#logging-cli-migration) to set log level to `verbose` or silence all logs. + :::: + + + The following example shows a valid verbose `logging.root` configuration: + + ```text + logging: + appenders: + console_appender: + type: console + layout: + type: pattern + highlight: true + root: + appenders: [console_appender] + level: all + ``` + + +$$$logging-loggers$$$ `logging.loggers[]` +: Allows you to [customize a specific logger instance](../../monitor/logging-configuration/log-settings-examples.md#customize-specific-log-records). + +`logging.appenders[]` +: [Appenders](../../monitor/logging-configuration/kibana-logging.md#logging-appenders) define how and where log messages are displayed (eg. **stdout** or console) and stored (eg. file on the disk). + +`map.includeElasticMapsService` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Set to `false` to disable connections to Elastic Maps Service. When `includeElasticMapsService` is turned off, only tile layer configured by [`map.tilemap.url`](#tilemap-url) is available in [Maps](../../../explore-analyze/visualize/maps.md). **Default: `true`** + +`map.emsUrl` +: Specifies the URL of a self hosted [{{hosted-ems}}](../../../explore-analyze/visualize/maps/maps-connect-to-ems.md#elastic-maps-server) + +$$$tilemap-settings$$$ `map.tilemap.options.attribution` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: The map attribution string. Provide attributions in markdown and use `\|` to delimit attributions, for example: `"[attribution 1](https://www.attribution1)\|[attribution 2](https://www.attribution2)"`. **Default: `"© [Elastic Maps Service](https://www.elastic.co/elastic-maps-service)"`** + +$$$tilemap-max-zoom$$$ `map.tilemap.options.maxZoom` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: The maximum zoom level. **Default: `10`** + +$$$tilemap-min-zoom$$$ `map.tilemap.options.minZoom` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: The minimum zoom level. **Default: `1`** + +$$$tilemap-subdomains$$$ `map.tilemap.options.subdomains` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: An array of subdomains used by the tile service. Specify the position of the subdomain the URL with the token `{s}`. + +$$$tilemap-url$$$ `map.tilemap.url` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: The URL to the service that {{kib}} uses as the default basemap in [maps](../../../explore-analyze/visualize/maps.md) and [vega maps](../../../explore-analyze/visualize/custom-visualizations-with-vega.md#vega-with-a-map). By default, {{kib}} sets a basemap from the [Elastic Maps Service](../../../explore-analyze/visualize/maps/maps-connect-to-ems.md), but users can point to their own Tile Map Service. For example: `"https://tiles.elastic.co/v2/default/{{z}}/{x}/{{y}}.png?elastic_tile_service_tos=agree&my_app_name=kibana"` + +`migrations.batchSize` +: Defines the number of documents migrated at a time. The higher the value, the faster the Saved Objects migration process performs at the cost of higher memory consumption. If upgrade migrations results in {{kib}} crashing with an out of memory exception or fails due to an Elasticsearch `circuit_breaking_exception`, use a smaller `batchSize` value to reduce the memory pressure. **Default: `1000`** + +`migrations.maxBatchSizeBytes` +: Defines the maximum payload size for indexing batches of upgraded saved objects to avoid migrations failing due to a 413 Request Entity Too Large response from Elasticsearch. This value should be lower than or equal to your Elasticsearch cluster’s `http.max_content_length` configuration option. **Default: `100mb`** + +`migrations.retryAttempts` +: The number of times migrations retry temporary failures, such as a network timeout, 503 status code, or `snapshot_in_progress_exception`. When upgrade migrations frequently fail after exhausting all retry attempts with a message such as `Unable to complete the [...] step after 15 attempts, terminating.`, increase the setting value. **Default: `15`** + +`newsfeed.enabled` +: Controls whether to enable the newsfeed system for the {{kib}} UI notification center. Set to `false` to disable the newsfeed system. **Default: `true`** + +`node.roles` +: [preview] Indicates which roles to configure the {{kib}} process with, which will effectively run {{kib}} in different modes. Valid options are `background_tasks` and `ui`, or `*` to select all roles. **Default: `*`** + +`notifications.connectors.default.email` +: Choose the default email connector for user notifications. As of `8.6.0`, {{kib}} is shipping with a new notification mechanism that will send email notifications for various user actions, e.g. assigning a *Case* to a user. To enable notifications, an email connector must be [preconfigured](https://www.elastic.co/guide/en/kibana/current/pre-configured-connectors.html) in the system via `kibana.yml`, and the notifications plugin must be configured to point to the ID of that connector. + +$$$path-data$$$ `path.data` +: The path where {{kib}} stores persistent data not saved in {{es}}. **Default: `data`** + +`pid.file` +: Specifies the path where {{kib}} creates the process ID file. + +`ops.interval` +: Set the interval in milliseconds to sample system and process performance metrics. The minimum value is 100. **Default: `5000`** + +$$$ops-cGroupOverrides-cpuPath$$$ `ops.cGroupOverrides.cpuPath` +: Override for cgroup cpu path when mounted in a manner that is inconsistent with `/proc/self/cgroup`. + +$$$ops-cGroupOverrides-cpuAcctPath$$$ `ops.cGroupOverrides.cpuAcctPath` +: Override for cgroup cpuacct path when mounted in a manner that is inconsistent with `/proc/self/cgroup`. + +$$$savedObjects-maxImportExportSize$$$ `savedObjects.maxImportExportSize` +: The maximum count of saved objects that can be imported or exported. This setting exists to prevent the {{kib}} server from running out of memory when handling large numbers of saved objects. It is recommended to only raise this setting if you are confident your server can hold this many objects in memory. **Default: `10000`** + +$$$savedObjects-maxImportPayloadBytes$$$ `savedObjects.maxImportPayloadBytes` +: The maximum byte size of a saved objects import that the {{kib}} server will accept. This setting exists to prevent the {{kib}} server from running out of memory when handling a large import payload. Note that this setting overrides the more general [`server.maxPayload`](#server-maxPayload) for saved object imports only. **Default: `26214400`** + +$$$server-basePath$$$ `server.basePath` +: Enables you to specify a path to mount {{kib}} at if you are running behind a proxy. Use the [`server.rewriteBasePath`](#server-rewriteBasePath) setting to tell {{kib}} if it should remove the basePath from requests it receives, and to prevent a deprecation warning at startup. This setting cannot end in a slash (`/`). + +$$$server-publicBaseUrl$$$ `server.publicBaseUrl` +: The publicly available URL that end-users access Kibana at. Must include the protocol, hostname, port (if different than the defaults for `http` and `https`, 80 and 443 respectively), and the [`server.basePath`](#server-basePath) (when that setting is configured explicitly). This setting cannot end in a slash (`/`). + +$$$server-compression$$$ `server.compression.enabled` +: Set to `false` to disable HTTP compression for all responses. **Default: `true`** + +`server.cors.enabled` +: [preview] Set to `true` to allow cross-origin API calls. **Default:** `false` + +`server.cors.allowCredentials` +: [preview] Set to `true` to allow browser code to access response body whenever request performed with user credentials. **Default:** `false` + +`server.cors.allowOrigin` +: experimental::[] List of origins permitted to access resources. You must specify explicit hostnames and not use `server.cors.allowOrigin: ["*"]` when `server.cors.allowCredentials: true`. **Default:** ["*"] + +`server.compression.referrerWhitelist` +: Specifies an array of trusted hostnames, such as the {{kib}} host, or a reverse proxy sitting in front of it. This determines whether HTTP compression may be used for responses, based on the request `Referer` header. This setting may not be used when [`server.compression.enabled`](#server-compression) is set to `false`. **Default: `none`** + +`server.compression.brotli.enabled` +: Set to `true` to enable brotli (br) compression format. Note: browsers not supporting brotli compression will fallback to using gzip instead. This setting may not be used when [`server.compression.enabled`](#server-compression) is set to `false`. **Default: `false`** + +$$$server-securityResponseHeaders-strictTransportSecurity$$$ `server.securityResponseHeaders.strictTransportSecurity` +: Controls whether the [`Strict-Transport-Security`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) header is used in all responses to the client from the {{kib}} server, and specifies what value is used. Allowed values are any text value or `null`. To disable, set to `null`. **Default:** `null` + +$$$server-securityResponseHeaders-xContentTypeOptions$$$ `server.securityResponseHeaders.xContentTypeOptions` +: Controls whether the [`X-Content-Type-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) header is used in all responses to the client from the {{kib}} server, and specifies what value is used. Allowed values are `nosniff` or `null`. To disable, set to `null`. **Default:** `"nosniff"` + +$$$server-securityResponseHeaders-referrerPolicy$$$ `server.securityResponseHeaders.referrerPolicy` +: Controls whether the [`Referrer-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) header is used in all responses to the client from the {{kib}} server, and specifies what value is used. Allowed values are `no-referrer`, `no-referrer-when-downgrade`, `origin`, `origin-when-cross-origin`, `same-origin`, `strict-origin`, `strict-origin-when-cross-origin`, `unsafe-url`, or `null`. To disable, set to `null`. **Default:** `"strict-origin-when-cross-origin"` + +$$$server-securityResponseHeaders-permissionsPolicy$$$ `server.securityResponseHeaders.permissionsPolicy` +: [preview] Controls whether the [`Permissions-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) header is used in all responses to the client from the {{kib}} server, and specifies what value is used. Allowed values are any text value or `null`. Refer to the [`Permissions-Policy` documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) for defined directives, values, and text format. To disable, set to `null`. **Default:** `camera=(), display-capture=(), fullscreen=(self), geolocation=(), microphone=(), web-share=()` + +$$$server-securityResponseHeaders-permissionsPolicyReportOnly$$$ `server.securityResponseHeaders.permissionsPolicyReportOnly` +: [preview] Controls whether the [`Permissions-Policy-Report-Only`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) header is used in all responses to the client from the {{kib}} server, and specifies what value is used. Allowed values are any text value or `null`. Refer to the [`Permissions-Policy` documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) for defined directives, values, and text format. + +$$$server-securityResponseHeaders-disableEmbedding$$$`server.securityResponseHeaders.disableEmbedding` +: Controls whether the [`Content-Security-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) and [`X-Frame-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) headers are configured to disable embedding {{kib}} in other webpages using iframes. When set to `true`, secure headers are used to disable embedding, which adds the `frame-ancestors: 'self'` directive to the `Content-Security-Policy` response header and adds the `X-Frame-Options: SAMEORIGIN` response header. **Default:** `false` + +$$$server-securityResponseHeaders-crossOriginOpenerPolicy$$$ `server.securityResponseHeaders.crossOriginOpenerPolicy` +: Controls whether the [`Cross-Origin-Opener-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) header is used in all responses to the client from the {{kib}} server, and specifies what value is used. Allowed values are `unsafe-none`, `same-origin-allow-popups`, `same-origin`, or `null`. To disable, set to `null`. **Default:** `"same-origin"` + +`server.customResponseHeaders` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Header names and values to send on all responses to the client from the {{kib}} server. **Default: `{}`** + +$$$server-shutdownTimeout$$$ `server.shutdownTimeout` +: Sets the grace period for {{kib}} to attempt to resolve any ongoing HTTP requests after receiving a `SIGTERM`/`SIGINT` signal, and before shutting down. Any new HTTP requests received during this period are rejected, because the incoming socket is closed without further processing. **Default: `30s`** + +$$$server-host$$$ `server.host` +: This setting specifies the host of the back end server. To allow remote users to connect, set the value to the IP address or DNS name of the {{kib}} server. Use `0.0.0.0` to make Kibana listen on all IPs (public and private). **Default: `"localhost"`** + +`server.keepaliveTimeout` +: The number of milliseconds to wait for additional data before restarting the [`server.socketTimeout`](#server-socketTimeout) counter. **Default: `"120000"`** + +$$$server-maxPayload$$$ `server.maxPayload` +: The maximum payload size in bytes for incoming server requests. **Default: `1048576`** + +`server.name` +: A human-readable display name that identifies this {{kib}} instance. **Default: `"your-hostname"`** + +$$$server-port$$$ `server.port` +: {{kib}} is served by a back end server. This setting specifies the port to use. **Default: `5601`** + +$$$server-protocol$$$ `server.protocol` +: [preview] The http protocol to use, either `http1` or `http2`. Set to `http1` to opt out of `HTTP/2` support when TLS is enabled. Use of `http1` may impact browser loading performance especially for dashboards with many panels. **Default**: `http2` if TLS is enabled, otherwise `http1`. + + ::::{note} + By default, enabling `http2` requires a valid `h2c` configuration, meaning that TLS must be enabled via [`server.ssl.enabled`](#server-ssl-enabled) and [`server.ssl.supportedProtocols`](#server-ssl-supportedProtocols), if specified, must contain at least `TLSv1.2` or `TLSv1.3`. Strict validation of the `h2c` setup can be disabled by adding `server.http2.allowUnsecure: true` to the configuration. + :::: + + +$$$server-rate-limiter-enabled$$$ `server.rateLimiter.enabled` +: Enables rate-limiting of requests to the {{kib}} server based on Node.js' Event Loop Utilization. If the average event loop utilization for the specified term exceeds the configured threshold, the server will respond with a `429 Too Many Requests` status code. + + This functionality should be used carefully as it may impact the server’s availability. The configuration options vary per environment, so it is recommended to enable this option in a testing environment first, adjust the rate-limiter configuration, and then roll it out to production. + + **Default: `false`** + + +`server.rateLimiter.elu` +: The Event Loop Utilization (ELU) threshold for rate-limiting requests to the {{kib}} server. The ELU is a value between 0 and 1, representing the average event loop utilization over the specified term. If the average ELU exceeds this threshold, the server will respond with a `429 Too Many Requests` status code. + + In a multi-instance environment with autoscaling, this value is usually between 0.6 and 0.8 to give the autoscaler enough time to react. This value can be higher in a single-instance environment but should not exceed 1.0. In general, the lower the value, the more aggressive the rate limiting. And the highest possible option should be used to prevent the {{kib}} server from being terminated. + + +`server.rateLimiter.term` +: This value is one of `short`, `medium`, or `long`, representing the term over which the average event loop utilization is calculated. It uses exponential moving averages (EMA) to smooth out the utilization values. Each term corresponds to `15s`, `30s`, and `60s`, respectively. + + The term value also changes the way the rate limiter sees the trend in the load: + + * `short`: `elu.short > server.rateLimiter.term`; + * `medium`: `elu.short > server.rateLimiter.elu AND elu.medium > server.rateLimiter.elu`; + * `long`: `elu.short > server.rateLimiter.elu AND elu.medium > server.rateLimiter.elu AND elu.long > server.rateLimiter.elu`. + + This behavior prevents requests from being throttled if the load starts decreasing. In general, the shorter the term, the more aggressive the rate limiting. In the multi-instance environment, the `medium` term makes the most sense as it gives the {{kib}} server enough time to spin up a new instance and prevents the existing instances from being terminated. + + +$$$server-requestId-allowFromAnyIp$$$ `server.requestId.allowFromAnyIp` +: Sets whether or not the `X-Opaque-Id` header should be trusted from any IP address for identifying requests in logs and forwarded to Elasticsearch. + +`server.requestId.ipAllowlist` +: A list of IPv4 and IPv6 address which the `X-Opaque-Id` header should be trusted from. Normally this would be set to the IP addresses of the load balancers or reverse-proxy that end users use to access Kibana. If any are set, [`server.requestId.allowFromAnyIp`](#server-requestId-allowFromAnyIp) must also be set to `false.` + +$$$server-rewriteBasePath$$$ `server.rewriteBasePath` +: Specifies whether {{kib}} should rewrite requests that are prefixed with [`server.basePath`](#server-basePath) or require that they are rewritten by your reverse proxy. **Default: `false`** + +$$$server-socketTimeout$$$ `server.socketTimeout` +: The number of milliseconds to wait before closing an inactive socket. **Default: `"120000"`** + +$$$server-payloadTimeout$$$ `server.payloadTimeout` +: Sets the maximum time allowed for the client to transmit the request payload (body) before giving up and responding with a Request Timeout (408) error response. **Default: `"20000"`** + +$$$server-ssl-cert-key$$$ `server.ssl.certificate` and `server.ssl.key` +: Paths to a PEM-encoded X.509 server certificate and its corresponding private key. These are used by {{kib}} to establish trust when receiving inbound SSL/TLS connections from users. + + ::::{note} + These settings cannot be used in conjunction with [`server.ssl.keystore.path`](#server-ssl-keystore-path). + :::: + + +$$$server-ssl-certificateAuthorities$$$ `server.ssl.certificateAuthorities` +: Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates which make up a trusted certificate chain for {{kib}}. This chain is used by {{kib}} to establish trust when receiving inbound SSL/TLS connections from end users. If PKI authentication is enabled, this chain is also used by {{kib}} to verify client certificates from end users. + + In addition to this setting, trusted certificates may be specified via [`server.ssl.keystore.path`](#server-ssl-keystore-path) and/or [`server.ssl.truststore.path`](#server-ssl-truststore-path). + + +$$$server-ssl-cipherSuites$$$ `server.ssl.cipherSuites` +: Details on the format, and the valid options, are available via the [OpenSSL cipher list format documentation](https://www.openssl.org/docs/man1.1.1/man1/ciphers.md#CIPHER-LIST-FORMAT). **Default: `TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 TLS_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-GCM-SHA384, DHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, DHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, DHE-RSA-AES256-SHA384, ECDHE-RSA-AES256-SHA256, DHE-RSA-AES256-SHA256, HIGH,!aNULL, !eNULL, !EXPORT, !DES, !RC4, !MD5, !PSK, !SRP, !CAMELLIA`**. + +`server.ssl.clientAuthentication` +: Controls the behavior in {{kib}} for requesting a certificate from client connections. Valid values are `"required"`, `"optional"`, and `"none"`. Using `"required"` will refuse to establish the connection unless a client presents a certificate, using `"optional"` will allow a client to present a certificate if it has one, and using `"none"` will prevent a client from presenting a certificate. **Default: `"none"`** + +$$$server-ssl-enabled$$$ `server.ssl.enabled` +: | Enables SSL/TLS for inbound connections to {{kib}}. When set to `true`, a certificate and its corresponding private key must be provided. These can be specified via [`server.ssl.keystore.path`](#server-ssl-keystore-path) or the combination of [`server.ssl.certificate`](#server-ssl-cert-key) and [`server.ssl.key`](#server-ssl-cert-key). **Default: `false`** + +`server.ssl.keyPassphrase` +: The password that decrypts the private key that is specified via [`server.ssl.key`](#server-ssl-cert-key). This value is optional, as the key may not be encrypted. + +$$$server-ssl-keystore-path$$$ `server.ssl.keystore.path` +: Path to a PKCS#12 keystore that contains an X.509 server certificate and its corresponding private key. If the keystore contains any additional certificates, those will be used as a trusted certificate chain for {{kib}}. All of these are used by {{kib}} to establish trust when receiving inbound SSL/TLS connections from end users. The certificate chain is also used by {{kib}} to verify client certificates from end users when PKI authentication is enabled. + + In addition to this setting, trusted certificates may be specified via [`server.ssl.certificateAuthorities`](#server-ssl-certificateAuthorities) and/or [`server.ssl.truststore.path`](#server-ssl-truststore-path). + + ::::{note} + This setting cannot be used in conjunction with [`server.ssl.certificate`](#server-ssl-cert-key) or [`server.ssl.key`](#server-ssl-cert-key) + :::: + + +`server.ssl.keystore.password` +: The password that will be used to decrypt the keystore specified via [`server.ssl.keystore.path`](#server-ssl-keystore-path). If the keystore has no password, leave this unset. If the keystore has an empty password, set this to `""`. + +$$$server-ssl-truststore-path$$$ `server.ssl.truststore.path` +: Path to a PKCS#12 trust store that contains one or more X.509 certificate authority (CA) certificates which make up a trusted certificate chain for {{kib}}. This chain is used by {{kib}} to establish trust when receiving inbound SSL/TLS connections from end users. If PKI authentication is enabled, this chain is also used by {{kib}} to verify client certificates from end users. + + In addition to this setting, trusted certificates may be specified via [`server.ssl.certificateAuthorities`](#server-ssl-certificateAuthorities) and/or [`server.ssl.keystore.path`](#server-ssl-keystore-path). + + +`server.ssl.truststore.password` +: The password that will be used to decrypt the trust store specified via [`server.ssl.truststore.path`](#server-ssl-truststore-path). If the trust store has no password, leave this unset. If the trust store has an empty password, set this to `""`. + +`server.ssl.redirectHttpFromPort` +: {{kib}} binds to this port and redirects all http requests to https over the port configured as [`server.port`](#server-port). + +$$$server-ssl-supportedProtocols$$$ `server.ssl.supportedProtocols` +: An array of supported protocols with versions. Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. **Default: TLSv1.2, TLSv1.3** Enabling `TLSv1.1` would require both setting the `--tls-min-1.1` option in the `node.options` configuration and adding `TLSv1.1` to `server.ssl.supportedProtocols`. `HTTP/2` requires the use of minimum `TLSv1.2` for secure connections. + +$$$server-uuid$$$ `server.uuid` +: The unique identifier for this {{kib}} instance. It must be a valid UUIDv4. It gets automatically generated on the first startup if not specified and persisted in the `data` path. + +$$$settings-xsrf-allowlist$$$ `server.xsrf.allowlist` +: It is not recommended to disable protections for arbitrary API endpoints. Instead, supply the `kbn-xsrf` header. The [`server.xsrf.allowlist`](#settings-xsrf-allowlist) setting requires the following format: + + ```text + *Default: [ ]* An array of API endpoints which should be exempt from Cross-Site Request Forgery ("XSRF") protections. + ``` + + +$$$settings-xsrf-disableProtection$$$ `server.xsrf.disableProtection` +: Setting this to `true` will completely disable Cross-site request forgery protection in Kibana. This is not recommended. **Default: `false`** + +`status.allowAnonymous` +: If authentication is enabled, setting this to `true` enables unauthenticated users to access the {{kib}} server status API and status page. **Default: `false`** + +$$$telemetry-allowChangingOptInStatus$$$ `telemetry.allowChangingOptInStatus` +: When `false`, users cannot change the opt-in status through [Advanced Settings](https://www.elastic.co/guide/en/kibana/current/advanced-options.html), and {{kib}} only looks at the value of [`telemetry.optIn`](#settings-telemetry-optIn) to determine whether to send telemetry data or not. **Default: `true`**. + +$$$settings-telemetry-optIn$$$ `telemetry.optIn` +: Set to `false` to stop sending any telemetry data to Elastic. Reporting your cluster statistics helps us improve your user experience. When `false`, the telemetry data is never sent to Elastic.
+ + This setting can be changed at any time in [Advanced Settings](https://www.elastic.co/guide/en/kibana/current/advanced-options.html). To prevent users from changing it, set [`telemetry.allowChangingOptInStatus`](#telemetry-allowChangingOptInStatus) to `false`. **Default: `true`** + + +`vis_type_vega.enableExternalUrls` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Set this value to true to allow Vega to use any URL to access external data sources and images. When false, Vega can only get data from {{es}}. **Default: `false`** + +`xpack.ccr.ui.enabled` +: Set this value to false to disable the Cross-Cluster Replication UI. **Default: `true`** + +$$$settings-explore-data-in-context$$$ `xpack.discoverEnhanced.actions.exploreDataInContextMenu.enabled` +: Enables the **Explore underlying data** option that allows you to open **Discover** from a dashboard panel and view the panel data. **Default: `false`** + + When you create visualizations using the **Lens** drag-and-drop editor, you can use the toolbar to open and explore your data in **Discover**. For more information, check out [Explore the data in Discover](../../../explore-analyze/visualize/lens.md#explore-lens-data-in-discover). + + +$$$settings-explore-data-in-chart$$$ `xpack.discoverEnhanced.actions.exploreDataInChart.enabled` +: Enables you to view the underlying documents in a data series from a dashboard panel. **Default: `false`** + +`xpack.ilm.ui.enabled` +: Set this value to false to disable the Index Lifecycle Policies UI. **Default: `true`** + +`xpack.index_management.ui.enabled` +: Set this value to false to disable the Index Management UI. **Default: `true`** + +`xpack.license_management.ui.enabled` +: Set this value to false to disable the License Management UI. **Default: `true`** + +`xpack.remote_clusters.ui.enabled` +: Set this value to false to disable the Remote Clusters UI. **Default: `true`** + +`xpack.rollup.ui.enabled` +: Set this value to false to disable the Rollup Jobs UI. **Default: true** + + ::::{admonition} Deprecated in 8.11.0. + :class: warning + + Rollups are deprecated and will be removed in a future version. Use [downsampling](../../../manage-data/data-store/index-types/downsampling-time-series-data-stream.md) instead. + :::: + + +`xpack.snapshot_restore.ui.enabled` +: Set this value to false to disable the Snapshot and Restore UI. **Default: true** + +`xpack.upgrade_assistant.ui.enabled` +: Set this value to false to disable the Upgrade Assistant UI. **Default: true** + +`i18n.locale` ![logo cloud](https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg "Supported on {{ess}}") +: Set this value to change the {{kib}} interface language. Valid locales are: `en`, `zh-CN`, `ja-JP`, `fr-FR`. **Default: `en`** diff --git a/deploy-manage/deploy/self-managed/deploy-cluster.md b/deploy-manage/deploy/self-managed/deploy-cluster.md new file mode 100644 index 000000000..33c74c815 --- /dev/null +++ b/deploy-manage/deploy/self-managed/deploy-cluster.md @@ -0,0 +1,23 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro-deploy.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html + - https://www.elastic.co/guide/en/elastic-stack/current/installing-elastic-stack.html +--- + +# Deploy the cluster + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/340 + +% Scope notes: Work with the previous content to explain the different options to install Elasticsearch and Kibana, remove the references to cloud based installation. cover ES + kibana - install of other stack components should be taken care of in that content set hints about install order (First ES then Kib). Add an introduction also to the installation methods (locally, production, multiple OSs). + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/elasticsearch-intro-deploy.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/setup.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/installing-elastic-stack.md +% Notes: 1-5 + +$$$dedicated-host$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/executable-jna-tmpdir.md b/deploy-manage/deploy/self-managed/executable-jna-tmpdir.md new file mode 100644 index 000000000..cd4f8f7e5 --- /dev/null +++ b/deploy-manage/deploy/self-managed/executable-jna-tmpdir.md @@ -0,0 +1,39 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/executable-jna-tmpdir.html +--- + +# Ensure JNA temporary directory permits executables [executable-jna-tmpdir] + +::::{note} +This is only relevant for Linux. +:::: + + +{{es}} uses the Java Native Access (JNA) library, and another library called `libffi`, for executing some platform-dependent native code. On Linux, the native code backing these libraries is extracted at runtime into a temporary directory and then mapped into executable pages in {{es}}'s address space. This requires the underlying files not to be on a filesystem mounted with the `noexec` option. + +By default, {{es}} will create its temporary directory within `/tmp`. However, some hardened Linux installations mount `/tmp` with the `noexec` option by default. This prevents JNA and `libffi` from working correctly. For instance, at startup JNA may fail to load with an `java.lang.UnsatisfiedLinkerError` exception or with a message that says something similar to `failed to map segment from shared object`, or `libffi` may report a message such as `failed to allocate closure`. Note that the exception messages can differ between JVM versions. Additionally, the components of {{es}} that rely on execution of native code via JNA may fail with messages indicating that it is `because JNA is not available`. + +To resolve these problems, either remove the `noexec` option from your `/tmp` filesystem, or configure {{es}} to use a different location for its temporary directory by setting the [`$ES_TMPDIR`](important-settings-configuration.md#es-tmpdir) environment variable. For instance: + +* If you are running {{es}} directly from a shell, set `$ES_TMPDIR` as follows: + + ```sh + export ES_TMPDIR=/usr/share/elasticsearch/tmp + ``` + +* For installs done through RPM or DEB packages, the environment variable needs to be set through the [system configuration file](setting-system-settings.md#sysconfig). +* If you are using `systemd` to run {{es}} as a service, add the following line to the `[Service]` section in a [service override file](setting-system-settings.md#systemd): + + ```text + Environment=ES_TMPDIR=/usr/share/elasticsearch/tmp + ``` + + +If you need finer control over the location of these temporary files, you can also configure the path that JNA uses with the [JVM flag](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options) `-Djna.tmpdir=` and you can configure the path that `libffi` uses for its temporary files by setting the `LIBFFI_TMPDIR` environment variable. Future versions of {{es}} may need additional configuration, so you should prefer to set `ES_TMPDIR` wherever possible. + +::::{note} +{{es}} does not remove its temporary directory. You should remove leftover temporary directories while {{es}} is not running. It is best to do this automatically, for instance on each reboot. If you are running on Linux, you can achieve this by using the [tmpfs](https://www.kernel.org/doc/html/latest/filesystems/tmpfs.md) file system. +:::: + + diff --git a/deploy-manage/deploy/self-managed/file-descriptors.md b/deploy-manage/deploy/self-managed/file-descriptors.md new file mode 100644 index 000000000..58c790201 --- /dev/null +++ b/deploy-manage/deploy/self-managed/file-descriptors.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/file-descriptors.html +--- + +# File Descriptors [file-descriptors] + +::::{note} +This is only relevant for Linux and macOS and can be safely ignored if running Elasticsearch on Windows. On Windows that JVM uses an [API](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858(v=vs.85).aspx) limited only by available resources. +:::: + + +Elasticsearch uses a lot of file descriptors or file handles. Running out of file descriptors can be disastrous and will most probably lead to data loss. Make sure to increase the limit on the number of open files descriptors for the user running Elasticsearch to 65,535 or higher. + +For the `.zip` and `.tar.gz` packages, set [`ulimit -n 65535`](setting-system-settings.md#ulimit) as root before starting Elasticsearch, or set `nofile` to `65535` in [`/etc/security/limits.conf`](setting-system-settings.md#limits.conf). + +On macOS, you must also pass the JVM option `-XX:-MaxFDLimit` to Elasticsearch in order for it to make use of the higher file descriptor limit. + +RPM and Debian packages already default the maximum number of file descriptors to 65535 and do not require further configuration. + +You can check the `max_file_descriptors` configured for each node using the [Nodes stats](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-stats.html) API, with: + +```console +GET _nodes/stats/process?filter_path=**.max_file_descriptors +``` + diff --git a/deploy-manage/deploy/self-managed/important-settings-configuration.md b/deploy-manage/deploy/self-managed/important-settings-configuration.md new file mode 100644 index 000000000..8f824593c --- /dev/null +++ b/deploy-manage/deploy/self-managed/important-settings-configuration.md @@ -0,0 +1,238 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html +--- + +# Important settings configuration [important-settings] + +{{es}} requires very little configuration to get started, but there are a number of items which **must** be considered before using your cluster in production: + +* [Path settings](#path-settings) +* [Cluster name setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-name) +* [Node name setting](#node-name) +* [Network host settings](#network.host) +* [Discovery settings](#discovery-settings) +* [Heap size settings](#heap-size-settings) +* [JVM heap dump path setting](#heap-dump-path) +* [GC logging settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#gc-logging) +* [Temporary directory settings](#es-tmpdir) +* [JVM fatal error log setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#error-file-path) +* [Cluster backups](#important-settings-backups) + +Our [{{ecloud}}](https://cloud.elastic.co/registration?page=docs&placement=docs-body) service configures these items automatically, making your cluster production-ready by default. + + +## Path settings [path-settings] + +{{es}} writes the data you index to indices and data streams to a `data` directory. {{es}} writes its own application logs, which contain information about cluster health and operations, to a `logs` directory. + +For [macOS `.tar.gz`](install-elasticsearch-from-archive-on-linux-macos.md), [Linux `.tar.gz`](install-elasticsearch-from-archive-on-linux-macos.md), and [Windows `.zip`](install-elasticsearch-with-zip-on-windows.md) installations, `data` and `logs` are subdirectories of `$ES_HOME` by default. However, files in `$ES_HOME` risk deletion during an upgrade. + +In production, we strongly recommend you set the `path.data` and `path.logs` in `elasticsearch.yml` to locations outside of `$ES_HOME`. [Docker](install-elasticsearch-with-docker.md), [Debian](install-elasticsearch-with-debian-package.md), and [RPM](install-elasticsearch-with-rpm.md) installations write data and log to locations outside of `$ES_HOME` by default. + +Supported `path.data` and `path.logs` values vary by platform: + +:::::::{tab-set} + +::::::{tab-item} Unix-like systems +Linux and macOS installations support Unix-style paths: + +```yaml +path: + data: /var/data/elasticsearch + logs: /var/log/elasticsearch +``` +:::::: + +::::::{tab-item} Windows +Windows installations support DOS paths with escaped backslashes: + +```yaml +path: + data: "C:\\Elastic\\Elasticsearch\\data" + logs: "C:\\Elastic\\Elasticsearch\\logs" +``` +:::::: + +::::::: +::::{warning} +Don’t modify anything within the data directory or run processes that might interfere with its contents. If something other than {{es}} modifies the contents of the data directory, then {{es}} may fail, reporting corruption or other data inconsistencies, or may appear to work correctly having silently lost some of your data. Don’t attempt to take filesystem backups of the data directory; there is no supported way to restore such a backup. Instead, use [Snapshot and restore](../../tools/snapshot-and-restore.md) to take backups safely. Don’t run virus scanners on the data directory. A virus scanner can prevent {{es}} from working correctly and may modify the contents of the data directory. The data directory contains no executables so a virus scan will only find false positives. +:::: + + +Elasticsearch offers a deprecated setting that allows you to specify multiple paths in `path.data`. To learn about this setting, and how to migrate away from it, refer to [Multiple data paths](https://www.elastic.co/guide/en/elasticsearch/reference/current/path-settings-overview.html#multiple-data-paths). + + +## Cluster name setting [_cluster_name_setting] + +A node can only join a cluster when it shares its `cluster.name` with all the other nodes in the cluster. The default name is `elasticsearch`, but you should change it to an appropriate name that describes the purpose of the cluster. + +```yaml +cluster.name: logging-prod +``` + +::::{important} +Do not reuse the same cluster names in different environments. Otherwise, nodes might join the wrong cluster. +:::: + + +::::{note} +Changing the name of a cluster requires a [full cluster restart](../../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-full). +:::: + + + +## Node name setting [node-name] + +{{es}} uses `node.name` as a human-readable identifier for a particular instance of {{es}}. This name is included in the response of many APIs. The node name defaults to the hostname of the machine when {{es}} starts, but can be configured explicitly in `elasticsearch.yml`: + +```yaml +node.name: prod-data-2 +``` + + +## Network host setting [network.host] + +By default, {{es}} only binds to loopback addresses such as `127.0.0.1` and `[::1]`. This is sufficient to run a cluster of one or more nodes on a single server for development and testing, but a [resilient production cluster](../../production-guidance/availability-and-resilience.md) must involve nodes on other servers. There are many [network settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html) but usually all you need to configure is `network.host`: + +```yaml +network.host: 192.168.1.10 +``` + +::::{important} +When you provide a value for `network.host`, {{es}} assumes that you are moving from development mode to production mode, and upgrades a number of system startup checks from warnings to exceptions. See the differences between [development and production modes](important-system-configuration.md#dev-vs-prod). +:::: + + + +## Discovery and cluster formation settings [discovery-settings] + +Configure two important discovery and cluster formation settings before going to production so that nodes in the cluster can discover each other and elect a master node. + + +### `discovery.seed_hosts` [unicast.hosts] + +Out of the box, without any network configuration, {{es}} will bind to the available loopback addresses and scan local ports `9300` to `9305` to connect with other nodes running on the same server. This behavior provides an auto-clustering experience without having to do any configuration. + +When you want to form a cluster with nodes on other hosts, use the [static](configure-elasticsearch.md#static-cluster-setting) `discovery.seed_hosts` setting. This setting provides a list of other nodes in the cluster that are master-eligible and likely to be live and contactable to seed the [discovery process](../../distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md). This setting accepts a YAML sequence or array of the addresses of all the master-eligible nodes in the cluster. Each address can be either an IP address or a hostname that resolves to one or more IP addresses via DNS. + +```yaml +discovery.seed_hosts: + - 192.168.1.10:9300 + - 192.168.1.11 <1> + - seeds.mydomain.com <2> + - [0:0:0:0:0:ffff:c0a8:10c]:9301 <3> +``` + +1. The port is optional and defaults to `9300`, but can be [overridden](../../distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md#built-in-hosts-providers). +2. If a hostname resolves to multiple IP addresses, the node will attempt to discover other nodes at all resolved addresses. +3. IPv6 addresses must be enclosed in square brackets. + + +If your master-eligible nodes do not have fixed names or addresses, use an [alternative hosts provider](../../distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md#built-in-hosts-providers) to find their addresses dynamically. + + +### `cluster.initial_master_nodes` [initial_master_nodes] + +When you start an {{es}} cluster for the first time, a [cluster bootstrapping](../../distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md) step determines the set of master-eligible nodes whose votes are counted in the first election. In [development mode](bootstrap-checks.md#dev-vs-prod-mode), with no discovery settings configured, this step is performed automatically by the nodes themselves. + +Because auto-bootstrapping is [inherently unsafe](../../distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md), when starting a new cluster in production mode, you must explicitly list the master-eligible nodes whose votes should be counted in the very first election. You set this list using the `cluster.initial_master_nodes` setting on every master-eligible node. Do not configure this setting on master-ineligible nodes. + +::::{important} +After the cluster forms successfully for the first time, remove the `cluster.initial_master_nodes` setting from each node’s configuration and never set it again for this cluster. Do not configure this setting on nodes joining an existing cluster. Do not configure this setting on nodes which are restarting. Do not configure this setting when performing a full-cluster restart. See [Bootstrapping a cluster](../../distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md). +:::: + + +```yaml +discovery.seed_hosts: + - 192.168.1.10:9300 + - 192.168.1.11 + - seeds.mydomain.com + - [0:0:0:0:0:ffff:c0a8:10c]:9301 +cluster.initial_master_nodes: <1> + - master-node-a + - master-node-b + - master-node-c +``` + +1. Identify the initial master nodes by their [`node.name`](#node-name), which defaults to their hostname. Ensure that the value in `cluster.initial_master_nodes` matches the `node.name` exactly. If you use a fully-qualified domain name (FQDN) such as `master-node-a.example.com` for your node names, then you must use the FQDN in this list. Conversely, if `node.name` is a bare hostname without any trailing qualifiers, you must also omit the trailing qualifiers in `cluster.initial_master_nodes`. + + +See [bootstrapping a cluster](../../distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md) and [discovery and cluster formation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html). + + +## Heap size settings [heap-size-settings] + +By default, {{es}} automatically sets the JVM heap size based on a node’s [roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) and total memory. We recommend the default sizing for most production environments. + +If needed, you can override the default sizing by manually [setting the JVM heap size](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-heap-size). + + +## JVM heap dump path setting [heap-dump-path] + +By default, {{es}} configures the JVM to dump the heap on out of memory exceptions to the default data directory. On [RPM](install-elasticsearch-with-rpm.md) and [Debian](install-elasticsearch-with-debian-package.md) packages, the data directory is `/var/lib/elasticsearch`. On [Linux and MacOS](install-elasticsearch-from-archive-on-linux-macos.md) and [Windows](install-elasticsearch-with-zip-on-windows.md) distributions, the `data` directory is located under the root of the {{es}} installation. + +If this path is not suitable for receiving heap dumps, modify the `-XX:HeapDumpPath=...` entry in [`jvm.options`](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options): + +* If you specify a directory, the JVM will generate a filename for the heap dump based on the PID of the running instance. +* If you specify a fixed filename instead of a directory, the file must not exist when the JVM needs to perform a heap dump on an out of memory exception. Otherwise, the heap dump will fail. + + +## GC logging settings [_gc_logging_settings] + +By default, {{es}} enables garbage collection (GC) logs. These are configured in [`jvm.options`](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options) and output to the same default location as the {{es}} logs. The default configuration rotates the logs every 64 MB and can consume up to 2 GB of disk space. + +You can reconfigure JVM logging using the command line options described in [JEP 158: Unified JVM Logging](https://openjdk.java.net/jeps/158). Unless you change the default `jvm.options` file directly, the {{es}} default configuration is applied in addition to your own settings. To disable the default configuration, first disable logging by supplying the `-Xlog:disable` option, then supply your own command line options. This disables *all* JVM logging, so be sure to review the available options and enable everything that you require. + +To see further options not contained in the original JEP, see [Enable Logging with the JVM Unified Logging Framework](https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.md#enable-logging-with-the-jvm-unified-logging-framework). + + +### Examples [_examples] + +Change the default GC log output location to `/opt/my-app/gc.log` by creating `$ES_HOME/config/jvm.options.d/gc.options` with some sample options: + +```shell +# Turn off all previous logging configuratons +-Xlog:disable + +# Default settings from JEP 158, but with `utctime` instead of `uptime` to match the next line +-Xlog:all=warning:stderr:utctime,level,tags + +# Enable GC logging to a custom location with a variety of options +-Xlog:gc*,gc+age=trace,safepoint:file=/opt/my-app/gc.log:utctime,level,pid,tags:filecount=32,filesize=64m +``` + +Configure an {{es}} [Docker container](install-elasticsearch-with-docker.md) to send GC debug logs to standard error (`stderr`). This lets the container orchestrator handle the output. If using the `ES_JAVA_OPTS` environment variable, specify: + +```sh +MY_OPTS="-Xlog:disable -Xlog:all=warning:stderr:utctime,level,tags -Xlog:gc=debug:stderr:utctime" +docker run -e ES_JAVA_OPTS="$MY_OPTS" # etc +``` + + +## Temporary directory settings [es-tmpdir] + +By default, {{es}} uses a private temporary directory that the startup script creates immediately below the system temporary directory. + +On some Linux distributions, a system utility will clean files and directories from `/tmp` if they have not been recently accessed. This behavior can lead to the private temporary directory being removed while {{es}} is running if features that require the temporary directory are not used for a long time. Removing the private temporary directory causes problems if a feature that requires this directory is subsequently used. + +If you install {{es}} using the `.deb` or `.rpm` packages and run it under `systemd`, the private temporary directory that {{es}} uses is excluded from periodic cleanup. + +If you intend to run the `.tar.gz` distribution on Linux or MacOS for an extended period, consider creating a dedicated temporary directory for {{es}} that is not under a path that will have old files and directories cleaned from it. This directory should have permissions set so that only the user that {{es}} runs as can access it. Then, set the `$ES_TMPDIR` environment variable to point to this directory before starting {{es}}. + + +## JVM fatal error log setting [_jvm_fatal_error_log_setting] + +By default, {{es}} configures the JVM to write fatal error logs to the default logging directory. On [RPM](install-elasticsearch-with-rpm.md) and [Debian](install-elasticsearch-with-debian-package.md) packages, this directory is `/var/log/elasticsearch`. On [Linux and MacOS](install-elasticsearch-from-archive-on-linux-macos.md) and [Windows](install-elasticsearch-with-zip-on-windows.md) distributions, the `logs` directory is located under the root of the {{es}} installation. + +These are logs produced by the JVM when it encounters a fatal error, such as a segmentation fault. If this path is not suitable for receiving logs, modify the `-XX:ErrorFile=...` entry in [`jvm.options`](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options). + + +## Cluster backups [important-settings-backups] + +In a disaster, [snapshots](../../tools/snapshot-and-restore.md) can prevent permanent data loss. [{{slm-cap}}](../../tools/snapshot-and-restore/create-snapshots.md#automate-snapshots-slm) is the easiest way to take regular backups of your cluster. For more information, see [*Create a snapshot*](../../tools/snapshot-and-restore/create-snapshots.md). + +::::{warning} +**Taking a snapshot is the only reliable and supported way to back up a cluster.** You cannot back up an {{es}} cluster by making copies of the data directories of its nodes. There are no supported methods to restore any data from a filesystem-level backup. If you try to restore a cluster from such a backup, it may fail with reports of corruption or missing files or other data inconsistencies, or it may appear to have succeeded having silently lost some of your data. + +:::: diff --git a/deploy-manage/deploy/self-managed/important-system-configuration.md b/deploy-manage/deploy/self-managed/important-system-configuration.md new file mode 100644 index 000000000..a16ed9892 --- /dev/null +++ b/deploy-manage/deploy/self-managed/important-system-configuration.md @@ -0,0 +1,35 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/system-config.html +--- + +# Important System configuration [system-config] + +Ideally, {{es}} should run alone on a server and use all of the resources available to it. In order to do so, you need to configure your operating system to allow the user running {{es}} to access more resources than allowed by default. + +The following settings **must** be considered before going to production: + +* [Configure system settings](setting-system-settings.md) +* [Disable swapping](setup-configuration-memory.md) +* [Increase file descriptors](file-descriptors.md) +* [Ensure sufficient virtual memory](vm-max-map-count.md) +* [Ensure sufficient threads](max-number-of-threads.md) +* [JVM DNS cache settings](networkaddress-cache-ttl.md) +* [Temporary directory not mounted with `noexec`](executable-jna-tmpdir.md) +* [TCP retransmission timeout](system-config-tcpretries.md) + + +## Development mode vs production mode [dev-vs-prod] + +By default, {{es}} assumes that you are working in development mode. If any of the above settings are not configured correctly, a warning will be written to the log file, but you will be able to start and run your {{es}} node. + +As soon as you configure a network setting like `network.host`, {{es}} assumes that you are moving to production and will upgrade the above warnings to exceptions. These exceptions will prevent your {{es}} node from starting. This is an important safety measure to ensure that you will not lose data because of a malconfigured server. + + + + + + + + + diff --git a/deploy-manage/deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md b/deploy-manage/deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md new file mode 100644 index 000000000..a55645d67 --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md @@ -0,0 +1,332 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/targz.html +--- + +# Install Elasticsearch from archive on Linux or MacOS [targz] + +{{es}} is available as a `.tar.gz` archive for Linux and MacOS. + +This package contains both free and subscription features. [Start a 30-day trial](https://www.elastic.co/guide/en/elasticsearch/reference/current/license-settings.html) to try out all of the features. + +The latest stable version of {{es}} can be found on the [Download {{es}}](https://elastic.co/downloads/elasticsearch) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +::::{note} +{{es}} includes a bundled version of [OpenJDK](https://openjdk.java.net) from the JDK maintainers (GPLv2+CE). To use your own version of Java, see the [JVM version requirements](installing-elasticsearch.md#jvm-version) +:::: + + +## Download and install archive for Linux [install-linux] + +::::{warning} +Version 9.0.0-beta1 of {{es}} has not yet been released. The archive might not be available. +:::: + + +The Linux archive for {{es}} v9.0.0-beta1 can be downloaded and installed as follows: + +```sh +wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-linux-x86_64.tar.gz +wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-linux-x86_64.tar.gz.sha512 +shasum -a 512 -c elasticsearch-9.0.0-beta1-linux-x86_64.tar.gz.sha512 <1> +tar -xzf elasticsearch-9.0.0-beta1-linux-x86_64.tar.gz +cd elasticsearch-9.0.0-beta1/ <2> +``` + +1. Compares the SHA of the downloaded `.tar.gz` archive and the published checksum, which should output `elasticsearch-{{version}}-linux-x86_64.tar.gz: OK`. +2. This directory is known as `$ES_HOME`. + + + +## Download and install archive for MacOS [install-macos] + +::::{warning} +Version 9.0.0-beta1 of {{es}} has not yet been released. The archive might not be available. +:::: + + +::::{admonition} macOS Gatekeeper warnings +:class: important + +Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{es}} artifacts. If macOS displays a dialog when you first run {{es}} that interrupts it, then you need to take an action to allow it to run. + +To prevent Gatekeeper checks on the {{es}} files, run the following command on the downloaded .tar.gz archive or the directory to which was extracted: + +```sh +xattr -d -r com.apple.quarantine +``` + +Alternatively, you can add a security override by following the instructions in the *If you want to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491). + +:::: + + +The MacOS archive for {{es}} v9.0.0-beta1 can be downloaded and installed as follows: + +```sh +curl -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-darwin-x86_64.tar.gz +curl https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-darwin-x86_64.tar.gz.sha512 | shasum -a 512 -c - <1> +tar -xzf elasticsearch-9.0.0-beta1-darwin-x86_64.tar.gz +cd elasticsearch-9.0.0-beta1/ <2> +``` + +1. Compares the SHA of the downloaded `.tar.gz` archive and the published checksum, which should output `elasticsearch-{{version}}-darwin-x86_64.tar.gz: OK`. +2. This directory is known as `$ES_HOME`. + + + +## Enable automatic creation of system indices [targz-enable-indices] + +Some commercial features automatically create indices within {{es}}. By default, {{es}} is configured to allow automatic index creation, and no additional steps are required. However, if you have disabled automatic index creation in {{es}}, you must configure [`action.auto_create_index`](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#index-creation) in `elasticsearch.yml` to allow the commercial features to create the following indices: + +```yaml +action.auto_create_index: .monitoring*,.watches,.triggered_watches,.watcher-history*,.ml* +``` + +::::{important} +If you are using [Logstash](https://www.elastic.co/products/logstash) or [Beats](https://www.elastic.co/products/beats) then you will most likely require additional index names in your `action.auto_create_index` setting, and the exact value will depend on your local configuration. If you are unsure of the correct value for your environment, you may consider setting the value to `*` which will allow automatic creation of all indices. + +:::: + + + +## Run {{es}} from the command line [targz-running] + +Run the following command to start {{es}} from the command line: + +```sh +./bin/elasticsearch +``` + +When starting {{es}} for the first time, security features are enabled and configured by default. The following security configuration occurs automatically: + +* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser. +* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates. +* An enrollment token is generated for {{kib}}, which is valid for 30 minutes. + +The password for the `elastic` user and the enrollment token for {{kib}} are output to your terminal. + +We recommend storing the `elastic` password as an environment variable in your shell. Example: + +```sh +export ELASTIC_PASSWORD="your_password" +``` + +If you have password-protected the {{es}} keystore, you will be prompted to enter the keystore’s password. See [Secure settings](../../security/secure-settings.md) for more details. + +By default {{es}} prints its logs to the console (`stdout`) and to the `.log` file within the [logs directory](important-settings-configuration.md#path-settings). {{es}} logs some information while it is starting, but after it has finished initializing it will continue to run in the foreground and won’t log anything further until something happens that is worth recording. While {{es}} is running you can interact with it through its HTTP interface which is on port `9200` by default. + +To stop {{es}}, press `Ctrl-C`. + +::::{note} +All scripts packaged with {{es}} require a version of Bash that supports arrays and assume that Bash is available at `/bin/bash`. As such, Bash should be available at this path either directly or via a symbolic link. +:::: + + + +### Enroll nodes in an existing cluster [_enroll_nodes_in_an_existing_cluster] + +When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to localhost. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration. + +Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically. + +Additionally, only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need to set `transport.host` to a [supported value](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#network-interface-values) (such as uncommenting the suggested value of `0.0.0.0`), or an IP address that’s bound to an interface where other hosts can reach it. Refer to [transport settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings) for more information. + +To enroll new nodes in your cluster, create an enrollment token with the `elasticsearch-create-enrollment-token` tool on any existing node in your cluster. You can then start a new node with the `--enrollment-token` parameter so that it joins an existing cluster. + +1. In a separate terminal from where {{es}} is running, navigate to the directory where you installed {{es}} and run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool to generate an enrollment token for your new nodes. + + ```sh + bin/elasticsearch-create-enrollment-token -s node + ``` + + Copy the enrollment token, which you’ll use to enroll new nodes with your {{es}} cluster. + +2. From the installation directory of your new node, start {{es}} and pass the enrollment token with the `--enrollment-token` parameter. + + ```sh + bin/elasticsearch --enrollment-token + ``` + + {{es}} automatically generates certificates and keys in the following directory: + + ```sh + config/certs + ``` + +3. Repeat the previous step for any new nodes that you want to enroll. + + +## Check that Elasticsearch is running [_check_that_elasticsearch_is_running] + +You can test that your {{es}} node is running by sending an HTTPS request to port `9200` on `localhost`: + +```sh +curl --cacert $ES_HOME/config/certs/http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 <1> +``` + +1. Ensure that you use `https` in your call, or the request will fail.`--cacert` +: Path to the generated `http_ca.crt` certificate for the HTTP layer. + + + +The call returns a response like this: + +```js +{ + "name" : "Cp8oag6", + "cluster_name" : "elasticsearch", + "cluster_uuid" : "AT69_T_DTp-1qgIJlatQqA", + "version" : { + "number" : "9.0.0-SNAPSHOT", + "build_type" : "tar", + "build_hash" : "f27399d", + "build_flavor" : "default", + "build_date" : "2016-03-30T09:51:41.449Z", + "build_snapshot" : false, + "lucene_version" : "10.0.0", + "minimum_wire_compatibility_version" : "1.2.3", + "minimum_index_compatibility_version" : "1.2.3" + }, + "tagline" : "You Know, for Search" +} +``` + +Log printing to `stdout` can be disabled using the `-q` or `--quiet` option on the command line. + + +## Run as a daemon [setup-installation-daemon] + +To run Elasticsearch as a daemon, specify `-d` on the command line, and record the process ID in a file using the `-p` option: + +```sh +./bin/elasticsearch -d -p pid +``` + +If you have password-protected the {{es}} keystore, you will be prompted to enter the keystore’s password. See [Secure settings](../../security/secure-settings.md) for more details. + +Log messages can be found in the `$ES_HOME/logs/` directory. + +To shut down Elasticsearch, kill the process ID recorded in the `pid` file: + +```sh +pkill -F pid +``` + +::::{note} +The {{es}} `.tar.gz` package does not include the `systemd` module. To manage {{es}} as a service, use the [Debian](../../maintenance/start-stop-services/start-stop-elasticsearch.md#start-deb) or [RPM](../../maintenance/start-stop-services/start-stop-elasticsearch.md#start-rpm) package instead. +:::: + + + +## Configure {{es}} on the command line [targz-configuring] + +{{es}} loads its configuration from the `$ES_HOME/config/elasticsearch.yml` file by default. The format of this config file is explained in [*Configuring {{es}}*](configure-elasticsearch.md). + +Any settings that can be specified in the config file can also be specified on the command line, using the `-E` syntax as follows: + +```sh +./bin/elasticsearch -d -Ecluster.name=my_cluster -Enode.name=node_1 +``` + +::::{tip} +Typically, any cluster-wide settings (like `cluster.name`) should be added to the `elasticsearch.yml` config file, while any node-specific settings such as `node.name` could be specified on the command line. +:::: + + + +## Connect clients to {{es}} [_connect_clients_to_es] + +When you start {{es}} for the first time, TLS is configured automatically for the HTTP layer. A CA certificate is generated and stored on disk at: + +```sh +$ES_HOME/config/certs/http_ca.crt +``` + +The hex-encoded SHA-256 fingerprint of this certificate is also output to the terminal. Any clients that connect to {{es}}, such as the [{{es}} Clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html), {{beats}}, standalone {{agent}}s, and {{ls}} must validate that they trust the certificate that {{es}} uses for HTTPS. {{fleet-server}} and {{fleet}}-managed {{agent}}s are automatically configured to trust the CA certificate. Other clients can establish trust by using either the fingerprint of the CA certificate or the CA certificate itself. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate. You can also copy the CA certificate to your machine and configure your client to use it. + + +#### Use the CA fingerprint [_use_the_ca_fingerprint] + +Copy the fingerprint value that’s output to your terminal when {{es}} starts, and configure your client to use this fingerprint to establish trust when it connects to {{es}}. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate by running the following command. The path is to the auto-generated CA certificate for the HTTP layer. + +```sh +openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt +``` + +The command returns the security certificate, including the fingerprint. The `issuer` should be `Elasticsearch security auto-configuration HTTP CA`. + +```sh +issuer= /CN=Elasticsearch security auto-configuration HTTP CA +SHA256 Fingerprint= +``` + + +#### Use the CA certificate [_use_the_ca_certificate] + +If your library doesn’t support a method of validating the fingerprint, the auto-generated CA certificate is created in the following directory on each {{es}} node: + +```sh +$ES_HOME/config/certs/http_ca.crt +``` + +Copy the `http_ca.crt` file to your machine and configure your client to use this certificate to establish trust when it connects to {{es}}. + + +## Directory layout of archives [targz-layout] + +The archive distributions are entirely self-contained. All files and directories are, by default, contained within `$ES_HOME` — the directory created when unpacking the archive. + +This is very convenient because you don’t have to create any directories to start using {{es}}, and uninstalling {{es}} is as easy as removing the `$ES_HOME` directory. However, it is advisable to change the default locations of the config directory, the data directory, and the logs directory so that you do not delete important data later on. + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | {{es}} home directory or `$ES_HOME` | Directory created by unpacking the archive | | +| bin | Binary scripts including `elasticsearch` to start a node and `elasticsearch-plugin` to install plugins | `$ES_HOME/bin` | | +| conf | Configuration files including `elasticsearch.yml` | `$ES_HOME/config` | `[ES_PATH_CONF](configure-elasticsearch.md#config-files-location)` | +| conf | Generated TLS keys and certificates for the transport and HTTP layer. | `$ES_HOME/config/certs` | | +| data | The location of the data files of each index / shard allocated on the node. | `$ES_HOME/data` | `path.data` | +| logs | Log files location. | `$ES_HOME/logs` | `path.logs` | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `$ES_HOME/plugins` | | +| repo | Shared file system repository locations. Can hold multiple locations. A file system repository can be placed in to any subdirectory of any directory specified here. | Not configured | `path.repo` | + +### Security certificates and keys [_security_certificates_and_keys] + +When you install {{es}}, the following certificates and keys are generated in the {{es}} configuration directory, which are used to connect a {{kib}} instance to your secured {{es}} cluster and to encrypt internode communication. The files are listed here for reference. + +`http_ca.crt` +: The CA certificate that is used to sign the certificates for the HTTP layer of this {{es}} cluster. + +`http.p12` +: Keystore that contains the key and certificate for the HTTP layer for this node. + +`transport.p12` +: Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster. + +`http.p12` and `transport.p12` are password-protected PKCS#12 keystores. {{es}} stores the passwords for these keystores as [secure settings](../../security/secure-settings.md). To retrieve the passwords so that you can inspect or change the keystore contents, use the [`bin/elasticsearch-keystore`](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-keystore.html) tool. + +Use the following command to retrieve the password for `http.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.http.ssl.keystore.secure_password +``` + +Use the following command to retrieve the password for `transport.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password +``` + + + +## Next steps [_next_steps] + +You now have a test {{es}} environment set up. Before you start serious development or go into production with {{es}}, you must do some additional setup: + +* Learn how to [configure Elasticsearch](configure-elasticsearch.md). +* Configure [important Elasticsearch settings](important-settings-configuration.md). +* Configure [important system settings](important-system-configuration.md). diff --git a/deploy-manage/deploy/self-managed/install-elasticsearch-with-debian-package.md b/deploy-manage/deploy/self-managed/install-elasticsearch-with-debian-package.md new file mode 100644 index 000000000..8a0050869 --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-elasticsearch-with-debian-package.md @@ -0,0 +1,365 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/deb.html +--- + +# Install Elasticsearch with Debian Package [deb] + +The Debian package for Elasticsearch can be [downloaded from our website](#install-deb) or from our [APT repository](#deb-repo). It can be used to install Elasticsearch on any Debian-based system such as Debian and Ubuntu. + +This package contains both free and subscription features. [Start a 30-day trial](https://www.elastic.co/guide/en/elasticsearch/reference/current/license-settings.html) to try out all of the features. + +The latest stable version of Elasticsearch can be found on the [Download Elasticsearch](https://elastic.co/downloads/elasticsearch) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +::::{note} +Elasticsearch includes a bundled version of [OpenJDK](https://openjdk.java.net) from the JDK maintainers (GPLv2+CE). To use your own version of Java, see the [JVM version requirements](installing-elasticsearch.md#jvm-version) +:::: + + +## Import the Elasticsearch PGP Key [deb-key] + +We sign all of our packages with the Elasticsearch Signing Key (PGP key [D88E42B4](https://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88E42B4), available from [https://pgp.mit.edu](https://pgp.mit.edu)) with fingerprint: + +``` +4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4 +``` +Download and install the public signing key: + +```sh +wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg +``` + + +## Installing from the APT repository [deb-repo] + +::::{warning} +Version 9.0.0-beta1 of Elasticsearch has not yet been released. +:::: + + +You may need to install the `apt-transport-https` package on Debian before proceeding: + +```sh +sudo apt-get install apt-transport-https +``` + +Save the repository definition to `/etc/apt/sources.list.d/elastic-9.x.list`: + +::::{note} +On systemd-based distributions, the installation scripts will attempt to set kernel parameters (e.g., `vm.max_map_count`); you can skip this by masking the systemd-sysctl.service unit. +:::: + + + +## Download and install the Debian package manually [install-deb] + +::::{warning} +Version 9.0.0-beta1 of Elasticsearch has not yet been released. The package might not be available. +:::: + + +The Debian package for Elasticsearch v9.0.0-beta1 can be downloaded from the website and installed as follows: + +```sh +wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-amd64.deb +wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-amd64.deb.sha512 +shasum -a 512 -c elasticsearch-9.0.0-beta1-amd64.deb.sha512 <1> +sudo dpkg -i elasticsearch-9.0.0-beta1-amd64.deb +``` + +1. Compares the SHA of the downloaded Debian package and the published checksum, which should output `elasticsearch-{{version}}-amd64.deb: OK`. + + + +## Start {{es}} with security enabled [deb-security-configuration] + +When installing {{es}}, security features are enabled and configured by default. When you install {{es}}, the following security configuration occurs automatically: + +* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser. +* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates. + +The password and certificate and keys are output to your terminal. You can reset the password for the `elastic` user with the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) command. + +We recommend storing the `elastic` password as an environment variable in your shell. For example: + +```sh +export ELASTIC_PASSWORD="your_password" +``` + +### Reconfigure a node to join an existing cluster [_reconfigure_a_node_to_join_an_existing_cluster] + +When you install {{es}}, the installation process configures a single-node cluster by default. If you want a node to join an existing cluster instead, generate an enrollment token on an existing node *before* you start the new node for the first time. + +1. On any node in your existing cluster, generate a node enrollment token: + + ```sh + /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node + ``` + +2. Copy the enrollment token, which is output to your terminal. +3. On your new {{es}} node, pass the enrollment token as a parameter to the `elasticsearch-reconfigure-node` tool: + + ```sh + /usr/share/elasticsearch/bin/elasticsearch-reconfigure-node --enrollment-token + ``` + + {{es}} is now configured to join the existing cluster. + +4. [Start your new node using `systemd`](#deb-running-systemd). + + + +## Enable automatic creation of system indices [deb-enable-indices] + +Some commercial features automatically create indices within {{es}}. By default, {{es}} is configured to allow automatic index creation, and no additional steps are required. However, if you have disabled automatic index creation in {{es}}, you must configure [`action.auto_create_index`](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#index-creation) in `elasticsearch.yml` to allow the commercial features to create the following indices: + +```yaml +action.auto_create_index: .monitoring*,.watches,.triggered_watches,.watcher-history*,.ml* +``` + +::::{important} +If you are using [Logstash](https://www.elastic.co/products/logstash) or [Beats](https://www.elastic.co/products/beats) then you will most likely require additional index names in your `action.auto_create_index` setting, and the exact value will depend on your local configuration. If you are unsure of the correct value for your environment, you may consider setting the value to `*` which will allow automatic creation of all indices. + +:::: + + + +## Running Elasticsearch with `systemd` [deb-running-systemd] + +To configure Elasticsearch to start automatically when the system boots up, run the following commands: + +```sh +sudo /bin/systemctl daemon-reload +sudo /bin/systemctl enable elasticsearch.service +``` + +Elasticsearch can be started and stopped as follows: + +```sh +sudo systemctl start elasticsearch.service +sudo systemctl stop elasticsearch.service +``` + +These commands provide no feedback as to whether Elasticsearch was started successfully or not. Instead, this information will be written in the log files located in `/var/log/elasticsearch/`. + +If you have password-protected your {{es}} keystore, you will need to provide `systemd` with the keystore password using a local file and systemd environment variables. This local file should be protected while it exists and may be safely deleted once Elasticsearch is up and running. + +```sh +echo "keystore_password" > /path/to/my_pwd_file.tmp +chmod 600 /path/to/my_pwd_file.tmp +sudo systemctl set-environment ES_KEYSTORE_PASSPHRASE_FILE=/path/to/my_pwd_file.tmp +sudo systemctl start elasticsearch.service +``` + +By default the Elasticsearch service doesn’t log information in the `systemd` journal. To enable `journalctl` logging, the `--quiet` option must be removed from the `ExecStart` command line in the `elasticsearch.service` file. + +When `systemd` logging is enabled, the logging information are available using the `journalctl` commands: + +To tail the journal: + +```sh +sudo journalctl -f +``` + +To list journal entries for the elasticsearch service: + +```sh +sudo journalctl --unit elasticsearch +``` + +To list journal entries for the elasticsearch service starting from a given time: + +```sh +sudo journalctl --unit elasticsearch --since "2016-10-30 18:17:16" +``` + +Check `man journalctl` or [https://www.freedesktop.org/software/systemd/man/journalctl.html](https://www.freedesktop.org/software/systemd/man/journalctl.md) for more command line options. + +::::{admonition} Startup timeouts with older `systemd` versions +:class: tip + +By default {{es}} sets the `TimeoutStartSec` parameter to `systemd` to `900s`. If you are running at least version 238 of `systemd` then {{es}} can automatically extend the startup timeout, and will do so repeatedly until startup is complete even if it takes longer than 900s. + +Versions of `systemd` prior to 238 do not support the timeout extension mechanism and will terminate the {{es}} process if it has not fully started up within the configured timeout. If this happens, {{es}} will report in its logs that it was shut down normally a short time after it started: + +```text +[2022-01-31T01:22:31,077][INFO ][o.e.n.Node ] [instance-0000000123] starting ... +... +[2022-01-31T01:37:15,077][INFO ][o.e.n.Node ] [instance-0000000123] stopping ... +``` + +However the `systemd` logs will report that the startup timed out: + +```text +Jan 31 01:22:30 debian systemd[1]: Starting Elasticsearch... +Jan 31 01:37:15 debian systemd[1]: elasticsearch.service: Start operation timed out. Terminating. +Jan 31 01:37:15 debian systemd[1]: elasticsearch.service: Main process exited, code=killed, status=15/TERM +Jan 31 01:37:15 debian systemd[1]: elasticsearch.service: Failed with result 'timeout'. +Jan 31 01:37:15 debian systemd[1]: Failed to start Elasticsearch. +``` + +To avoid this, upgrade your `systemd` to at least version 238. You can also temporarily work around the problem by extending the `TimeoutStartSec` parameter. + +:::: + + + +## Check that Elasticsearch is running [deb-check-running] + +You can test that your {{es}} node is running by sending an HTTPS request to port `9200` on `localhost`: + +```sh +curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 <1> +``` + +1. Ensure that you use `https` in your call, or the request will fail.`--cacert` +: Path to the generated `http_ca.crt` certificate for the HTTP layer. + + + +The call returns a response like this: + +```js +{ + "name" : "Cp8oag6", + "cluster_name" : "elasticsearch", + "cluster_uuid" : "AT69_T_DTp-1qgIJlatQqA", + "version" : { + "number" : "9.0.0-SNAPSHOT", + "build_type" : "tar", + "build_hash" : "f27399d", + "build_flavor" : "default", + "build_date" : "2016-03-30T09:51:41.449Z", + "build_snapshot" : false, + "lucene_version" : "10.0.0", + "minimum_wire_compatibility_version" : "1.2.3", + "minimum_index_compatibility_version" : "1.2.3" + }, + "tagline" : "You Know, for Search" +} +``` + + +## Configuring Elasticsearch [deb-configuring] + +The `/etc/elasticsearch` directory contains the default runtime configuration for {{es}}. The ownership of this directory and all contained files are set to `root:elasticsearch` on package installations. + +The `setgid` flag applies group permissions on the `/etc/elasticsearch` directory to ensure that {{es}} can read any contained files and subdirectories. All files and subdirectories inherit the `root:elasticsearch` ownership. Running commands from this directory or any subdirectories, such as the [elasticsearch-keystore tool](../../security/secure-settings.md), requires `root:elasticsearch` permissions. + +Elasticsearch loads its configuration from the `/etc/elasticsearch/elasticsearch.yml` file by default. The format of this config file is explained in [*Configuring {{es}}*](configure-elasticsearch.md). + +The Debian package also has a system configuration file (`/etc/default/elasticsearch`), which allows you to set the following parameters: + +`ES_JAVA_HOME` +: Set a custom Java path to be used. + +`ES_PATH_CONF` +: Configuration file directory (which needs to include `elasticsearch.yml`, `jvm.options`, and `log4j2.properties` files); defaults to `/etc/elasticsearch`. + +`ES_JAVA_OPTS` +: Any additional JVM system properties you may want to apply. + +`RESTART_ON_UPGRADE` +: Configure restart on package upgrade, defaults to `false`. This means you will have to restart your Elasticsearch instance after installing a package manually. The reason for this is to ensure, that upgrades in a cluster do not result in a continuous shard reallocation resulting in high network traffic and reducing the response times of your cluster. + +::::{note} +Distributions that use `systemd` require that system resource limits be configured via `systemd` rather than via the `/etc/sysconfig/elasticsearch` file. See [Systemd configuration](setting-system-settings.md#systemd) for more information. +:::: + + + +## Connect clients to {{es}} [_connect_clients_to_es_3] + +When you start {{es}} for the first time, TLS is configured automatically for the HTTP layer. A CA certificate is generated and stored on disk at: + +```sh +/etc/elasticsearch/certs/http_ca.crt +``` + +The hex-encoded SHA-256 fingerprint of this certificate is also output to the terminal. Any clients that connect to {{es}}, such as the [{{es}} Clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html), {{beats}}, standalone {{agent}}s, and {{ls}} must validate that they trust the certificate that {{es}} uses for HTTPS. {{fleet-server}} and {{fleet}}-managed {{agent}}s are automatically configured to trust the CA certificate. Other clients can establish trust by using either the fingerprint of the CA certificate or the CA certificate itself. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate. You can also copy the CA certificate to your machine and configure your client to use it. + + +#### Use the CA fingerprint [_use_the_ca_fingerprint_3] + +Copy the fingerprint value that’s output to your terminal when {{es}} starts, and configure your client to use this fingerprint to establish trust when it connects to {{es}}. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate by running the following command. The path is to the auto-generated CA certificate for the HTTP layer. + +```sh +openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt +``` + +The command returns the security certificate, including the fingerprint. The `issuer` should be `Elasticsearch security auto-configuration HTTP CA`. + +```sh +issuer= /CN=Elasticsearch security auto-configuration HTTP CA +SHA256 Fingerprint= +``` + + +#### Use the CA certificate [_use_the_ca_certificate_3] + +If your library doesn’t support a method of validating the fingerprint, the auto-generated CA certificate is created in the following directory on each {{es}} node: + +```sh +/etc/elasticsearch/certs/http_ca.crt +``` + +Copy the `http_ca.crt` file to your machine and configure your client to use this certificate to establish trust when it connects to {{es}}. + + +## Directory layout of Debian package [deb-layout] + +The Debian package places config files, logs, and the data directory in the appropriate locations for a Debian-based system: + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | Elasticsearch home directory or `$ES_HOME` | `/usr/share/elasticsearch` | | +| bin | Binary scripts including `elasticsearch` to start a node and `elasticsearch-plugin` to install plugins | `/usr/share/elasticsearch/bin` | | +| conf | Configuration files including `elasticsearch.yml` | `/etc/elasticsearch` | `[ES_PATH_CONF](configure-elasticsearch.md#config-files-location)` | +| conf | Environment variables including heap size, file descriptors. | `/etc/default/elasticsearch` | | +| conf | Generated TLS keys and certificates for the transport and http layer. | `/etc/elasticsearch/certs` | | +| data | The location of the data files of each index / shard allocated on the node. | `/var/lib/elasticsearch` | `path.data` | +| jdk | The bundled Java Development Kit used to run Elasticsearch. Can be overridden by setting the `ES_JAVA_HOME` environment variable in `/etc/default/elasticsearch`. | `/usr/share/elasticsearch/jdk` | | +| logs | Log files location. | `/var/log/elasticsearch` | `path.logs` | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `/usr/share/elasticsearch/plugins` | | +| repo | Shared file system repository locations. Can hold multiple locations. A file system repository can be placed in to any subdirectory of any directory specified here. | Not configured | `path.repo` | + +### Security certificates and keys [_security_certificates_and_keys_2] + +When you install {{es}}, the following certificates and keys are generated in the {{es}} configuration directory, which are used to connect a {{kib}} instance to your secured {{es}} cluster and to encrypt internode communication. The files are listed here for reference. + +`http_ca.crt` +: The CA certificate that is used to sign the certificates for the HTTP layer of this {{es}} cluster. + +`http.p12` +: Keystore that contains the key and certificate for the HTTP layer for this node. + +`transport.p12` +: Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster. + +`http.p12` and `transport.p12` are password-protected PKCS#12 keystores. {{es}} stores the passwords for these keystores as [secure settings](../../security/secure-settings.md). To retrieve the passwords so that you can inspect or change the keystore contents, use the [`bin/elasticsearch-keystore`](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-keystore.html) tool. + +Use the following command to retrieve the password for `http.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.http.ssl.keystore.secure_password +``` + +Use the following command to retrieve the password for `transport.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password +``` + + + +## Next steps [_next_steps_3] + +You now have a test {{es}} environment set up. Before you start serious development or go into production with {{es}}, you must do some additional setup: + +* Learn how to [configure Elasticsearch](configure-elasticsearch.md). +* Configure [important Elasticsearch settings](important-settings-configuration.md). +* Configure [important system settings](important-system-configuration.md). diff --git a/deploy-manage/deploy/self-managed/install-elasticsearch-with-docker.md b/deploy-manage/deploy/self-managed/install-elasticsearch-with-docker.md new file mode 100644 index 000000000..3bde5e1a0 --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-elasticsearch-with-docker.md @@ -0,0 +1,632 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html +--- + +# Install Elasticsearch with Docker [docker] + +Docker images for {{es}} are available from the Elastic Docker registry. A list of all published Docker images and tags is available at [www.docker.elastic.co](https://www.docker.elastic.co). The source code is in [GitHub](https://github.com/elastic/elasticsearch/blob/master/distribution/docker). + +This package contains both free and subscription features. [Start a 30-day trial](https://www.elastic.co/guide/en/elasticsearch/reference/current/license-settings.html) to try out all of the features. + +::::{tip} +If you just want to test {{es}} in local development, refer to [Run {{es}} locally](../../../solutions/search/get-started.md). Please note that this setup is not suitable for production environments. + +:::: + + +## Run {{es}} in Docker [docker-cli-run-dev-mode] + +Use Docker commands to start a single-node {{es}} cluster for development or testing. You can then run additional Docker commands to add nodes to the test cluster or run {{kib}}. + +::::{tip} +This setup doesn’t run multiple {{es}} nodes or {{kib}} by default. To create a multi-node cluster with {{kib}}, use Docker Compose instead. See [Start a multi-node cluster with Docker Compose](#docker-compose-file). +:::: + + +### Hardened Docker images [docker-wolfi-hardened-image] + +You can also use the hardened [Wolfi](https://wolfi.dev/) image for additional security. Using Wolfi images requires Docker version 20.10.10 or higher. + +To use the Wolfi image, append `-wolfi` to the image tag in the Docker command. + +For example: + +```sh +docker pull docker.elastic.co/elasticsearch/elasticsearch-wolfi:9.0.0-beta1 +``` + + +### Start a single-node cluster [_start_a_single_node_cluster] + +1. Install Docker. Visit [Get Docker](https://docs.docker.com/get-docker/) to install Docker for your environment. + + If using Docker Desktop, make sure to allocate at least 4GB of memory. You can adjust memory usage in Docker Desktop by going to **Settings > Resources**. + +2. Create a new docker network. + + ```sh + docker network create elastic + ``` + +3. Pull the {{es}} Docker image. + + ::::{warning} + Version 9.0.0-beta1 has not yet been released. No Docker image is currently available for {{es}} 9.0.0-beta1. + :::: + + + ```sh + docker pull docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + +4. Optional: Install [Cosign](https://docs.sigstore.dev/cosign/system_config/installation/) for your environment. Then use Cosign to verify the {{es}} image’s signature. + + $$$docker-verify-signature$$$ + + ```sh + wget https://artifacts.elastic.co/cosign.pub + cosign verify --key cosign.pub docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + + The `cosign` command prints the check results and the signature payload in JSON format: + + ```sh + Verification for docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 -- + The following checks were performed on each of these signatures: + - The cosign claims were validated + - Existence of the claims in the transparency log was verified offline + - The signatures were verified against the specified public key + ``` + +5. Start an {{es}} container. + + ```sh + docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + + ::::{tip} + Use the `-m` flag to set a memory limit for the container. This removes the need to [manually set the JVM size](#docker-set-heap-size). + :::: + + + {{ml-cap}} features such as [semantic search with ELSER](../../../solutions/search/vector/sparse-vector-elser.md) require a larger container with more than 1GB of memory. If you intend to use the {{ml}} capabilities, then start the container with this command: + + ```sh + docker run --name es01 --net elastic -p 9200:9200 -it -m 6GB -e "xpack.ml.use_auto_machine_memory_percent=true" docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + + The command prints the `elastic` user password and an enrollment token for {{kib}}. + +6. Copy the generated `elastic` password and enrollment token. These credentials are only shown when you start {{es}} for the first time. You can regenerate the credentials using the following commands. + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana + ``` + + We recommend storing the `elastic` password as an environment variable in your shell. Example: + + ```sh + export ELASTIC_PASSWORD="your_password" + ``` + +7. Copy the `http_ca.crt` SSL certificate from the container to your local machine. + + ```sh + docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt . + ``` + +8. Make a REST API call to {{es}} to ensure the {{es}} container is running. + + ```sh + curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 + ``` + + + +### Add more nodes [_add_more_nodes] + +1. Use an existing node to generate a enrollment token for the new node. + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node + ``` + + The enrollment token is valid for 30 minutes. + +2. Start a new {{es}} container. Include the enrollment token as an environment variable. + + ```sh + docker run -e ENROLLMENT_TOKEN="" --name es02 --net elastic -it -m 1GB docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + +3. Call the [cat nodes API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-nodes.html) to verify the node was added to the cluster. + + ```sh + curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200/_cat/nodes + ``` + + + +### Run {{kib}} [run-kibana-docker] + +1. Pull the {{kib}} Docker image. + + ::::{warning} + Version 9.0.0-beta1 has not yet been released. No Docker image is currently available for {{kib}} 9.0.0-beta1. + :::: + + + ```sh + docker pull docker.elastic.co/kibana/kibana:9.0.0-beta1 + ``` + +2. Optional: Verify the {{kib}} image’s signature. + + ```sh + wget https://artifacts.elastic.co/cosign.pub + cosign verify --key cosign.pub docker.elastic.co/kibana/kibana:9.0.0-beta1 + ``` + +3. Start a {{kib}} container. + + ```sh + docker run --name kib01 --net elastic -p 5601:5601 docker.elastic.co/kibana/kibana:9.0.0-beta1 + ``` + +4. When {{kib}} starts, it outputs a unique generated link to the terminal. To access {{kib}}, open this link in a web browser. +5. In your browser, enter the enrollment token that was generated when you started {{es}}. + + To regenerate the token, run: + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana + ``` + +6. Log in to {{kib}} as the `elastic` user with the password that was generated when you started {{es}}. + + To regenerate the password, run: + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic + ``` + + + +### Remove containers [remove-containers-docker] + +To remove the containers and their network, run: + +```sh +# Remove the Elastic network +docker network rm elastic + +# Remove {es} containers +docker rm es01 +docker rm es02 + +# Remove the {kib} container +docker rm kib01 +``` + + +### Next steps [_next_steps_5] + +You now have a test {{es}} environment set up. Before you start serious development or go into production with {{es}}, review the [requirements and recommendations](#docker-prod-prerequisites) to apply when running {{es}} in Docker in production. + + + +## Start a multi-node cluster with Docker Compose [docker-compose-file] + +Use Docker Compose to start a three-node {{es}} cluster with {{kib}}. Docker Compose lets you start multiple containers with a single command. + +### Configure and start the cluster [_configure_and_start_the_cluster] + +1. Install Docker Compose. Visit the [Docker Compose docs](https://docs.docker.com/compose/install/) to install Docker Compose for your environment. + + If you’re using Docker Desktop, Docker Compose is installed automatically. Make sure to allocate at least 4GB of memory to Docker Desktop. You can adjust memory usage in Docker Desktop by going to **Settings > Resources**. + +2. Create or navigate to an empty directory for the project. +3. Download and save the following files in the project directory: + + * [`.env`](https://github.com/elastic/elasticsearch/blob/master/docs/reference/setup/install/docker/.env) + * [`docker-compose.yml`](https://github.com/elastic/elasticsearch/blob/master/docs/reference/setup/install/docker/docker-compose.yml) + +4. In the `.env` file, specify a password for the `ELASTIC_PASSWORD` and `KIBANA_PASSWORD` variables. + + The passwords must be alphanumeric and can’t contain special characters, such as `!` or `@`. The bash script included in the `docker-compose.yml` file only works with alphanumeric characters. Example: + + ```txt + # Password for the 'elastic' user (at least 6 characters) + ELASTIC_PASSWORD=changeme + + # Password for the 'kibana_system' user (at least 6 characters) + KIBANA_PASSWORD=changeme + ... + ``` + +5. In the `.env` file, set `STACK_VERSION` to the current {{stack}} version. + + ```txt + ... + # Version of Elastic products + STACK_VERSION=9.0.0-beta1 + ... + ``` + +6. By default, the Docker Compose configuration exposes port `9200` on all network interfaces. + + To avoid exposing port `9200` to external hosts, set `ES_PORT` to `127.0.0.1:9200` in the `.env` file. This ensures {{es}} is only accessible from the host machine. + + ```txt + ... + # Port to expose Elasticsearch HTTP API to the host + #ES_PORT=9200 + ES_PORT=127.0.0.1:9200 + ... + ``` + +7. To start the cluster, run the following command from the project directory. + + ```sh + docker-compose up -d + ``` + +8. After the cluster has started, open [http://localhost:5601](http://localhost:5601) in a web browser to access {{kib}}. +9. Log in to {{kib}} as the `elastic` user using the `ELASTIC_PASSWORD` you set earlier. + + +### Stop and remove the cluster [_stop_and_remove_the_cluster] + +To stop the cluster, run `docker-compose down`. The data in the Docker volumes is preserved and loaded when you restart the cluster with `docker-compose up`. + +```sh +docker-compose down +``` + +To delete the network, containers, and volumes when you stop the cluster, specify the `-v` option: + +```sh +docker-compose down -v +``` + + +### Next steps [_next_steps_6] + +You now have a test {{es}} environment set up. Before you start serious development or go into production with {{es}}, review the [requirements and recommendations](#docker-prod-prerequisites) to apply when running {{es}} in Docker in production. + + + +## Using the Docker images in production [docker-prod-prerequisites] + +The following requirements and recommendations apply when running {{es}} in Docker in production. + +### Set `vm.max_map_count` to at least `262144` [_set_vm_max_map_count_to_at_least_262144] + +The `vm.max_map_count` kernel setting must be set to at least `262144` for production use. + +How you set `vm.max_map_count` depends on your platform. + +#### Linux [_linux] + +To view the current value for the `vm.max_map_count` setting, run: + +```sh +grep vm.max_map_count /etc/sysctl.conf +vm.max_map_count=262144 +``` + +To apply the setting on a live system, run: + +```sh +sysctl -w vm.max_map_count=262144 +``` + +To permanently change the value for the `vm.max_map_count` setting, update the value in `/etc/sysctl.conf`. + + +#### macOS with [Docker for Mac](https://docs.docker.com/docker-for-mac) [_macos_with_docker_for_machttpsdocs_docker_comdocker_for_mac] + +The `vm.max_map_count` setting must be set within the xhyve virtual machine: + +1. From the command line, run: + + ```sh + screen ~/Library/Containers/com.docker.docker/Data/vms/0/tty + ``` + +2. Press enter and use `sysctl` to configure `vm.max_map_count`: + + ```sh + sysctl -w vm.max_map_count=262144 + ``` + +3. To exit the `screen` session, type `Ctrl a d`. + + +#### Windows and macOS with [Docker Desktop](https://www.docker.com/products/docker-desktop) [_windows_and_macos_with_docker_desktophttpswww_docker_comproductsdocker_desktop] + +The `vm.max_map_count` setting must be set via docker-machine: + +```sh +docker-machine ssh +sudo sysctl -w vm.max_map_count=262144 +``` + + +#### Windows with [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl) [_windows_with_docker_desktop_wsl_2_backendhttpsdocs_docker_comdocker_for_windowswsl] + +The `vm.max_map_count` setting must be set in the "docker-desktop" WSL instance before the {{es}} container will properly start. There are several ways to do this, depending on your version of Windows and your version of WSL. + +If you are on Windows 10 before version 22H2, or if you are on Windows 10 version 22H2 using the built-in version of WSL, you must either manually set it every time you restart Docker before starting your {{es}} container, or (if you do not wish to do so on every restart) you must globally set every WSL2 instance to have the `vm.max_map_count` changed. This is because these versions of WSL do not properly process the /etc/sysctl.conf file. + +To manually set it every time you reboot, you must run the following commands in a command prompt or PowerShell window every time you restart Docker: + +```sh +wsl -d docker-desktop -u root +sysctl -w vm.max_map_count=262144 +``` + +If you are on these versions of WSL and you do not want to have to run those commands every time you restart Docker, you can globally change every WSL distribution with this setting by modifying your %USERPROFILE%\.wslconfig as follows: + +```text +[wsl2] +kernelCommandLine = "sysctl.vm.max_map_count=262144" +``` + +This will cause all WSL2 VMs to have that setting assigned when they start. + +If you are on Windows 11, or Windows 10 version 22H2 and have installed the Microsoft Store version of WSL, you can modify the /etc/sysctl.conf within the "docker-desktop" WSL distribution, perhaps with commands like this: + +```sh +wsl -d docker-desktop -u root +vi /etc/sysctl.conf +``` + +and appending a line which reads: + +```text +vm.max_map_count = 262144 +``` + + + +### Configuration files must be readable by the `elasticsearch` user [_configuration_files_must_be_readable_by_the_elasticsearch_user] + +By default, {{es}} runs inside the container as user `elasticsearch` using uid:gid `1000:0`. + +::::{important} +One exception is [Openshift](https://docs.openshift.com/container-platform/3.6/creating_images/guidelines.md#openshift-specific-guidelines), which runs containers using an arbitrarily assigned user ID. Openshift presents persistent volumes with the gid set to `0`, which works without any adjustments. +:::: + + +If you are bind-mounting a local directory or file, it must be readable by the `elasticsearch` user. In addition, this user must have write access to the [config, data and log dirs](important-settings-configuration.md#path-settings) ({{es}} needs write access to the `config` directory so that it can generate a keystore). A good strategy is to grant group access to gid `0` for the local directory. + +For example, to prepare a local directory for storing data through a bind-mount: + +```sh +mkdir esdatadir +chmod g+rwx esdatadir +chgrp 0 esdatadir +``` + +You can also run an {{es}} container using both a custom UID and GID. You must ensure that file permissions will not prevent {{es}} from executing. You can use one of two options: + +* Bind-mount the `config`, `data` and `logs` directories. If you intend to install plugins and prefer not to [create a custom Docker image](#_c_customized_image), you must also bind-mount the `plugins` directory. +* Pass the `--group-add 0` command line option to `docker run`. This ensures that the user under which {{es}} is running is also a member of the `root` (GID 0) group inside the container. + + +### Increase ulimits for nofile and nproc [_increase_ulimits_for_nofile_and_nproc] + +Increased ulimits for [nofile](setting-system-settings.md) and [nproc](max-number-threads-check.md) must be available for the {{es}} containers. Verify the [init system](https://github.com/moby/moby/tree/ea4d1243953e6b652082305a9c3cda8656edab26/contrib/init) for the Docker daemon sets them to acceptable values. + +To check the Docker daemon defaults for ulimits, run: + +```sh +docker run --rm docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 /bin/bash -c 'ulimit -Hn && ulimit -Sn && ulimit -Hu && ulimit -Su' +``` + +If needed, adjust them in the Daemon or override them per container. For example, when using `docker run`, set: + +```sh +--ulimit nofile=65535:65535 +``` + + +### Disable swapping [_disable_swapping] + +Swapping needs to be disabled for performance and node stability. For information about ways to do this, see [Disable swapping](setup-configuration-memory.md). + +If you opt for the `bootstrap.memory_lock: true` approach, you also need to define the `memlock: true` ulimit in the [Docker Daemon](https://docs.docker.com/engine/reference/commandline/dockerd/#default-ulimits), or explicitly set for the container as shown in the [sample compose file](#docker-compose-file). When using `docker run`, you can specify: + +```sh +-e "bootstrap.memory_lock=true" --ulimit memlock=-1:-1 +``` + + +### Randomize published ports [_randomize_published_ports] + +The image [exposes](https://docs.docker.com/engine/reference/builder/#/expose) TCP ports 9200 and 9300. For production clusters, randomizing the published ports with `--publish-all` is recommended, unless you are pinning one container per host. + + +### Manually set the heap size [docker-set-heap-size] + +By default, {{es}} automatically sizes JVM heap based on a nodes’s [roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) and the total memory available to the node’s container. We recommend this default sizing for most production environments. If needed, you can override default sizing by manually setting JVM heap size. + +To manually set the heap size in production, bind mount a [JVM options](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options) file under `/usr/share/elasticsearch/config/jvm.options.d` that includes your desired [heap size](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-heap-size) settings. + +For testing, you can also manually set the heap size using the `ES_JAVA_OPTS` environment variable. For example, to use 1GB, use the following command. + +```sh +docker run -e ES_JAVA_OPTS="-Xms1g -Xmx1g" -e ENROLLMENT_TOKEN="" --name es01 -p 9200:9200 --net elastic -it docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 +``` + +The `ES_JAVA_OPTS` variable overrides all other JVM options. We do not recommend using `ES_JAVA_OPTS` in production. + + +### Pin deployments to a specific image version [_pin_deployments_to_a_specific_image_version] + +Pin your deployments to a specific version of the {{es}} Docker image. For example `docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1`. + + +### Always bind data volumes [_always_bind_data_volumes] + +You should use a volume bound on `/usr/share/elasticsearch/data` for the following reasons: + +1. The data of your {{es}} node won’t be lost if the container is killed +2. {{es}} is I/O sensitive and the Docker storage driver is not ideal for fast I/O +3. It allows the use of advanced [Docker volume plugins](https://docs.docker.com/engine/extend/plugins/#volume-plugins) + + +### Avoid using `loop-lvm` mode [_avoid_using_loop_lvm_mode] + +If you are using the devicemapper storage driver, do not use the default `loop-lvm` mode. Configure docker-engine to use [direct-lvm](https://docs.docker.com/engine/userguide/storagedriver/device-mapper-driver/#configure-docker-with-devicemapper). + + +### Centralize your logs [_centralize_your_logs] + +Consider centralizing your logs by using a different [logging driver](https://docs.docker.com/engine/admin/logging/overview/). Also note that the default json-file logging driver is not ideally suited for production use. + + + +## Configuring {{es}} with Docker [docker-configuration-methods] + +When you run in Docker, the [{{es}} configuration files](configure-elasticsearch.md#config-files-location) are loaded from `/usr/share/elasticsearch/config/`. + +To use custom configuration files, you [bind-mount the files](#docker-config-bind-mount) over the configuration files in the image. + +You can set individual {{es}} configuration parameters using Docker environment variables. The [sample compose file](#docker-compose-file) and the [single-node example](#docker-cli-run-dev-mode) use this method. You can use the setting name directly as the environment variable name. If you cannot do this, for example because your orchestration platform forbids periods in environment variable names, then you can use an alternative style by converting the setting name as follows. + +1. Change the setting name to uppercase +2. Prefix it with `ES_SETTING_` +3. Escape any underscores (`_`) by duplicating them +4. Convert all periods (`.`) to underscores (`_`) + +For example, `-e bootstrap.memory_lock=true` becomes `-e ES_SETTING_BOOTSTRAP_MEMORY__LOCK=true`. + +You can use the contents of a file to set the value of the `ELASTIC_PASSWORD` or `KEYSTORE_PASSWORD` environment variables, by suffixing the environment variable name with `_FILE`. This is useful for passing secrets such as passwords to {{es}} without specifying them directly. + +For example, to set the {{es}} bootstrap password from a file, you can bind mount the file and set the `ELASTIC_PASSWORD_FILE` environment variable to the mount location. If you mount the password file to `/run/secrets/bootstrapPassword.txt`, specify: + +```sh +-e ELASTIC_PASSWORD_FILE=/run/secrets/bootstrapPassword.txt +``` + +You can override the default command for the image to pass {{es}} configuration parameters as command line options. For example: + +```sh +docker run bin/elasticsearch -Ecluster.name=mynewclustername +``` + +While bind-mounting your configuration files is usually the preferred method in production, you can also [create a custom Docker image](#_c_customized_image) that contains your configuration. + +### Mounting {{es}} configuration files [docker-config-bind-mount] + +Create custom config files and bind-mount them over the corresponding files in the Docker image. For example, to bind-mount `custom_elasticsearch.yml` with `docker run`, specify: + +```sh +-v full_path_to/custom_elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml +``` + +If you bind-mount a custom `elasticsearch.yml` file, ensure it includes the `network.host: 0.0.0.0` setting. This setting ensures the node is reachable for HTTP and transport traffic, provided its ports are exposed. The Docker image’s built-in `elasticsearch.yml` file includes this setting by default. + +::::{important} +The container **runs {{es}} as user `elasticsearch` using uid:gid `1000:0`**. Bind mounted host directories and files must be accessible by this user, and the data and log directories must be writable by this user. +:::: + + + +### Create an encrypted {{es}} keystore [docker-keystore-bind-mount] + +By default, {{es}} will auto-generate a keystore file for [secure settings](../../security/secure-settings.md). This file is obfuscated but not encrypted. + +To encrypt your secure settings with a password and have them persist outside the container, use a `docker run` command to manually create the keystore instead. The command must: + +* Bind-mount the `config` directory. The command will create an `elasticsearch.keystore` file in this directory. To avoid errors, do not directly bind-mount the `elasticsearch.keystore` file. +* Use the `elasticsearch-keystore` tool with the `create -p` option. You’ll be prompted to enter a password for the keystore. + +For example: + +```sh +docker run -it --rm \ +-v full_path_to/config:/usr/share/elasticsearch/config \ +docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 \ +bin/elasticsearch-keystore create -p +``` + +You can also use a `docker run` command to add or update secure settings in the keystore. You’ll be prompted to enter the setting values. If the keystore is encrypted, you’ll also be prompted to enter the keystore password. + +```sh +docker run -it --rm \ +-v full_path_to/config:/usr/share/elasticsearch/config \ +docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 \ +bin/elasticsearch-keystore \ +add my.secure.setting \ +my.other.secure.setting +``` + +If you’ve already created the keystore and don’t need to update it, you can bind-mount the `elasticsearch.keystore` file directly. You can use the `KEYSTORE_PASSWORD` environment variable to provide the keystore password to the container at startup. For example, a `docker run` command might have the following options: + +```sh +-v full_path_to/config/elasticsearch.keystore:/usr/share/elasticsearch/config/elasticsearch.keystore +-e KEYSTORE_PASSWORD=mypassword +``` + + +### Using custom Docker images [_c_customized_image] + +In some environments, it might make more sense to prepare a custom image that contains your configuration. A `Dockerfile` to achieve this might be as simple as: + +```sh +FROM docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 +COPY --chown=elasticsearch:elasticsearch elasticsearch.yml /usr/share/elasticsearch/config/ +``` + +You could then build and run the image with: + +```sh +docker build --tag=elasticsearch-custom . +docker run -ti -v /usr/share/elasticsearch/data elasticsearch-custom +``` + +Some plugins require additional security permissions. You must explicitly accept them either by: + +* Attaching a `tty` when you run the Docker image and allowing the permissions when prompted. +* Inspecting the security permissions and accepting them (if appropriate) by adding the `--batch` flag to the plugin install command. + +See [Plugin management](https://www.elastic.co/guide/en/elasticsearch/plugins/current/_other_command_line_parameters.html) for more information. + + +### Troubleshoot Docker errors for {{es}} [troubleshoot-docker-errors] + +Here’s how to resolve common errors when running {{es}} with Docker. + + +### elasticsearch.keystore is a directory [_elasticsearch_keystore_is_a_directory] + +```txt +Exception in thread "main" org.elasticsearch.bootstrap.BootstrapException: java.io.IOException: Is a directory: SimpleFSIndexInput(path="/usr/share/elasticsearch/config/elasticsearch.keystore") Likely root cause: java.io.IOException: Is a directory +``` + +A [keystore-related](#docker-keystore-bind-mount) `docker run` command attempted to directly bind-mount an `elasticsearch.keystore` file that doesn’t exist. If you use the `-v` or `--volume` flag to mount a file that doesn’t exist, Docker instead creates a directory with the same name. + +To resolve this error: + +1. Delete the `elasticsearch.keystore` directory in the `config` directory. +2. Update the `-v` or `--volume` flag to point to the `config` directory path rather than the keystore file’s path. For an example, see [Create an encrypted {{es}} keystore](#docker-keystore-bind-mount). +3. Retry the command. + + +### elasticsearch.keystore: Device or resource busy [_elasticsearch_keystore_device_or_resource_busy] + +```txt +Exception in thread "main" java.nio.file.FileSystemException: /usr/share/elasticsearch/config/elasticsearch.keystore.tmp -> /usr/share/elasticsearch/config/elasticsearch.keystore: Device or resource busy +``` + +A `docker run` command attempted to [update the keystore](#docker-keystore-bind-mount) while directly bind-mounting the `elasticsearch.keystore` file. To update the keystore, the container requires access to other files in the `config` directory, such as `keystore.tmp`. + +To resolve this error: + +1. Update the `-v` or `--volume` flag to point to the `config` directory path rather than the keystore file’s path. For an example, see [Create an encrypted {{es}} keystore](#docker-keystore-bind-mount). +2. Retry the command. diff --git a/deploy-manage/deploy/self-managed/install-elasticsearch-with-rpm.md b/deploy-manage/deploy/self-managed/install-elasticsearch-with-rpm.md new file mode 100644 index 000000000..be6d7b48c --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-elasticsearch-with-rpm.md @@ -0,0 +1,369 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/rpm.html +--- + +# Install Elasticsearch with RPM [rpm] + +The RPM for Elasticsearch can be [downloaded from our website](#install-rpm) or from our [RPM repository](#rpm-repo). It can be used to install Elasticsearch on any RPM-based system such as OpenSuSE, SLES, Centos, Red Hat, and Oracle Enterprise. + +::::{note} +RPM install is not supported on distributions with old versions of RPM, such as SLES 11 and CentOS 5. Please see [Install {{es}} from archive on Linux or MacOS](install-elasticsearch-from-archive-on-linux-macos.md) instead. +:::: + + +This package contains both free and subscription features. [Start a 30-day trial](https://www.elastic.co/guide/en/elasticsearch/reference/current/license-settings.html) to try out all of the features. + +The latest stable version of Elasticsearch can be found on the [Download Elasticsearch](https://elastic.co/downloads/elasticsearch) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +::::{note} +Elasticsearch includes a bundled version of [OpenJDK](https://openjdk.java.net) from the JDK maintainers (GPLv2+CE). To use your own version of Java, see the [JVM version requirements](installing-elasticsearch.md#jvm-version) +:::: + + +::::{tip} +For a step-by-step example of setting up the {{stack}} on your own premises, try out our tutorial: [Installing a self-managed Elastic Stack](installing-elasticsearch.md). +:::: + + +## Import the Elasticsearch GPG Key [rpm-key] + +We sign all of our packages with the Elasticsearch Signing Key (PGP key [D88E42B4](https://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88E42B4), available from [https://pgp.mit.edu](https://pgp.mit.edu)) with fingerprint: + +``` +4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4 +``` +Download and install the public signing key: + +```sh +rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch +``` + + +## Installing from the RPM repository [rpm-repo] + +::::{warning} +Version 9.0.0-beta1 of Elasticsearch has not yet been released. +:::: + + +Create a file called `elasticsearch.repo` in the `/etc/yum.repos.d/` directory for RedHat based distributions, or in the `/etc/zypp/repos.d/` directory for OpenSuSE based distributions, containing: + + +## Download and install the RPM manually [install-rpm] + +::::{warning} +Version 9.0.0-beta1 of Elasticsearch has not yet been released. The RPM might not be available. +:::: + + +The RPM for Elasticsearch v9.0.0-beta1 can be downloaded from the website and installed as follows: + +```sh +wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-x86_64.rpm +wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-x86_64.rpm.sha512 +shasum -a 512 -c elasticsearch-9.0.0-beta1-x86_64.rpm.sha512 <1> +sudo rpm --install elasticsearch-9.0.0-beta1-x86_64.rpm +``` + +1. Compares the SHA of the downloaded RPM and the published checksum, which should output `elasticsearch-{{version}}-x86_64.rpm: OK`. + + +::::{note} +On systemd-based distributions, the installation scripts will attempt to set kernel parameters (e.g., `vm.max_map_count`); you can skip this by masking the systemd-sysctl.service unit. +:::: + + + +## Start {{es}} with security enabled [rpm-security-configuration] + +When installing {{es}}, security features are enabled and configured by default. When you install {{es}}, the following security configuration occurs automatically: + +* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser. +* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates. + +The password and certificate and keys are output to your terminal. You can reset the password for the `elastic` user with the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) command. + +We recommend storing the `elastic` password as an environment variable in your shell. For example: + +```sh +export ELASTIC_PASSWORD="your_password" +``` + +### Reconfigure a node to join an existing cluster [_reconfigure_a_node_to_join_an_existing_cluster_2] + +When you install {{es}}, the installation process configures a single-node cluster by default. If you want a node to join an existing cluster instead, generate an enrollment token on an existing node *before* you start the new node for the first time. + +1. On any node in your existing cluster, generate a node enrollment token: + + ```sh + /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node + ``` + +2. Copy the enrollment token, which is output to your terminal. +3. On your new {{es}} node, pass the enrollment token as a parameter to the `elasticsearch-reconfigure-node` tool: + + ```sh + /usr/share/elasticsearch/bin/elasticsearch-reconfigure-node --enrollment-token + ``` + + {{es}} is now configured to join the existing cluster. + +4. [Start your new node using `systemd`](#rpm-running-systemd). + + + +## Enable automatic creation of system indices [rpm-enable-indices] + +Some commercial features automatically create indices within {{es}}. By default, {{es}} is configured to allow automatic index creation, and no additional steps are required. However, if you have disabled automatic index creation in {{es}}, you must configure [`action.auto_create_index`](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#index-creation) in `elasticsearch.yml` to allow the commercial features to create the following indices: + +```yaml +action.auto_create_index: .monitoring*,.watches,.triggered_watches,.watcher-history*,.ml* +``` + +::::{important} +If you are using [Logstash](https://www.elastic.co/products/logstash) or [Beats](https://www.elastic.co/products/beats) then you will most likely require additional index names in your `action.auto_create_index` setting, and the exact value will depend on your local configuration. If you are unsure of the correct value for your environment, you may consider setting the value to `*` which will allow automatic creation of all indices. + +:::: + + + +## Running Elasticsearch with `systemd` [rpm-running-systemd] + +To configure Elasticsearch to start automatically when the system boots up, run the following commands: + +```sh +sudo /bin/systemctl daemon-reload +sudo /bin/systemctl enable elasticsearch.service +``` + +Elasticsearch can be started and stopped as follows: + +```sh +sudo systemctl start elasticsearch.service +sudo systemctl stop elasticsearch.service +``` + +These commands provide no feedback as to whether Elasticsearch was started successfully or not. Instead, this information will be written in the log files located in `/var/log/elasticsearch/`. + +If you have password-protected your {{es}} keystore, you will need to provide `systemd` with the keystore password using a local file and systemd environment variables. This local file should be protected while it exists and may be safely deleted once Elasticsearch is up and running. + +```sh +echo "keystore_password" > /path/to/my_pwd_file.tmp +chmod 600 /path/to/my_pwd_file.tmp +sudo systemctl set-environment ES_KEYSTORE_PASSPHRASE_FILE=/path/to/my_pwd_file.tmp +sudo systemctl start elasticsearch.service +``` + +By default the Elasticsearch service doesn’t log information in the `systemd` journal. To enable `journalctl` logging, the `--quiet` option must be removed from the `ExecStart` command line in the `elasticsearch.service` file. + +When `systemd` logging is enabled, the logging information are available using the `journalctl` commands: + +To tail the journal: + +```sh +sudo journalctl -f +``` + +To list journal entries for the elasticsearch service: + +```sh +sudo journalctl --unit elasticsearch +``` + +To list journal entries for the elasticsearch service starting from a given time: + +```sh +sudo journalctl --unit elasticsearch --since "2016-10-30 18:17:16" +``` + +Check `man journalctl` or [https://www.freedesktop.org/software/systemd/man/journalctl.html](https://www.freedesktop.org/software/systemd/man/journalctl.md) for more command line options. + +::::{admonition} Startup timeouts with older `systemd` versions +:class: tip + +By default {{es}} sets the `TimeoutStartSec` parameter to `systemd` to `900s`. If you are running at least version 238 of `systemd` then {{es}} can automatically extend the startup timeout, and will do so repeatedly until startup is complete even if it takes longer than 900s. + +Versions of `systemd` prior to 238 do not support the timeout extension mechanism and will terminate the {{es}} process if it has not fully started up within the configured timeout. If this happens, {{es}} will report in its logs that it was shut down normally a short time after it started: + +```text +[2022-01-31T01:22:31,077][INFO ][o.e.n.Node ] [instance-0000000123] starting ... +... +[2022-01-31T01:37:15,077][INFO ][o.e.n.Node ] [instance-0000000123] stopping ... +``` + +However the `systemd` logs will report that the startup timed out: + +```text +Jan 31 01:22:30 debian systemd[1]: Starting Elasticsearch... +Jan 31 01:37:15 debian systemd[1]: elasticsearch.service: Start operation timed out. Terminating. +Jan 31 01:37:15 debian systemd[1]: elasticsearch.service: Main process exited, code=killed, status=15/TERM +Jan 31 01:37:15 debian systemd[1]: elasticsearch.service: Failed with result 'timeout'. +Jan 31 01:37:15 debian systemd[1]: Failed to start Elasticsearch. +``` + +To avoid this, upgrade your `systemd` to at least version 238. You can also temporarily work around the problem by extending the `TimeoutStartSec` parameter. + +:::: + + + +## Check that Elasticsearch is running [rpm-check-running] + +You can test that your {{es}} node is running by sending an HTTPS request to port `9200` on `localhost`: + +```sh +curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 <1> +``` + +1. Ensure that you use `https` in your call, or the request will fail.`--cacert` +: Path to the generated `http_ca.crt` certificate for the HTTP layer. + + + +The call returns a response like this: + +```js +{ + "name" : "Cp8oag6", + "cluster_name" : "elasticsearch", + "cluster_uuid" : "AT69_T_DTp-1qgIJlatQqA", + "version" : { + "number" : "9.0.0-SNAPSHOT", + "build_type" : "tar", + "build_hash" : "f27399d", + "build_flavor" : "default", + "build_date" : "2016-03-30T09:51:41.449Z", + "build_snapshot" : false, + "lucene_version" : "10.0.0", + "minimum_wire_compatibility_version" : "1.2.3", + "minimum_index_compatibility_version" : "1.2.3" + }, + "tagline" : "You Know, for Search" +} +``` + + +## Configuring Elasticsearch [rpm-configuring] + +The `/etc/elasticsearch` directory contains the default runtime configuration for {{es}}. The ownership of this directory and all contained files are set to `root:elasticsearch` on package installations. + +The `setgid` flag applies group permissions on the `/etc/elasticsearch` directory to ensure that {{es}} can read any contained files and subdirectories. All files and subdirectories inherit the `root:elasticsearch` ownership. Running commands from this directory or any subdirectories, such as the [elasticsearch-keystore tool](../../security/secure-settings.md), requires `root:elasticsearch` permissions. + +Elasticsearch loads its configuration from the `/etc/elasticsearch/elasticsearch.yml` file by default. The format of this config file is explained in [*Configuring {{es}}*](configure-elasticsearch.md). + +The RPM also has a system configuration file (`/etc/sysconfig/elasticsearch`), which allows you to set the following parameters: + +`ES_JAVA_HOME` +: Set a custom Java path to be used. + +`ES_PATH_CONF` +: Configuration file directory (which needs to include `elasticsearch.yml`, `jvm.options`, and `log4j2.properties` files); defaults to `/etc/elasticsearch`. + +`ES_JAVA_OPTS` +: Any additional JVM system properties you may want to apply. + +`RESTART_ON_UPGRADE` +: Configure restart on package upgrade, defaults to `false`. This means you will have to restart your Elasticsearch instance after installing a package manually. The reason for this is to ensure, that upgrades in a cluster do not result in a continuous shard reallocation resulting in high network traffic and reducing the response times of your cluster. + +::::{note} +Distributions that use `systemd` require that system resource limits be configured via `systemd` rather than via the `/etc/sysconfig/elasticsearch` file. See [Systemd configuration](setting-system-settings.md#systemd) for more information. +:::: + + + +## Connect clients to {{es}} [_connect_clients_to_es_4] + +When you start {{es}} for the first time, TLS is configured automatically for the HTTP layer. A CA certificate is generated and stored on disk at: + +```sh +/etc/elasticsearch/certs/http_ca.crt +``` + +The hex-encoded SHA-256 fingerprint of this certificate is also output to the terminal. Any clients that connect to {{es}}, such as the [{{es}} Clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html), {{beats}}, standalone {{agent}}s, and {{ls}} must validate that they trust the certificate that {{es}} uses for HTTPS. {{fleet-server}} and {{fleet}}-managed {{agent}}s are automatically configured to trust the CA certificate. Other clients can establish trust by using either the fingerprint of the CA certificate or the CA certificate itself. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate. You can also copy the CA certificate to your machine and configure your client to use it. + + +#### Use the CA fingerprint [_use_the_ca_fingerprint_4] + +Copy the fingerprint value that’s output to your terminal when {{es}} starts, and configure your client to use this fingerprint to establish trust when it connects to {{es}}. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate by running the following command. The path is to the auto-generated CA certificate for the HTTP layer. + +```sh +openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt +``` + +The command returns the security certificate, including the fingerprint. The `issuer` should be `Elasticsearch security auto-configuration HTTP CA`. + +```sh +issuer= /CN=Elasticsearch security auto-configuration HTTP CA +SHA256 Fingerprint= +``` + + +#### Use the CA certificate [_use_the_ca_certificate_4] + +If your library doesn’t support a method of validating the fingerprint, the auto-generated CA certificate is created in the following directory on each {{es}} node: + +```sh +/etc/elasticsearch/certs/http_ca.crt +``` + +Copy the `http_ca.crt` file to your machine and configure your client to use this certificate to establish trust when it connects to {{es}}. + + +## Directory layout of RPM [rpm-layout] + +The RPM places config files, logs, and the data directory in the appropriate locations for an RPM-based system: + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | Elasticsearch home directory or `$ES_HOME` | `/usr/share/elasticsearch` | | +| bin | Binary scripts including `elasticsearch` to start a node and `elasticsearch-plugin` to install plugins | `/usr/share/elasticsearch/bin` | | +| conf | Configuration files including `elasticsearch.yml` | `/etc/elasticsearch` | `[ES_PATH_CONF](configure-elasticsearch.md#config-files-location)` | +| conf | Environment variables including heap size, file descriptors. | `/etc/sysconfig/elasticsearch` | | +| conf | Generated TLS keys and certificates for the transport and http layer. | `/etc/elasticsearch/certs` | | +| data | The location of the data files of each index / shard allocated on the node. | `/var/lib/elasticsearch` | `path.data` | +| jdk | The bundled Java Development Kit used to run Elasticsearch. Can be overridden by setting the `ES_JAVA_HOME` environment variable in `/etc/sysconfig/elasticsearch`. | `/usr/share/elasticsearch/jdk` | | +| logs | Log files location. | `/var/log/elasticsearch` | `path.logs` | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `/usr/share/elasticsearch/plugins` | | +| repo | Shared file system repository locations. Can hold multiple locations. A file system repository can be placed in to any subdirectory of any directory specified here. | Not configured | `path.repo` | + +### Security certificates and keys [_security_certificates_and_keys_3] + +When you install {{es}}, the following certificates and keys are generated in the {{es}} configuration directory, which are used to connect a {{kib}} instance to your secured {{es}} cluster and to encrypt internode communication. The files are listed here for reference. + +`http_ca.crt` +: The CA certificate that is used to sign the certificates for the HTTP layer of this {{es}} cluster. + +`http.p12` +: Keystore that contains the key and certificate for the HTTP layer for this node. + +`transport.p12` +: Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster. + +`http.p12` and `transport.p12` are password-protected PKCS#12 keystores. {{es}} stores the passwords for these keystores as [secure settings](../../security/secure-settings.md). To retrieve the passwords so that you can inspect or change the keystore contents, use the [`bin/elasticsearch-keystore`](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-keystore.html) tool. + +Use the following command to retrieve the password for `http.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.http.ssl.keystore.secure_password +``` + +Use the following command to retrieve the password for `transport.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password +``` + + + +## Next steps [_next_steps_4] + +You now have a test {{es}} environment set up. Before you start serious development or go into production with {{es}}, you must do some additional setup: + +* Learn how to [configure Elasticsearch](configure-elasticsearch.md). +* Configure [important Elasticsearch settings](important-settings-configuration.md). +* Configure [important system settings](important-system-configuration.md). diff --git a/deploy-manage/deploy/self-managed/install-elasticsearch-with-zip-on-windows.md b/deploy-manage/deploy/self-managed/install-elasticsearch-with-zip-on-windows.md new file mode 100644 index 000000000..a39fadf6e --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-elasticsearch-with-zip-on-windows.md @@ -0,0 +1,372 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/zip-windows.html +--- + +# Install Elasticsearch with .zip on Windows [zip-windows] + +{{es}} can be installed on Windows using the Windows `.zip` archive. This comes with a `elasticsearch-service.bat` command which will setup {{es}} to run as a service. + +This package contains both free and subscription features. [Start a 30-day trial](https://www.elastic.co/guide/en/elasticsearch/reference/current/license-settings.html) to try out all of the features. + +::::{note} +On Windows the {{es}} {ml} feature requires the Microsoft Universal C Runtime library. This is built into Windows 10, Windows Server 2016 and more recent versions of Windows. For older versions of Windows it can be installed via Windows Update, or from a [separate download](https://support.microsoft.com/en-us/help/2999226/update-for-universal-c-runtime-in-windows). If you cannot install the Microsoft Universal C Runtime library you can still use the rest of {{es}} if you disable the {{ml}} feature. +:::: + + +The latest stable version of {{es}} can be found on the [Download {{es}}](https://elastic.co/downloads/elasticsearch) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +::::{note} +{{es}} includes a bundled version of [OpenJDK](https://openjdk.java.net) from the JDK maintainers (GPLv2+CE). To use your own version of Java, see the [JVM version requirements](installing-elasticsearch.md#jvm-version) +:::: + + +## Download and install the `.zip` package [install-windows] + +::::{warning} +Version 9.0.0-beta1 of {{es}} has not yet been released. The archive might not be available. +:::: + + +Download the `.zip` archive for {{es}} 9.0.0-beta1 from: [https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-windows-x86_64.zip](https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.0.0-beta1-windows-x86_64.zip) + +Unzip it with your favorite unzip tool. This will create a folder called `elasticsearch-9.0.0-beta1`, which we will refer to as `%ES_HOME%`. In a terminal window, `cd` to the `%ES_HOME%` directory, for instance: + +```sh +cd C:\Program Files\elasticsearch-9.0.0-beta1 +``` + + +## Enable automatic creation of system indices [windows-enable-indices] + +Some commercial features automatically create indices within {{es}}. By default, {{es}} is configured to allow automatic index creation, and no additional steps are required. However, if you have disabled automatic index creation in {{es}}, you must configure [`action.auto_create_index`](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#index-creation) in `elasticsearch.yml` to allow the commercial features to create the following indices: + +```yaml +action.auto_create_index: .monitoring*,.watches,.triggered_watches,.watcher-history*,.ml* +``` + +::::{important} +If you are using [Logstash](https://www.elastic.co/products/logstash) or [Beats](https://www.elastic.co/products/beats) then you will most likely require additional index names in your `action.auto_create_index` setting, and the exact value will depend on your local configuration. If you are unsure of the correct value for your environment, you may consider setting the value to `*` which will allow automatic creation of all indices. + +:::: + + + +## Run {{es}} from the command line [windows-running] + +Run the following command to start {{es}} from the command line: + +```sh +.\bin\elasticsearch.bat +``` + +When starting {{es}} for the first time, security features are enabled and configured by default. The following security configuration occurs automatically: + +* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser. +* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates. +* An enrollment token is generated for {{kib}}, which is valid for 30 minutes. + +The password for the `elastic` user and the enrollment token for {{kib}} are output to your terminal. + +We recommend storing the `elastic` password as an environment variable in your shell. Example: + +```sh +$ELASTIC_PASSWORD = "your_password" +``` + +If you have password-protected the {{es}} keystore, you will be prompted to enter the keystore’s password. See [Secure settings](../../security/secure-settings.md) for more details. + +By default {{es}} prints its logs to the console (`STDOUT`) and to the `.log` file within the [logs directory](important-settings-configuration.md#path-settings). {{es}} logs some information while it is starting, but after it has finished initializing it will continue to run in the foreground and won’t log anything further until something happens that is worth recording. While {{es}} is running you can interact with it through its HTTP interface which is on port `9200` by default. + +To stop {{es}}, press `Ctrl-C`. + + +### Enroll nodes in an existing cluster [_enroll_nodes_in_an_existing_cluster_2] + +When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to localhost. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration. + +Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically. + +Additionally, only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need to set `transport.host` to a [supported value](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#network-interface-values) (such as uncommenting the suggested value of `0.0.0.0`), or an IP address that’s bound to an interface where other hosts can reach it. Refer to [transport settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings) for more information. + +To enroll new nodes in your cluster, create an enrollment token with the `elasticsearch-create-enrollment-token` tool on any existing node in your cluster. You can then start a new node with the `--enrollment-token` parameter so that it joins an existing cluster. + +1. In a separate terminal from where {{es}} is running, navigate to the directory where you installed {{es}} and run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool to generate an enrollment token for your new nodes. + + ```sh + bin\elasticsearch-create-enrollment-token -s node + ``` + + Copy the enrollment token, which you’ll use to enroll new nodes with your {{es}} cluster. + +2. From the installation directory of your new node, start {{es}} and pass the enrollment token with the `--enrollment-token` parameter. + + ```sh + bin\elasticsearch --enrollment-token + ``` + + {{es}} automatically generates certificates and keys in the following directory: + + ```sh + config\certs + ``` + +3. Repeat the previous step for any new nodes that you want to enroll. + + +## Configure {{es}} on the command line [windows-configuring] + +{{es}} loads its configuration from the `%ES_HOME%\config\elasticsearch.yml` file by default. The format of this config file is explained in [*Configuring {{es}}*](configure-elasticsearch.md). + +Any settings that can be specified in the config file can also be specified on the command line, using the `-E` syntax as follows: + +```sh +.\bin\elasticsearch.bat -Ecluster.name=my_cluster -Enode.name=node_1 +``` + +::::{note} +Values that contain spaces must be surrounded with quotes. For instance `-Epath.logs="C:\My Logs\logs"`. +:::: + + +::::{tip} +Typically, any cluster-wide settings (like `cluster.name`) should be added to the `elasticsearch.yml` config file, while any node-specific settings such as `node.name` could be specified on the command line. +:::: + + + +## Check that Elasticsearch is running [_check_that_elasticsearch_is_running_2] + +You can test that your {{es}} node is running by sending an HTTPS request to port `9200` on `localhost`: + +```sh +curl --cacert %ES_HOME%\config\certs\http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 <1> +``` + +1. Ensure that you use `https` in your call, or the request will fail.`--cacert` +: Path to the generated `http_ca.crt` certificate for the HTTP layer. + + + +The call returns a response like this: + +```js +{ + "name" : "Cp8oag6", + "cluster_name" : "elasticsearch", + "cluster_uuid" : "AT69_T_DTp-1qgIJlatQqA", + "version" : { + "number" : "9.0.0-SNAPSHOT", + "build_type" : "tar", + "build_hash" : "f27399d", + "build_flavor" : "default", + "build_date" : "2016-03-30T09:51:41.449Z", + "build_snapshot" : false, + "lucene_version" : "10.0.0", + "minimum_wire_compatibility_version" : "1.2.3", + "minimum_index_compatibility_version" : "1.2.3" + }, + "tagline" : "You Know, for Search" +} +``` + + +## Install and run {{es}} as a service on Windows [windows-service] + +You can install {{es}} as a service that runs in the background or starts automatically at boot time without user interaction. + +1. Install {{es}} as a service. The name of the service and the value of `ES_JAVA_HOME` will be made available during install: + + ```sh + C:\Program Files\elasticsearch-9.0.0-beta1\bin>elasticsearch-service.bat install + Installing service : "elasticsearch-service-x64" + Using ES_JAVA_HOME (64-bit): "C:\jvm\jdk1.8" + The service 'elasticsearch-service-x64' has been installed. + ``` + +2. Start {{es}} as a service. When {{es}} starts, authentication is enabled by default: + + ```sh + C:\Program Files\elasticsearch-9.0.0-beta1\bin>bin\elasticsearch-service.bat start + ``` + + ::::{note} + TLS is not enabled or configured when you start {{es}} as a service. + :::: + +3. Generate a password for the `elastic` user with the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) tool. The password is output to the command line. + + ```sh + C:\Program Files\elasticsearch-9.0.0-beta1\bin>\bin\elasticsearch-reset-password -u elastic + ``` + + +::::{note} +While a JRE can be used for the {{es}} service, due to its use of a client VM (as opposed to a server JVM which offers better performance for long-running applications) its usage is discouraged and a warning will be issued. +:::: + + +::::{note} +The system environment variable `ES_JAVA_HOME` should be set to the path of the JDK installation that you want the service to use. If you upgrade the JDK, you are not required to the reinstall the service but you must set the value of the system environment variable `ES_JAVA_HOME` to the path to the new JDK installation. However, upgrading across JVM types (e.g. JRE versus SE) is not supported, and does require the service to be reinstalled. +:::: + + +### Manage {{es}} as a service on Windows [windows-service-manage] + +Run the `elasticsearch-service.bat` script in the `bin\` folder to install, remove, manage, or configure the service and potentially start and stop the service from the command line. + +```sh +C:\Program Files\elasticsearch-9.0.0-beta1\bin>elasticsearch-service.bat + +Usage: elasticsearch-service.bat install|remove|start|stop|manager [SERVICE_ID] +``` + +The script requires one parameter (the command to execute), followed by an optional one indicating the service id (useful when installing multiple {{es}} services). + +The commands available are: + +`install` +: Install {{es}} as a service + +`remove` +: Remove the installed {{es}} service (and stop the service if started) + +`start` +: Start the {{es}} service (if installed) + +`stop` +: Stop the {{es}} service (if started) + +`manager` +: Start a GUI for managing the installed service + + +## Customize service settings [windows-service-settings] + +The {{es}} service can be configured prior to installation by setting the following environment variables (either using the [set command](https://technet.microsoft.com/en-us/library/cc754250(v=ws.10).aspx) from the command line, or through the **System Properties→Environment Variables** GUI). + +`SERVICE_ID` +: A unique identifier for the service. Useful if installing multiple instances on the same machine. Defaults to `elasticsearch-service-x64`. + +`SERVICE_USERNAME` +: The user to run as, defaults to the local system account. + +`SERVICE_PASSWORD` +: The password for the user specified in `%SERVICE_USERNAME%`. + +`SERVICE_DISPLAY_NAME` +: The name of the service. Defaults to `{{es}} %SERVICE_ID%`. + +`SERVICE_DESCRIPTION` +: The description of the service. Defaults to `{{es}} Windows Service - https://elastic.co`. + +`ES_JAVA_HOME` +: The installation directory of the desired JVM to run the service under. + +`SERVICE_LOG_DIR` +: Service log directory, defaults to `%ES_HOME%\logs`. Note that this does not control the path for the {{es}} logs; the path for these is set via the setting `path.logs` in the `elasticsearch.yml` configuration file, or on the command line. + +`ES_PATH_CONF` +: Configuration file directory (which needs to include `elasticsearch.yml`, `jvm.options`, and `log4j2.properties` files), defaults to `%ES_HOME%\config`. + +`ES_JAVA_OPTS` +: Any additional JVM system properties you may want to apply. + +`ES_START_TYPE` +: Startup mode for the service. Can be either `auto` or `manual` (default). + +`ES_STOP_TIMEOUT` +: The timeout in seconds that procrun waits for service to exit gracefully. Defaults to `0`. + +::::{note} +At its core, `elasticsearch-service.bat` relies on [Apache Commons Daemon](https://commons.apache.org/proper/commons-daemon/) project to install the service. Environment variables set prior to the service installation are copied and will be used during the service lifecycle. This means any changes made to them after the installation will not be picked up unless the service is reinstalled. +:::: + + +::::{note} +By default, {{es}} automatically sizes JVM heap based on a node’s [roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) and total memory. We recommend this default sizing for most production environments. If needed, you can override default sizing by manually setting the heap size. + +When installing {{es}} on Windows as a service for the first time or running {{es}} from the command line, you can manually [Set the JVM heap size](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-heap-size). To resize the heap for an already installed service, use the service manager: `bin\elasticsearch-service.bat manager`. + +:::: + + +::::{note} +The service automatically configures a private temporary directory for use by {{es}} when it is running. This private temporary directory is configured as a sub-directory of the private temporary directory for the user running the installation. If the service will run under a different user, you can configure the location of the temporary directory that the service should use by setting the environment variable `ES_TMPDIR` to the preferred location before you execute the service installation. +:::: + + +Using the Manager GUI +: It is also possible to configure the service after it’s been installed using the manager GUI (`elasticsearch-service-mgr.exe`), which offers insight into the installed service, including its status, startup type, JVM, start and stop settings amongst other things. Invoke `elasticsearch-service.bat manager` from the command-line to open the manager window. + +Most changes (like JVM settings) made through the manager GUI will require a restart of the service to take affect. + + + +## Connect clients to {{es}} [_connect_clients_to_es_2] + +When you start {{es}} for the first time, TLS is configured automatically for the HTTP layer. A CA certificate is generated and stored on disk at: + +```sh +%ES_HOME%\config\certs\http_ca.crt +``` + +The hex-encoded SHA-256 fingerprint of this certificate is also output to the terminal. Any clients that connect to {{es}}, such as the [{{es}} Clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html), {{beats}}, standalone {{agent}}s, and {{ls}} must validate that they trust the certificate that {{es}} uses for HTTPS. {{fleet-server}} and {{fleet}}-managed {{agent}}s are automatically configured to trust the CA certificate. Other clients can establish trust by using either the fingerprint of the CA certificate or the CA certificate itself. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate. You can also copy the CA certificate to your machine and configure your client to use it. + + +#### Use the CA fingerprint [_use_the_ca_fingerprint_2] + +Copy the fingerprint value that’s output to your terminal when {{es}} starts, and configure your client to use this fingerprint to establish trust when it connects to {{es}}. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate by running the following command. The path is to the auto-generated CA certificate for the HTTP layer. + +```sh +openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt +``` + +The command returns the security certificate, including the fingerprint. The `issuer` should be `Elasticsearch security auto-configuration HTTP CA`. + +```sh +issuer= /CN=Elasticsearch security auto-configuration HTTP CA +SHA256 Fingerprint= +``` + + +#### Use the CA certificate [_use_the_ca_certificate_2] + +If your library doesn’t support a method of validating the fingerprint, the auto-generated CA certificate is created in the following directory on each {{es}} node: + +```sh +%ES_HOME%\config\certs\http_ca.crt +``` + +Copy the `http_ca.crt` file to your machine and configure your client to use this certificate to establish trust when it connects to {{es}}. + + +## Directory layout of `.zip` archive [windows-layout] + +The `.zip` package is entirely self-contained. All files and directories are, by default, contained within `%ES_HOME%` — the directory created when unpacking the archive. + +This is very convenient because you don’t have to create any directories to start using {{es}}, and uninstalling {{es}} is as easy as removing the `%ES_HOME%` directory. However, it is advisable to change the default locations of the config directory, the data directory, and the logs directory so that you do not delete important data later on. + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | {{es}} home directory or `%ES_HOME%` | Directory created by unpacking the archive | | +| bin | Binary scripts including `elasticsearch` to start a node and `elasticsearch-plugin` to install plugins | `%ES_HOME%\bin` | | +| conf | Configuration files including `elasticsearch.yml` | `%ES_HOME%\config` | `[ES_PATH_CONF](configure-elasticsearch.md#config-files-location)` | +| conf | Generated TLS keys and certificates for the transport and HTTP layer. | `%ES_HOME%\config\certs` | | +| data | The location of the data files of each index / shard allocated on the node. | `%ES_HOME%\data` | `path.data` | +| logs | Log files location. | `%ES_HOME%\logs` | `path.logs` | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `%ES_HOME%\plugins` | | +| repo | Shared file system repository locations. Can hold multiple locations. A file system repository can be placed in to any subdirectory of any directory specified here. | Not configured | `path.repo` | + + +## Next steps [_next_steps_2] + +You now have a test {{es}} environment set up. Before you start serious development or go into production with {{es}}, you must do some additional setup: + +* Learn how to [configure Elasticsearch](configure-elasticsearch.md). +* Configure [important Elasticsearch settings](important-settings-configuration.md). +* Configure [important system settings](important-system-configuration.md). diff --git a/deploy-manage/deploy/self-managed/install-from-archive-on-linux-macos.md b/deploy-manage/deploy/self-managed/install-from-archive-on-linux-macos.md new file mode 100644 index 000000000..a05a8bc0a --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-from-archive-on-linux-macos.md @@ -0,0 +1,103 @@ +--- +navigation_title: "Install from archive on Linux or macOS" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/targz.html +--- + + + +# Install from archive on Linux or macOS [targz] + + +Kibana is provided for Linux and Darwin as a `.tar.gz` package. These packages are the easiest formats to use when trying out Kibana. + +This package contains both free and subscription features. [Start a 30-day trial](../../license/manage-your-license-in-self-managed-cluster.md) to try out all of the features. + +The latest stable version of Kibana can be found on the [Download Kibana](https://elastic.co/downloads/kibana) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +::::{note} +macOS is supported for development purposes only and is not covered under the support SLA for [production-supported operating systems](https://www.elastic.co/support/matrix#kibana). + +:::: + + +## Download and install the Linux 64-bit package [install-linux64] + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Download and install the Darwin package [install-darwin64] + +::::{admonition} macOS Gatekeeper warnings +:class: important + +Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{kib}} artifacts. If macOS displays a dialog when you first run {{kib}} that interrupts it, you will need to take an action to allow it to run. + +To prevent Gatekeeper checks on the {{kib}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: + +```sh +xattr -d -r com.apple.quarantine +``` + +Alternatively, you can add a security override if a Gatekeeper popup appears by following the instructions in the *How to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491). + +:::: + + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Start {{es}} and generate an enrollment token for {{kib}} [targz-enroll] + + +When you start {{es}} for the first time, the following security configuration occurs automatically: + +* [Certificates and keys](installing-elasticsearch.md#stack-security-certificates) for TLS are generated for the transport and HTTP layers. +* The TLS configuration settings are written to `elasticsearch.yml`. +* A password is generated for the `elastic` user. +* An enrollment token is generated for {{kib}}. + +You can then start {{kib}} and enter the enrollment token to securely connect {{kib}} with {{es}}. The enrollment token is valid for 30 minutes. + + +## Run {{kib}} from the command line [targz-running] + +Kibana can be started from the command line as follows: + +```sh +./bin/kibana +``` + +By default, Kibana runs in the foreground, prints its logs to the standard output (`stdout`), and can be stopped by pressing **Ctrl-C**. + +If this is the first time you’re starting {{kib}}, this command generates a unique link in your terminal to enroll your {{kib}} instance with {{es}}. + +1. In your terminal, click the generated link to open {{kib}} in your browser. +2. In your browser, paste the enrollment token that was generated in the terminal when you started {{es}}, and then click the button to connect your {{kib}} instance with {{es}}. +3. Log in to {{kib}} as the `elastic` user with the password that was generated when you started {{es}}. + +::::{note} +If you need to reset the password for the `elastic` user or other built-in users, run the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) tool. To generate new enrollment tokens for {{kib}} or {{es}} nodes, run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool. These tools are available in the {{es}} `bin` directory. + +:::: + + + +## Configure {{kib}} via the config file [targz-configuring] + +Kibana loads its configuration from the `$KIBANA_HOME/config/kibana.yml` file by default. The format of this config file is explained in [Configuring Kibana](configure.md). + + +## Directory layout of `.tar.gz` archives [targz-layout] + +The `.tar.gz` packages are entirely self-contained. All files and directories are, by default, contained within `$KIBANA_HOME` — the directory created when unpacking the archive. + +This is very convenient because you don’t have to create any directories to start using Kibana, and uninstalling Kibana is as easy as removing the `$KIBANA_HOME` directory. However, it is advisable to change the default locations of the config and data directories so that you do not delete important data later on. + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | Kibana home directory or `$KIBANA_HOME` | Directory created by unpacking the archive | | +| bin | Binary scripts including `kibana` to start the Kibana server and `kibana-plugin` to install plugins | `$KIBANA_HOME\bin` | | +| config | Configuration files including `kibana.yml` | `$KIBANA_HOME\config` | `[KBN_PATH_CONF](configure.md)` | +| data | The location of the data files written to disk by Kibana and its plugins | `$KIBANA_HOME\data` | | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `$KIBANA_HOME\plugins` | | diff --git a/deploy-manage/deploy/self-managed/install-kibana.md b/deploy-manage/deploy/self-managed/install-kibana.md new file mode 100644 index 000000000..feeb8d10e --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-kibana.md @@ -0,0 +1,19 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/setup.html + - https://www.elastic.co/guide/en/kibana/current/install.html +--- + +# Install Kibana + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/340 + +% Scope notes: Good intro / landing page. Merge the content of both, and remove the reference to cloud + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/setup.md +% Notes: 5 child docs, all needed +% - [ ] ./raw-migrated-files/kibana/kibana/install.md \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/install-on-windows.md b/deploy-manage/deploy/self-managed/install-on-windows.md new file mode 100644 index 000000000..baf906355 --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-on-windows.md @@ -0,0 +1,76 @@ +--- +navigation_title: "Install on Windows" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/windows.html +--- + + + +# Install on Windows [windows] + + +Kibana can be installed on Windows using the `.zip` package. + +This package contains both free and subscription features. [Start a 30-day trial](../../license/manage-your-license-in-self-managed-cluster.md) to try out all of the features. + +The latest stable version of Kibana can be found on the [Download Kibana](https://elastic.co/downloads/kibana) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +## Download and install the `.zip` package [install-windows] + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Start {{es}} and generate an enrollment token for {{kib}} [windows-enroll] + + +When you start {{es}} for the first time, the following security configuration occurs automatically: + +* [Certificates and keys](installing-elasticsearch.md#stack-security-certificates) for TLS are generated for the transport and HTTP layers. +* The TLS configuration settings are written to `elasticsearch.yml`. +* A password is generated for the `elastic` user. +* An enrollment token is generated for {{kib}}. + +You can then start {{kib}} and enter the enrollment token to securely connect {{kib}} with {{es}}. The enrollment token is valid for 30 minutes. + + +## Run {{kib}} from the command line [windows-running] + +Kibana can be started from the command line as follows: + +```sh +.\bin\kibana.bat +``` + +By default, Kibana runs in the foreground, prints its logs to `STDOUT`, and can be stopped by pressing **Ctrl-C**. + +If this is the first time you’re starting {{kib}}, this command generates a unique link in your terminal to enroll your {{kib}} instance with {{es}}. + +1. In your terminal, click the generated link to open {{kib}} in your browser. +2. In your browser, paste the enrollment token that was generated in the terminal when you started {{es}}, and then click the button to connect your {{kib}} instance with {{es}}. +3. Log in to {{kib}} as the `elastic` user with the password that was generated when you started {{es}}. + +::::{note} +If you need to reset the password for the `elastic` user or other built-in users, run the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) tool. To generate new enrollment tokens for {{kib}} or {{es}} nodes, run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool. These tools are available in the {{es}} `bin` directory. + +:::: + + + +## Configure {{kib}} via the config file [windows-configuring] + +Kibana loads its configuration from the `$KIBANA_HOME/config/kibana.yml` file by default. The format of this config file is explained in [Configuring Kibana](configure.md). + + +## Directory layout of `.zip` archive [windows-layout] + +The `.zip` package is entirely self-contained. All files and directories are, by default, contained within `$KIBANA_HOME` — the directory created when unpacking the archive. + +This is very convenient because you don’t have to create any directories to start using Kibana, and uninstalling Kibana is as easy as removing the `$KIBANA_HOME` directory. However, it is advisable to change the default locations of the config and data directories so that you do not delete important data later on. + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | Kibana home directory or `$KIBANA_HOME` | Directory created by unpacking the archive | | +| bin | Binary scripts including `kibana` to start the Kibana server and `kibana-plugin` to install plugins | `$KIBANA_HOME\bin` | | +| config | Configuration files including `kibana.yml` | `$KIBANA_HOME\config` | `[KBN_PATH_CONF](configure.md)` | +| | data | `The location of the data files written to disk by Kibana and its plugins` | `$KIBANA_HOME\data` | +| | plugins | `Plugin files location. Each plugin will be contained in a subdirectory.` | `$KIBANA_HOME\plugins` | diff --git a/deploy-manage/deploy/self-managed/install-with-debian-package.md b/deploy-manage/deploy/self-managed/install-with-debian-package.md new file mode 100644 index 000000000..c594547e3 --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-with-debian-package.md @@ -0,0 +1,96 @@ +--- +navigation_title: "Install with Debian package" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/deb.html +--- + + + +# Install with Debian package [deb] + + +The Debian package for Kibana can be [downloaded from our website](#install-deb) or from our [APT repository](#deb-repo). It can be used to install Kibana on any Debian-based system such as Debian and Ubuntu. + +This package contains both free and subscription features. [Start a 30-day trial](../../license/manage-your-license-in-self-managed-cluster.md) to try out all of the features. + +The latest stable version of Kibana can be found on the [Download Kibana](https://elastic.co/downloads/kibana) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +## Import the Elastic PGP key [deb-key] + +We sign all of our packages with the Elastic Signing Key (PGP key [D88E42B4](https://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88E42B4), available from [https://pgp.mit.edu](https://pgp.mit.edu)) with fingerprint: + +``` +4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4 +``` +Download and install the public signing key: + +```sh +wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg +``` + + +## Install from the APT repository [deb-repo] + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Download and install the Debian package manually [install-deb] + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Start {{es}} and generate an enrollment token for {{kib}} [deb-enroll] + + +When you start {{es}} for the first time, the following security configuration occurs automatically: + +* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser. +* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates. + +The password and certificate and keys are output to your terminal. + +You can then generate an enrollment token for {{kib}} with the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool: + +```sh +bin/elasticsearch-create-enrollment-token -s kibana +``` + +Start {{kib}} and enter the enrollment token to securely connect {{kib}} with {{es}}. + + +## Run {{kib}} with `systemd` [deb-running-systemd] + +To configure {{kib}} to start automatically when the system starts, run the following commands: + +```sh +sudo /bin/systemctl daemon-reload +sudo /bin/systemctl enable kibana.service +``` + +{{kib}} can be started and stopped as follows: + +```sh +sudo systemctl start kibana.service +sudo systemctl stop kibana.service +``` + +These commands provide no feedback as to whether {{kib}} was started successfully or not. Log information can be accessed via `journalctl -u kibana.service`. + + +## Configure {{kib}} via the config file [deb-configuring] + +Kibana loads its configuration from the `/etc/kibana/kibana.yml` file by default. The format of this config file is explained in [Configuring Kibana](configure.md). + + +## Directory layout of Debian package [deb-layout] + +The Debian package places config files, logs, and the data directory in the appropriate locations for a Debian-based system: + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | Kibana home directory or `$KIBANA_HOME` | `/usr/share/kibana` | | +| bin | Binary scripts including `kibana` to start the Kibana server and `kibana-plugin` to install plugins | `/usr/share/kibana/bin` | | +| config | Configuration files including `kibana.yml` | `/etc/kibana` | `[KBN_PATH_CONF](configure.md)` | +| data | The location of the data files written to disk by Kibana and its plugins | `/var/lib/kibana` | `path.data` | +| logs | Logs files location | `/var/log/kibana` | `[Logging configuration](../../monitor/logging-configuration/kibana-logging.md)` | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `/usr/share/kibana/plugins` | | diff --git a/deploy-manage/deploy/self-managed/install-with-docker.md b/deploy-manage/deploy/self-managed/install-with-docker.md new file mode 100644 index 000000000..c6061ec2c --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-with-docker.md @@ -0,0 +1,255 @@ +--- +navigation_title: "Install with Docker" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/docker.html +--- + + + +# Install with Docker [docker] + + +Docker images for {{kib}} are available from the Elastic Docker registry. The base image is [ubuntu:20.04](https://hub.docker.com/_/ubuntu). + +A list of all published Docker images and tags is available at [www.docker.elastic.co](https://www.docker.elastic.co). The source code is in [GitHub](https://github.com/elastic/dockerfiles/tree/master/kibana). + +These images contain both free and subscription features. [Start a 30-day trial](../../license/manage-your-license-in-self-managed-cluster.md) to try out all of the features. + + +## Run {{kib}} in Docker for development [run-kibana-on-docker-for-dev] + +Use Docker commands to run {{kib}} on a single-node {{es}} cluster for development or testing. + +::::{tip} +This setup doesn’t run multiple {{es}} nodes by default. To create a multi-node cluster with {{kib}}, use Docker Compose instead. Refer to [Start a multi-node cluster with Docker Compose](install-elasticsearch-with-docker.md#docker-compose-file) in the {{es}} documentation. +:::: + + +## Hardened Docker images [_hardened_docker_images] + +You can also use the hardened [Wolfi](https://wolfi.dev/) image for additional security. Using Wolfi images requires Docker version 20.10.10 or higher. + +To use the Wolfi image, append `-wolfi` to the image tag in the Docker command. + +For example: + +```sh +docker pull docker.elastic.co/elasticsearch/elasticsearch-wolfi:9.0.0-beta1 +``` + + +## Start a single node cluster [_start_a_single_node_cluster] + +1. Install Docker. Visit [Get Docker](https://docs.docker.com/get-docker/) to install Docker for your environment. + + ::::{important} + If using Docker Desktop, make sure to allocate at least 4GB of memory. You can adjust memory usage in Docker Desktop by going to **Settings > Resources**. + :::: + +2. Create a new Docker network for {{es}} and {{kib}}. + + ```sh + docker network create elastic + ``` + +3. Pull the {{es}} Docker image. + + ::::{warning} + Version 9.0.0-beta1 has not yet been released. No Docker image is currently available for {{es}} 9.0.0-beta1. + :::: + + + ```sh + docker pull docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + +4. Optional: Install [Cosign](https://docs.sigstore.dev/system_config/installation/) for your environment. Then use Cosign to verify the {{es}} image’s signature. + + ```sh + wget https://artifacts.elastic.co/cosign.pub + cosign verify --key cosign.pub docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + + The `cosign` command prints the check results and the signature payload in JSON format: + + ```sh + Verification for docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 -- + The following checks were performed on each of these signatures: + - The cosign claims were validated + - Existence of the claims in the transparency log was verified offline + - The signatures were verified against the specified public key + ``` + +5. Start an {{es}} container. + + ```sh + docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB docker.elastic.co/elasticsearch/elasticsearch:9.0.0-beta1 + ``` + + ::::{tip} + Use the `-m` flag to set a memory limit for the container. This removes the need to [manually set the JVM size](install-elasticsearch-with-docker.md#docker-set-heap-size). + :::: + + + The command prints the `elastic` user password and an enrollment token for {{kib}}. + +6. Copy the generated `elastic` password and enrollment token. These credentials are only shown when you start {{es}} for the first time. You can regenerate the credentials using the following commands. + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana + ``` + +7. Pull the {{kib}} Docker image. + + ::::{warning} + Version 9.0.0-beta1 has not yet been released. No Docker image is currently available for {{kib}} 9.0.0-beta1. + :::: + + + ```sh + docker pull docker.elastic.co/kibana/kibana:9.0.0-beta1 + ``` + +8. Optional: Verify the {{kib}} image’s signature. + + ```sh + wget https://artifacts.elastic.co/cosign.pub + cosign verify --key cosign.pub docker.elastic.co/kibana/kibana:9.0.0-beta1 + ``` + +9. Start a {{kib}} container. + + ```sh + docker run --name kib01 --net elastic -p 5601:5601 docker.elastic.co/kibana/kibana:9.0.0-beta1 + ``` + +10. When {{kib}} starts, it outputs a unique generated link to the terminal. To access {{kib}}, open this link in a web browser. +11. In your browser, enter the enrollment token that was generated when you started {{es}}. + + To regenerate the token, run: + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana + ``` + +12. Log in to {{kib}} as the `elastic` user with the password that was generated when you started {{es}}. + + To regenerate the password, run: + + ```sh + docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic + ``` + + + +### Remove Docker containers [_remove_docker_containers] + +To remove the containers and their network, run: + +```sh +# Remove the Elastic network +docker network rm elastic + +# Remove the {es} container +docker rm es01 + +# Remove the {kib} container +docker rm kib01 +``` + + +## Configure {{kib}} on Docker [configuring-kibana-docker] + +The Docker images provide several methods for configuring {{kib}}. The conventional approach is to provide a `kibana.yml` file as described in [Configuring Kibana](configure.md), but it’s also possible to use environment variables to define settings. + + +### Bind-mounted configuration [bind-mount-config] + +One way to configure {{kib}} on Docker is to provide `kibana.yml` via bind-mounting. With `docker-compose`, the bind-mount can be specified like this: + +```yaml +version: '2' +services: + kibana: + image: docker.elastic.co/kibana/kibana:9.0.0-beta1 + volumes: + - ./kibana.yml:/usr/share/kibana/config/kibana.yml +``` + + +## Persist the {{kib}} keystore [_persist_the_kib_keystore] + +By default, {{kib}} auto-generates a keystore file for secure settings at startup. To persist your [secure settings](../../security/secure-settings.md), use the `kibana-keystore` utility to bind-mount the parent directory of the keystore to the container. For example: + +```sh +docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data docker.elastic.co/kibana/kibana:9.0.0-beta1 bin/kibana-keystore create +docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data docker.elastic.co/kibana/kibana:9.0.0-beta1 bin/kibana-keystore add test_keystore_setting +``` + + +### Environment variable configuration [environment-variable-config] + +Under Docker, {{kib}} can be configured via environment variables. When the container starts, a helper process checks the environment for variables that can be mapped to Kibana command-line arguments. + +For compatibility with container orchestration systems, these environment variables are written in all capitals, with underscores as word separators. The helper translates these names to valid {{kib}} setting names. + +::::{warning} +All information that you include in environment variables is visible through the `ps` command, including sensitive information. +:::: + + +Some example translations are shown here: + +**Environment Variable** +: **Kibana Setting** + +`SERVER_NAME` +: `server.name` + +`SERVER_BASEPATH` +: `server.basePath` + +`ELASTICSEARCH_HOSTS` +: `elasticsearch.hosts` + +In general, any setting listed in [*Configure {{kib}}*](configure.md) can be configured with this technique. + +Supplying array options can be tricky. The following example shows the syntax for providing an array to `ELASTICSEARCH_HOSTS`. + +These variables can be set with `docker-compose` like this: + +```yaml +version: '2' +services: + kibana: + image: docker.elastic.co/kibana/kibana:9.0.0-beta1 + environment: + SERVER_NAME: kibana.example.org + ELASTICSEARCH_HOSTS: '["http://es01:9200","http://es02:9200","http://es03:9200"]' +``` + +Since environment variables are translated to CLI arguments, they take precedence over settings configured in `kibana.yml`. + + +### Docker defaults [docker-defaults] + +The following settings have different default values when using the Docker images: + +`server.host` +: `"0.0.0.0"` + +`server.shutdownTimeout` +: `"5s"` + +`elasticsearch.hosts` +: `http://elasticsearch:9200` + +`monitoring.ui.container.elasticsearch.enabled` +: `true` + +These settings are defined in the default `kibana.yml`. They can be overridden with a [custom `kibana.yml`](#bind-mount-config) or via [environment variables](#environment-variable-config). + +::::{important} +If replacing `kibana.yml` with a custom version, be sure to copy the defaults to the custom file if you want to retain them. If not, they will be "masked" by the new file. +:::: diff --git a/deploy-manage/deploy/self-managed/install-with-rpm.md b/deploy-manage/deploy/self-managed/install-with-rpm.md new file mode 100644 index 000000000..277d94412 --- /dev/null +++ b/deploy-manage/deploy/self-managed/install-with-rpm.md @@ -0,0 +1,106 @@ +--- +navigation_title: "Install with RPM" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/rpm.html +--- + + + +# Install with RPM [rpm] + + +The RPM for Kibana can be [downloaded from our website](#install-rpm) or from our [RPM repository](#rpm-repo). It can be used to install Kibana on any RPM-based system such as OpenSuSE, SLES, Red Hat, and Oracle Enterprise. + +::::{note} +RPM install is not supported on distributions with old versions of RPM, such as SLES 11. Refer to [Install from archive on Linux or macOS](install-from-archive-on-linux-macos.md) instead. +:::: + + +This package contains both free and subscription features. [Start a 30-day trial](../../license/manage-your-license-in-self-managed-cluster.md) to try out all of the features. + +The latest stable version of Kibana can be found on the [Download Kibana](https://elastic.co/downloads/kibana) page. Other versions can be found on the [Past Releases page](https://elastic.co/downloads/past-releases). + +::::{tip} +For a step-by-step example of setting up the {{stack}} on your own premises, try out our tutorial: [Installing a self-managed Elastic Stack](installing-elasticsearch.md). +:::: + + +## Import the Elastic PGP key [rpm-key] + +We sign all of our packages with the Elastic Signing Key (PGP key [D88E42B4](https://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88E42B4), available from [https://pgp.mit.edu](https://pgp.mit.edu)) with fingerprint: + +``` +4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4 +``` +Download and install the public signing key: + +```sh +rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch +``` + + +## Installing from the RPM repository [rpm-repo] + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Download and install the RPM manually [install-rpm] + +Version 9.0.0-beta1 of Kibana has not yet been released. + + +## Start {{es}} and generate an enrollment token for {{kib}} [rpm-enroll] + + +When you start {{es}} for the first time, the following security configuration occurs automatically: + +* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser. +* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates. + +The password and certificate and keys are output to your terminal. + +You can then generate an enrollment token for {{kib}} with the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool: + +```sh +bin/elasticsearch-create-enrollment-token -s kibana +``` + +Start {{kib}} and enter the enrollment token to securely connect {{kib}} with {{es}}. + + +## Run {{kib}} with `systemd` [rpm-running-systemd] + +To configure {{kib}} to start automatically when the system starts, run the following commands: + +```sh +sudo /bin/systemctl daemon-reload +sudo /bin/systemctl enable kibana.service +``` + +{{kib}} can be started and stopped as follows: + +```sh +sudo systemctl start kibana.service +sudo systemctl stop kibana.service +``` + +These commands provide no feedback as to whether {{kib}} was started successfully or not. Log information can be accessed via `journalctl -u kibana.service`. + + +## Configure {{kib}} via the config file [rpm-configuring] + +Kibana loads its configuration from the `/etc/kibana/kibana.yml` file by default. The format of this config file is explained in [Configuring Kibana](configure.md). + + +## Directory layout of RPM [rpm-layout] + +The RPM places config files, logs, and the data directory in the appropriate locations for an RPM-based system: + +| Type | Description | Default Location | Setting | +| --- | --- | --- | --- | +| home | Kibana home directory or `$KIBANA_HOME` | `/usr/share/kibana` | | +| bin | Binary scripts including `kibana` to start the Kibana server and `kibana-plugin` to install plugins | `/usr/share/kibana/bin` | | +| config | Configuration files including `kibana.yml` | `/etc/kibana` | `[KBN_PATH_CONF](configure.md)` | +| data | The location of the data files written to disk by Kibana and its plugins | `/var/lib/kibana` | `path.data` | +| logs | Logs files location | `/var/log/kibana` | `[Logging configuration](../../monitor/logging-configuration/kibana-logging.md)` | +| plugins | Plugin files location. Each plugin will be contained in a subdirectory. | `/usr/share/kibana/plugins` | | diff --git a/deploy-manage/deploy/self-managed/installing-elasticsearch.md b/deploy-manage/deploy/self-managed/installing-elasticsearch.md new file mode 100644 index 000000000..0c72159e8 --- /dev/null +++ b/deploy-manage/deploy/self-managed/installing-elasticsearch.md @@ -0,0 +1,58 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-stack-security.html + - https://www.elastic.co/guide/en/elastic-stack/current/installing-stack-demo-self.html +--- + +# Installing Elasticsearch + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/340 + +% Scope notes: From the initial doc remove the reference to cloud based and the title self-managed, as this is already self-managed. We have to merge and decide the final content considering the first two documents. The one with "security" in the name doesn't really differ from the first one, as now security is enabled by default, so it's not needed anymore, but it has interesting details that might be needed on the legacy installation docs. The third doc (tutorial style) can be omitted, we leave it here for redirection purposes only. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/install-elasticsearch.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/configuring-stack-security.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/installing-stack-demo-self.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$elasticsearch-deployment-options$$$ + +$$$jvm-version$$$ + +$$$stack-security-certificates$$$ + +$$$stack-skip-auto-configuration$$$ + +$$$elasticsearch-docker-images$$$ + +$$$elasticsearch-install-packages$$$ + +$$$install-stack-self-elastic-agent$$$ + +$$$install-stack-self-elasticsearch-config$$$ + +$$$install-stack-self-elasticsearch-first$$$ + +$$$install-stack-self-elasticsearch-second$$$ + +$$$install-stack-self-elasticsearch-start$$$ + +$$$install-stack-self-elasticsearch-third$$$ + +$$$install-stack-self-fleet-server$$$ + +$$$install-stack-self-kibana$$$ + +$$$install-stack-self-next-steps$$$ + +$$$install-stack-self-overview$$$ + +$$$install-stack-self-prereqs$$$ + +$$$install-stack-self-view-data$$$ \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/local-development-installation-quickstart.md b/deploy-manage/deploy/self-managed/local-development-installation-quickstart.md new file mode 100644 index 000000000..48ede71a6 --- /dev/null +++ b/deploy-manage/deploy/self-managed/local-development-installation-quickstart.md @@ -0,0 +1,62 @@ +--- +navigation_title: "Run {{es}} locally" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/run-elasticsearch-locally.html +--- + + + +# Local development installation (quickstart) [run-elasticsearch-locally] + + +::::{warning} +**DO NOT USE THESE INSTRUCTIONS FOR PRODUCTION DEPLOYMENTS** + +The instructions on this page are for **local development only**. Do not use this configuration for production deployments, because it is not secure. Refer to [deployment options](../../../get-started/deployment-options.md) for a list of production deployment options. + +:::: + + +Quickly set up {{es}} and {{kib}} in Docker for local development or testing, using the [`start-local` script](https://github.com/elastic/start-local?tab=readme-ov-file#-try-elasticsearch-and-kibana-locally). + +This setup comes with a one-month trial license that includes all Elastic features. After the trial period, the license reverts to **Free and open - Basic**. Refer to [Elastic subscriptions](https://www.elastic.co/subscriptions) for more information. + + +## Prerequisites [local-dev-prerequisites] + +* If you don’t have Docker installed, [download and install Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. +* If you’re using Microsoft Windows, then install [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install). + + +## Run `start-local` [local-dev-quick-start] + +To set up {{es}} and {{kib}} locally, run the `start-local` script: + +```sh +curl -fsSL https://elastic.co/start-local | sh +``` + +This script creates an `elastic-start-local` folder containing configuration files and starts both {{es}} and {{kib}} using Docker. + +After running the script, you can access Elastic services at the following endpoints: + +* **{{es}}**: [http://localhost:9200](http://localhost:9200) +* **{{kib}}**: [http://localhost:5601](http://localhost:5601) + +The script generates a random password for the `elastic` user, and an API key, stored in the `.env` file. + +::::{warning} +This setup is for local testing only. HTTPS is disabled, and Basic authentication is used for {{es}}. For security, {{es}} and {{kib}} are accessible only through `localhost`. + +:::: + + + +## Learn more [local-dev-additional-info] + +For more detailed information about the `start-local` setup, refer to the [README on GitHub](https://github.com/elastic/start-local). Learn about customizing the setup, logging, and more. + + +## Next steps [local-dev-next-steps] + +Use our [quick start guides](https://www.elastic.co/guide/en/elasticsearch/reference/current/quickstart.html) to learn the basics of {{es}}. diff --git a/deploy-manage/deploy/self-managed/max-number-of-threads.md b/deploy-manage/deploy/self-managed/max-number-of-threads.md new file mode 100644 index 000000000..2054bbbe0 --- /dev/null +++ b/deploy-manage/deploy/self-managed/max-number-of-threads.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/max-number-of-threads.html +--- + +# Number of threads [max-number-of-threads] + +Elasticsearch uses a number of thread pools for different types of operations. It is important that it is able to create new threads whenever needed. Make sure that the number of threads that the Elasticsearch user can create is at least 4096. + +This can be done by setting [`ulimit -u 4096`](setting-system-settings.md#ulimit) as root before starting Elasticsearch, or by setting `nproc` to `4096` in [`/etc/security/limits.conf`](setting-system-settings.md#limits.conf). + +The package distributions when run as services under `systemd` will configure the number of threads for the Elasticsearch process automatically. No additional configuration is required. + diff --git a/deploy-manage/deploy/self-managed/max-number-threads-check.md b/deploy-manage/deploy/self-managed/max-number-threads-check.md new file mode 100644 index 000000000..13f84ff37 --- /dev/null +++ b/deploy-manage/deploy/self-managed/max-number-threads-check.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/max-number-threads-check.html +--- + +# Maximum number of threads check [max-number-threads-check] + +Elasticsearch executes requests by breaking the request down into stages and handing those stages off to different thread pool executors. There are different [thread pool executors](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-threadpool.html) for a variety of tasks within Elasticsearch. Thus, Elasticsearch needs the ability to create a lot of threads. The maximum number of threads check ensures that the Elasticsearch process has the rights to create enough threads under normal use. This check is enforced only on Linux. If you are on Linux, to pass the maximum number of threads check, you must configure your system to allow the Elasticsearch process the ability to create at least 4096 threads. This can be done via `/etc/security/limits.conf` using the `nproc` setting (note that you might have to increase the limits for the `root` user too). + diff --git a/deploy-manage/deploy/self-managed/max-size-virtual-memory-check.md b/deploy-manage/deploy/self-managed/max-size-virtual-memory-check.md new file mode 100644 index 000000000..ef6d33d1a --- /dev/null +++ b/deploy-manage/deploy/self-managed/max-size-virtual-memory-check.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/max-size-virtual-memory-check.html +--- + +# Maximum size virtual memory check [max-size-virtual-memory-check] + +Elasticsearch and Lucene use `mmap` to great effect to map portions of an index into the Elasticsearch address space. This keeps certain index data off the JVM heap but in memory for blazing fast access. For this to be effective, the Elasticsearch should have unlimited address space. The maximum size virtual memory check enforces that the Elasticsearch process has unlimited address space and is enforced only on Linux. To pass the maximum size virtual memory check, you must configure your system to allow the Elasticsearch process the ability to have unlimited address space. This can be done via adding ` - as unlimited` to `/etc/security/limits.conf`. This may require you to increase the limits for the `root` user too. + diff --git a/deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md b/deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md new file mode 100644 index 000000000..4c792228a --- /dev/null +++ b/deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md @@ -0,0 +1,9 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/networkaddress-cache-ttl.html +--- + +# DNS cache settings [networkaddress-cache-ttl] + +Elasticsearch runs with a security manager in place. With a security manager in place, the JVM defaults to caching positive hostname resolutions indefinitely and defaults to caching negative hostname resolutions for ten seconds. Elasticsearch overrides this behavior with default values to cache positive lookups for sixty seconds, and to cache negative lookups for ten seconds. These values should be suitable for most environments, including environments where DNS resolutions vary with time. If not, you can edit the values `es.networkaddress.cache.ttl` and `es.networkaddress.cache.negative.ttl` in the [JVM options](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options). Note that the values [`networkaddress.cache.ttl=`](https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.md) and [`networkaddress.cache.negative.ttl=`](https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.md) in the [Java security policy](https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.md) are ignored by Elasticsearch unless you remove the settings for `es.networkaddress.cache.ttl` and `es.networkaddress.cache.negative.ttl`. + diff --git a/deploy-manage/deploy/self-managed/other-configuration-settings.md b/deploy-manage/deploy/self-managed/other-configuration-settings.md new file mode 100644 index 000000000..0e5554f28 --- /dev/null +++ b/deploy-manage/deploy/self-managed/other-configuration-settings.md @@ -0,0 +1,7 @@ +# Other configuration settings + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/340 + +% Scope notes: Link to reference documentation? Where are we going to allocate the rest of the config settings? Reference? \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/plugins.md b/deploy-manage/deploy/self-managed/plugins.md new file mode 100644 index 000000000..4e294e857 --- /dev/null +++ b/deploy-manage/deploy/self-managed/plugins.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-plugins.html +--- + +# Plugins [modules-plugins] + +Plugins are a way to enhance the basic Elasticsearch functionality in a custom manner. They range from adding custom mapping types, custom analyzers (in a more built in fashion), custom script engines, custom discovery and more. + +For information about selecting and installing plugins, see [{{es}} Plugins and Integrations](https://www.elastic.co/guide/en/elasticsearch/plugins/current/index.html). + +For information about developing your own plugin, see [Help for plugin authors](https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugin-authors.html). + diff --git a/deploy-manage/deploy/self-managed/setting-system-settings.md b/deploy-manage/deploy/self-managed/setting-system-settings.md new file mode 100644 index 000000000..3679079cf --- /dev/null +++ b/deploy-manage/deploy/self-managed/setting-system-settings.md @@ -0,0 +1,92 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-system-settings.html +--- + +# Configuring system settings [setting-system-settings] + +Where to configure systems settings depends on which package you have used to install Elasticsearch, and which operating system you are using. + +When using the `.zip` or `.tar.gz` packages, system settings can be configured: + +* Temporarily with [`ulimit`](#ulimit). +* Permanently in [`/etc/security/limits.conf`](#limits.conf). + +When using the RPM or Debian packages, most system settings are set in the [system configuration file](#sysconfig). However, systems which use systemd require that system limits are specified in a [systemd configuration file](#systemd). + +## `ulimit` [ulimit] + +On Linux systems, `ulimit` can be used to change resource limits on a temporary basis. Limits usually need to be set as `root` before switching to the user that will run Elasticsearch. For example, to set the number of open file handles (`ulimit -n`) to 65,535, you can do the following: + +```sh +sudo su <1> +ulimit -n 65535 <2> +su elasticsearch <3> +``` + +1. Become `root`. +2. Change the max number of open files. +3. Become the `elasticsearch` user in order to start Elasticsearch. + + +The new limit is only applied during the current session. + +You can consult all currently applied limits with `ulimit -a`. + + +## `/etc/security/limits.conf` [limits.conf] + +On Linux systems, persistent limits can be set for a particular user by editing the `/etc/security/limits.conf` file. To set the maximum number of open files for the `elasticsearch` user to 65,535, add the following line to the `limits.conf` file: + +```sh +elasticsearch - nofile 65535 +``` + +This change will only take effect the next time the `elasticsearch` user opens a new session. + +::::{admonition} Ubuntu and `limits.conf` +:class: note + +Ubuntu ignores the `limits.conf` file for processes started by `init.d`. To enable the `limits.conf` file, edit `/etc/pam.d/su` and uncomment the following line: + +```sh +# session required pam_limits.so +``` + +:::: + + + +## Sysconfig file [sysconfig] + +When using the RPM or Debian packages, environment variables can be specified in the system configuration file, which is located in: + +RPM +: `/etc/sysconfig/elasticsearch` + +Debian +: `/etc/default/elasticsearch` + +However, system limits need to be specified via [systemd](#systemd). + + +## Systemd configuration [systemd] + +When using the RPM or Debian packages on systems that use [systemd](https://en.wikipedia.org/wiki/Systemd), system limits must be specified via systemd. + +The systemd service file (`/usr/lib/systemd/system/elasticsearch.service`) contains the limits that are applied by default. + +To override them, add a file called `/etc/systemd/system/elasticsearch.service.d/override.conf` (alternatively, you may run `sudo systemctl edit elasticsearch` which opens the file automatically inside your default editor). Set any changes in this file, such as: + +```sh +[Service] +LimitMEMLOCK=infinity +``` + +Once finished, run the following command to reload units: + +```sh +sudo systemctl daemon-reload +``` + + diff --git a/deploy-manage/deploy/self-managed/setup-configuration-memory.md b/deploy-manage/deploy/self-managed/setup-configuration-memory.md new file mode 100644 index 000000000..1c60e1357 --- /dev/null +++ b/deploy-manage/deploy/self-managed/setup-configuration-memory.md @@ -0,0 +1,86 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-configuration-memory.html +--- + +# Disable swapping [setup-configuration-memory] + +Most operating systems try to use as much memory as possible for file system caches and eagerly swap out unused application memory. This can result in parts of the JVM heap or even its executable pages being swapped out to disk. + +Swapping is very bad for performance, for node stability, and should be avoided at all costs. It can cause garbage collections to last for **minutes** instead of milliseconds and can cause nodes to respond slowly or even to disconnect from the cluster. In a resilient distributed system, it’s more effective to let the operating system kill the node. + +There are three approaches to disabling swapping. The preferred option is to completely disable swap. If this is not an option, whether or not to prefer minimizing swappiness versus memory locking is dependent on your environment. + +## Disable all swap files [disable-swap-files] + +Usually Elasticsearch is the only service running on a box, and its memory usage is controlled by the JVM options. There should be no need to have swap enabled. + +On Linux systems, you can disable swap temporarily by running: + +```sh +sudo swapoff -a +``` + +This doesn’t require a restart of Elasticsearch. + +To disable it permanently, you will need to edit the `/etc/fstab` file and comment out any lines that contain the word `swap`. + +On Windows, the equivalent can be achieved by disabling the paging file entirely via `System Properties → Advanced → Performance → Advanced → Virtual memory`. + + +## Configure `swappiness` [swappiness] + +Another option available on Linux systems is to ensure that the sysctl value `vm.swappiness` is set to `1`. This reduces the kernel’s tendency to swap and should not lead to swapping under normal circumstances, while still allowing the whole system to swap in emergency conditions. + + +## Enable `bootstrap.memory_lock` [bootstrap-memory_lock] + +Another option is to use [mlockall](http://opengroup.org/onlinepubs/007908799/xsh/mlockall.md) on Linux/Unix systems, or [VirtualLock](https://msdn.microsoft.com/en-us/library/windows/desktop/aa366895%28v=vs.85%29.aspx) on Windows, to try to lock the process address space into RAM, preventing any {{es}} heap memory from being swapped out. + +::::{note} +Some platforms still swap off-heap memory when using a memory lock. To prevent off-heap memory swaps, [disable all swap files](#disable-swap-files) instead. +:::: + + +To enable a memory lock, set `bootstrap.memory_lock` to `true` in `elasticsearch.yml`: + +```yaml +bootstrap.memory_lock: true +``` + +::::{warning} +`mlockall` might cause the JVM or shell session to exit if it tries to allocate more memory than is available! +:::: + + +After starting Elasticsearch, you can see whether this setting was applied successfully by checking the value of `mlockall` in the output from this request: + +```console +GET _nodes?filter_path=**.mlockall +``` + +If you see that `mlockall` is `false`, then it means that the `mlockall` request has failed. You will also see a line with more information in the logs with the words `Unable to lock JVM Memory`. + +The most probable reason, on Linux/Unix systems, is that the user running Elasticsearch doesn’t have permission to lock memory. This can be granted as follows: + +`.zip` and `.tar.gz` +: Set [`ulimit -l unlimited`](setting-system-settings.md#ulimit) as root before starting {{es}}. Alternatively, set `memlock` to `unlimited` in `/etc/security/limits.conf`: + + ```sh + # allow user 'elasticsearch' mlockall + elasticsearch soft memlock unlimited + elasticsearch hard memlock unlimited + ``` + + +RPM and Debian +: Set `LimitMEMLOCK` to `infinity` in the [systemd configuration](setting-system-settings.md#systemd). + +Another possible reason why `mlockall` can fail is that [the JNA temporary directory (usually a sub-directory of `/tmp`) is mounted with the `noexec` option](executable-jna-tmpdir.md). This can be solved by specifying a new temporary directory for JNA using the `ES_JAVA_OPTS` environment variable: + +```sh +export ES_JAVA_OPTS="$ES_JAVA_OPTS -Djna.tmpdir=" +./bin/elasticsearch +``` + +or setting this JVM flag in the jvm.options configuration file. diff --git a/deploy-manage/deploy/self-managed/system-config-tcpretries.md b/deploy-manage/deploy/self-managed/system-config-tcpretries.md new file mode 100644 index 000000000..c57074af1 --- /dev/null +++ b/deploy-manage/deploy/self-managed/system-config-tcpretries.md @@ -0,0 +1,35 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/system-config-tcpretries.html +--- + +# TCP retransmission timeout [system-config-tcpretries] + +Each pair of {{es}} nodes communicates via a number of TCP connections which [remain open](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#long-lived-connections) until one of the nodes shuts down or communication between the nodes is disrupted by a failure in the underlying infrastructure. + +TCP provides reliable communication over occasionally unreliable networks by hiding temporary network disruptions from the communicating applications. Your operating system will retransmit any lost messages a number of times before informing the sender of any problem. {{es}} must wait while the retransmissions are happening and can only react once the operating system decides to give up. Users must therefore also wait for a sequence of retransmissions to complete. + +Most Linux distributions default to retransmitting any lost packets 15 times. Retransmissions back off exponentially, so these 15 retransmissions take over 900 seconds to complete. This means it takes Linux many minutes to detect a network partition or a failed node with this method. Windows defaults to just 5 retransmissions which corresponds with a timeout of around 13 seconds. + +The Linux default allows for communication over networks that may experience very long periods of packet loss, but this default is excessive and even harmful on the high quality networks used by most {{es}} installations. When a cluster detects a node failure it reacts by reallocating lost shards, rerouting searches, and maybe electing a new master node. Highly available clusters must be able to detect node failures promptly, which can be achieved by reducing the permitted number of retransmissions. Connections to [remote clusters](../../remote-clusters.md) should also prefer to detect failures much more quickly than the Linux default allows. Linux users should therefore reduce the maximum number of TCP retransmissions. + +You can decrease the maximum number of TCP retransmissions to `5` by running the following command as `root`. Five retransmissions corresponds with a timeout of around 13 seconds. + +```sh +sysctl -w net.ipv4.tcp_retries2=5 +``` + +To set this value permanently, update the `net.ipv4.tcp_retries2` setting in `/etc/sysctl.conf`. To verify after rebooting, run `sysctl net.ipv4.tcp_retries2`. + +::::{important} +This setting applies to all TCP connections and will affect the reliability of communication with systems other than {{es}} clusters too. If your clusters communicate with external systems over a low quality network then you may need to select a higher value for `net.ipv4.tcp_retries2`. For this reason, {{es}} does not adjust this setting automatically. +:::: + + +## Related configuration [_related_configuration] + +{{es}} also implements its own internal health checks with timeouts that are much shorter than the default retransmission timeout on Linux. Since these are application-level health checks their timeouts must allow for application-level effects such as garbage collection pauses. You should not reduce any timeouts related to these application-level health checks. + +You must also ensure your network infrastructure does not interfere with the long-lived connections between nodes, [even if those connections appear to be idle](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#long-lived-connections). Devices which drop connections when they reach a certain age are a common source of problems to {{es}} clusters, and must not be used. + + diff --git a/deploy-manage/deploy/self-managed/tools-apis.md b/deploy-manage/deploy/self-managed/tools-apis.md new file mode 100644 index 000000000..6502ce5d4 --- /dev/null +++ b/deploy-manage/deploy/self-managed/tools-apis.md @@ -0,0 +1,5 @@ +# Tools and APIs + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/310 \ No newline at end of file diff --git a/deploy-manage/deploy/self-managed/vm-max-map-count.md b/deploy-manage/deploy/self-managed/vm-max-map-count.md new file mode 100644 index 000000000..29c8964e7 --- /dev/null +++ b/deploy-manage/deploy/self-managed/vm-max-map-count.md @@ -0,0 +1,25 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html +--- + +# Virtual memory [vm-max-map-count] + +Elasticsearch uses a [`mmapfs`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-store.html#mmapfs) directory by default to store its indices. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions. + +On Linux, you can increase the limits by running the following command as `root`: + +```sh +sysctl -w vm.max_map_count=262144 +``` + +To set this value permanently, update the `vm.max_map_count` setting in `/etc/sysctl.conf`. To verify after rebooting, run `sysctl vm.max_map_count`. + +The RPM and Debian packages will configure this setting automatically. No further configuration is required. + +You can find out the current mmap count of a running Elasticsearch process using the following command, where `$PID` is the process ID of the running Elasticsearch process: + +```sh +wc -l /proc/$PID/maps +``` + diff --git a/deploy-manage/distributed-architecture.md b/deploy-manage/distributed-architecture.md new file mode 100644 index 000000000..0800fda4d --- /dev/null +++ b/deploy-manage/distributed-architecture.md @@ -0,0 +1,20 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_data_store_architecture.html +--- + +# Distributed architecture [_data_store_architecture] + +{{es}} is a distributed document store. Instead of storing information as rows of columnar data, {{es}} stores complex data structures that have been serialized as JSON documents. When you have multiple {{es}} nodes in a cluster, stored documents are distributed across the cluster and can be accessed immediately from any node. + +The topics in this section provides information about the architecture of {{es}} and how it stores and retrieves data: + +* [Nodes and shards](distributed-architecture/clusters-nodes-shards.md): Learn about the basic building blocks of an {{es}} cluster, including nodes, shards, primaries, and replicas. +* [Node roles](distributed-architecture/clusters-nodes-shards/node-roles.md): Learn about the different roles that nodes can have in an {{es}} cluster. +* [Reading and writing documents](distributed-architecture/reading-and-writing-documents.md): Learn how {{es}} replicates read and write operations across shards and shard copies. +* [Shard allocation, relocation, and recovery](distributed-architecture/shard-allocation-relocation-recovery.md): Learn how {{es}} allocates and balances shards across nodes. + + * [Shard allocation awareness](distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md): Learn how to use custom node attributes to distribute shards across different racks or availability zones. + +* [Shard request cache](https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-request-cache.html): Learn how {{es}} caches search requests to improve performance. + diff --git a/deploy-manage/distributed-architecture/clusters-nodes-shards.md b/deploy-manage/distributed-architecture/clusters-nodes-shards.md new file mode 100644 index 000000000..3fe41b1c9 --- /dev/null +++ b/deploy-manage/distributed-architecture/clusters-nodes-shards.md @@ -0,0 +1,37 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/nodes-shards.html +--- + +# Clusters, nodes, and shards [nodes-shards] + +::::{note} +Nodes and shards are what make {{es}} distributed and scalable. These concepts aren’t essential if you’re just getting started. How you [deploy {{es}}](../../get-started/deployment-options.md) in production determines what you need to know: + +* **Self-managed {{es}}**: You are responsible for setting up and managing nodes, clusters, shards, and replicas. This includes managing the underlying infrastructure, scaling, and ensuring high availability through failover and backup strategies. +* **Elastic Cloud**: Elastic can autoscale resources in response to workload changes. Choose from different deployment types to apply sensible defaults for your use case. A basic understanding of nodes, shards, and replicas is still important. +* **Elastic Cloud Serverless**: You don’t need to worry about nodes, shards, or replicas. These resources are 100% automated on the serverless platform, which is designed to scale with your workload. + +:::: + + +You can add servers (*nodes*) to a cluster to increase capacity, and {{es}} automatically distributes your data and query load across all of the available nodes. + +Elastic is able to distribute your data across nodes by subdividing an index into *shards*. Each index in {{es}} is a grouping of one or more physical shards, where each shard is a self-contained Lucene index containing a subset of the documents in the index. By distributing the documents in an index across multiple shards, and distributing those shards across multiple nodes, {{es}} increases indexing and query capacity. + +There are two types of shards: *primaries* and *replicas*. Each document in an index belongs to one primary shard. A replica shard is a copy of a primary shard. Replicas maintain redundant copies of your data across the nodes in your cluster. This protects against hardware failure and increases capacity to serve read requests like searching or retrieving a document. + +::::{tip} +The number of primary shards in an index is fixed at the time that an index is created, but the number of replica shards can be changed at any time, without interrupting indexing or query operations. + +:::: + + +Shard copies in your cluster are automatically balanced across nodes to provide scale and high availability. All nodes are aware of all the other nodes in the cluster and can forward client requests to the appropriate node. This allows {{es}} to distribute indexing and query load across the cluster. + +If you’re exploring {{es}} for the first time or working in a development environment, then you can use a cluster with a single node and create indices with only one shard. However, in a production environment, you should build a cluster with multiple nodes and indices with multiple shards to increase performance and resilience. + +* To learn about optimizing the number and size of shards in your cluster, refer to [Size your shards](../production-guidance/optimize-performance/size-shards.md). +* To learn about how read and write operations are replicated across shards and shard copies, refer to [Reading and writing documents](reading-and-writing-documents.md). +* To adjust how shards are allocated and balanced across nodes, refer to [Shard allocation, relocation, and recovery](shard-allocation-relocation-recovery.md). + diff --git a/deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md b/deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md new file mode 100644 index 000000000..61eadab4e --- /dev/null +++ b/deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md @@ -0,0 +1,311 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/node-roles-overview.html +--- + +# Node roles [node-roles-overview] + +Any time that you start an instance of {{es}}, you are starting a *node*. A collection of connected nodes is called a [cluster](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html). If you are running a single node of {{es}}, then you have a cluster of one node. All nodes know about all the other nodes in the cluster and can forward client requests to the appropriate node. + +Each node performs one or more roles. Roles control the behavior of the node in the cluster. + + +## Set node roles [set-node-roles] + +You define a node’s roles by setting `node.roles` in [`elasticsearch.yml`](../../deploy/self-managed/configure-elasticsearch.md). If you set `node.roles`, the node is only assigned the roles you specify. If you don’t set `node.roles`, the node is assigned the following roles: + +* `master` +* `data` +* `data_content` +* `data_hot` +* `data_warm` +* `data_cold` +* `data_frozen` +* `ingest` +* `ml` +* `remote_cluster_client` +* `transform` + +::::{important} +If you set `node.roles`, ensure you specify every node role your cluster needs. Every cluster requires the following node roles: + +* `master` +* + + `data_content` and `data_hot`
OR
`data` + + +Some {{stack}} features also require specific node roles: + +* {{ccs-cap}} and {{ccr}} require the `remote_cluster_client` role. +* {{stack-monitor-app}} and ingest pipelines require the `ingest` role. +* {{fleet}}, the {{security-app}}, and {{transforms}} require the `transform` role. The `remote_cluster_client` role is also required to use {{ccs}} with these features. +* {{ml-cap}} features, such as {{anomaly-detect}}, require the `ml` role. + +:::: + + +As the cluster grows and in particular if you have large {{ml}} jobs or {{ctransforms}}, consider separating dedicated master-eligible nodes from dedicated data nodes, {{ml}} nodes, and {{transform}} nodes. + + +## Change the role of a node [change-node-role] + +Each data node maintains the following data on disk: + +* the shard data for every shard allocated to that node, +* the index metadata corresponding with every shard allocated to that node, and +* the cluster-wide metadata, such as settings and index templates. + +Similarly, each master-eligible node maintains the following data on disk: + +* the index metadata for every index in the cluster, and +* the cluster-wide metadata, such as settings and index templates. + +Each node checks the contents of its data path at startup. If it discovers unexpected data then it will refuse to start. This is to avoid importing unwanted [dangling indices](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-gateway.html#dangling-indices) which can lead to a red cluster health. To be more precise, nodes without the `data` role will refuse to start if they find any shard data on disk at startup, and nodes without both the `master` and `data` roles will refuse to start if they have any index metadata on disk at startup. + +It is possible to change the roles of a node by adjusting its `elasticsearch.yml` file and restarting it. This is known as *repurposing* a node. In order to satisfy the checks for unexpected data described above, you must perform some extra steps to prepare a node for repurposing when starting the node without the `data` or `master` roles. + +* If you want to repurpose a data node by removing the `data` role then you should first use an [allocation filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-shard-allocation-filtering) to safely migrate all the shard data onto other nodes in the cluster. +* If you want to repurpose a node to have neither the `data` nor `master` roles then it is simplest to start a brand-new node with an empty data path and the desired roles. You may find it safest to use an [allocation filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-shard-allocation-filtering) to migrate the shard data elsewhere in the cluster first. + +If it is not possible to follow these extra steps then you may be able to use the [`elasticsearch-node repurpose`](https://www.elastic.co/guide/en/elasticsearch/reference/current/node-tool.html#node-tool-repurpose) tool to delete any excess data that prevents a node from starting. + + +## Available node roles [node-roles-list] + +The following is a list of the roles that a node can perform in a cluster. A node can have one or more roles. + +* [Master-eligible node](#master-node-role) (`master`): A node that is eligible to be [elected as the *master* node](../discovery-cluster-formation.md), which controls the cluster. +* [Data node](#data-node-role) (`data`, `data_content`, `data_hot`, `data_warm`, `data_cold`, `data_frozen`): A node that has one of several data roles. Data nodes hold data and perform data related operations such as CRUD, search, and aggregations. You might use multiple data roles in a cluster so you can implement [data tiers](../../../manage-data/lifecycle/data-tiers.md). +* [Ingest node](#node-ingest-node) (`ingest`): Ingest nodes are able to apply an [ingest pipeline](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md) to a document in order to transform and enrich the document before indexing. With a heavy ingest load, it makes sense to use dedicated ingest nodes and to not include the `ingest` role from nodes that have the `master` or `data` roles. +* [Remote-eligible node](#remote-node) (`remote_cluster_client`): A node that is eligible to act as a remote client. +* [Machine learning node](#ml-node-role) (`ml`): A node that can run {{ml-features}}. If you want to use {{ml-features}}, there must be at least one {{ml}} node in your cluster. For more information, see [Machine learning settings](../../deploy/self-managed/configure-elasticsearch.md) and [Machine learning in the {{stack}}](https://www.elastic.co/guide/en/machine-learning/current/index.html). +* [{{transform-cap}} node](#transform-node-role) (`transform`): A node that can perform {{transforms}}. If you want to use {{transforms}}, there must be at least one {{transform}} node in your cluster. For more information, see [{{transforms-cap}} settings](../../deploy/self-managed/configure-elasticsearch.md) and [*Transforming data*](../../../explore-analyze/transforms.md). + +::::{admonition} Coordinating node +:class: note + +:name: coordinating-node + +Requests like search requests or bulk-indexing requests may involve data held on different data nodes. A search request, for example, is executed in two phases which are coordinated by the node which receives the client request — the *coordinating node*. + +In the *scatter* phase, the coordinating node forwards the request to the data nodes which hold the data. Each data node executes the request locally and returns its results to the coordinating node. In the *gather* phase, the coordinating node reduces each data node’s results into a single global result set. + +Every node is implicitly a coordinating node. This means that a node that has an explicit empty list of roles in the `node.roles` setting will only act as a coordinating node, which cannot be disabled. As a result, such a node needs to have enough memory and CPU in order to deal with the gather phase. + +:::: + + + +### Master-eligible node [master-node-role] + +The master node is responsible for lightweight cluster-wide actions such as creating or deleting an index, tracking which nodes are part of the cluster, and deciding which shards to allocate to which nodes. It is important for cluster health to have a stable master node. + +Any master-eligible node that is not a [voting-only node](#voting-only-node) may be elected to become the master node by the [master election process](../discovery-cluster-formation.md). + +::::{important} +Master nodes must have a `path.data` directory whose contents persist across restarts, just like data nodes, because this is where the cluster metadata is stored. The cluster metadata describes how to read the data stored on the data nodes, so if it is lost then the data stored on the data nodes cannot be read. +:::: + + + +#### Dedicated master-eligible node [dedicated-master-node] + +It is important for the health of the cluster that the elected master node has the resources it needs to fulfill its responsibilities. If the elected master node is overloaded with other tasks then the cluster will not operate well. The most reliable way to avoid overloading the master with other tasks is to configure all the master-eligible nodes to be *dedicated master-eligible nodes* which only have the `master` role, allowing them to focus on managing the cluster. Master-eligible nodes will still also behave as [coordinating nodes](#coordinating-node) that route requests from clients to the other nodes in the cluster, but you should *not* use dedicated master nodes for this purpose. + +A small or lightly-loaded cluster may operate well if its master-eligible nodes have other roles and responsibilities, but once your cluster comprises more than a handful of nodes it usually makes sense to use dedicated master-eligible nodes. + +To create a dedicated master-eligible node, set: + +```yaml +node.roles: [ master ] +``` + + +#### Voting-only master-eligible node [voting-only-node] + +A voting-only master-eligible node is a node that participates in [master elections](../discovery-cluster-formation.md) but which will not act as the cluster’s elected master node. In particular, a voting-only node can serve as a tiebreaker in elections. + +It may seem confusing to use the term "master-eligible" to describe a voting-only node since such a node is not actually eligible to become the master at all. This terminology is an unfortunate consequence of history: master-eligible nodes are those nodes that participate in elections and perform certain tasks during cluster state publications, and voting-only nodes have the same responsibilities even if they can never become the elected master. + +To configure a master-eligible node as a voting-only node, include `master` and `voting_only` in the list of roles. For example to create a voting-only data node: + +```yaml +node.roles: [ data, master, voting_only ] +``` + +::::{important} +Only nodes with the `master` role can be marked as having the `voting_only` role. +:::: + + +High availability (HA) clusters require at least three master-eligible nodes, at least two of which are not voting-only nodes. Such a cluster will be able to elect a master node even if one of the nodes fails. + +Voting-only master-eligible nodes may also fill other roles in your cluster. For instance, a node may be both a data node and a voting-only master-eligible node. A *dedicated* voting-only master-eligible nodes is a voting-only master-eligible node that fills no other roles in the cluster. To create a dedicated voting-only master-eligible node, set: + +```yaml +node.roles: [ master, voting_only ] +``` + +Since dedicated voting-only nodes never act as the cluster’s elected master, they may require less heap and a less powerful CPU than the true master nodes. However all master-eligible nodes, including voting-only nodes, are on the critical path for [publishing cluster state updates](../discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing). Cluster state updates are usually independent of performance-critical workloads such as indexing or searches, but they are involved in management activities such as index creation and rollover, mapping updates, and recovery after a failure. The performance characteristics of these activities are a function of the speed of the storage on each master-eligible node, as well as the reliability and latency of the network interconnections between the elected master node and the other nodes in the cluster. You must therefore ensure that the storage and networking available to the nodes in your cluster are good enough to meet your performance goals. + + +### Data nodes [data-node-role] + +Data nodes hold the shards that contain the documents you have indexed. Data nodes handle data related operations like CRUD, search, and aggregations. These operations are I/O-, memory-, and CPU-intensive. It is important to monitor these resources and to add more data nodes if they are overloaded. + +The main benefit of having dedicated data nodes is the separation of the master and data roles. + +In a multi-tier deployment architecture, you use specialized data roles to assign data nodes to specific tiers: `data_content`,`data_hot`, `data_warm`, `data_cold`, or `data_frozen`. A node can belong to multiple tiers. + +If you want to include a node in all tiers, or if your cluster does not use multiple tiers, then you can use the generic `data` role. + +[Cluster shard limits](../../deploy/self-managed/configure-elasticsearch.md#cluster-shard-limit) prevent creation of more than 1000 non-frozen shards per node, and 3000 frozen shards per dedicated frozen node. Make sure you have enough nodes of each type in your cluster to handle the number of shards you need. + +::::{warning} +If you assign a node to a specific tier using a specialized data role, then you shouldn’t also assign it the generic `data` role. The generic `data` role takes precedence over specialized data roles. +:::: + + + +#### Generic data node [generic-data-node] + +Generic data nodes are included in all content tiers. A node with a generic `data` role can fill any of the specialized data node roles. + +To create a dedicated generic data node, set: + +```yaml +node.roles: [ data ] +``` + + +#### Content data node [data-content-node] + +Content data nodes are part of the content tier. Data stored in the content tier is generally a collection of items such as a product catalog or article archive. Unlike time series data, the value of the content remains relatively constant over time, so it doesn’t make sense to move it to a tier with different performance characteristics as it ages. Content data typically has long data retention requirements, and you want to be able to retrieve items quickly regardless of how old they are. + +Content tier nodes are usually optimized for query performance—​they prioritize processing power over IO throughput so they can process complex searches and aggregations and return results quickly. While they are also responsible for indexing, content data is generally not ingested at as high a rate as time series data such as logs and metrics. From a resiliency perspective the indices in this tier should be configured to use one or more replicas. + +The content tier is required and is often deployed within the same node grouping as the hot tier. System indices and other indices that aren’t part of a data stream are automatically allocated to the content tier. + +To create a dedicated content node, set: + +```yaml +node.roles: [ data_content ] +``` + + +#### Hot data node [data-hot-node] + +Hot data nodes are part of the hot tier. The hot tier is the {{es}} entry point for time series data and holds your most-recent, most-frequently-searched time series data. Nodes in the hot tier need to be fast for both reads and writes, which requires more hardware resources and faster storage (SSDs). For resiliency, indices in the hot tier should be configured to use one or more replicas. + +The hot tier is required. New indices that are part of a [data stream](../../../manage-data/data-store/index-types/data-streams.md) are automatically allocated to the hot tier. + +To create a dedicated hot node, set: + +```yaml +node.roles: [ data_hot ] +``` + + +#### Warm data node [data-warm-node] + +Warm data nodes are part of the warm tier. Time series data can move to the warm tier once it is being queried less frequently than the recently-indexed data in the hot tier. The warm tier typically holds data from recent weeks. Updates are still allowed, but likely infrequent. Nodes in the warm tier generally don’t need to be as fast as those in the hot tier. For resiliency, indices in the warm tier should be configured to use one or more replicas. + +To create a dedicated warm node, set: + +```yaml +node.roles: [ data_warm ] +``` + + +#### Cold data node [data-cold-node] + +Cold data nodes are part of the cold tier. When you no longer need to search time series data regularly, it can move from the warm tier to the cold tier. While still searchable, this tier is typically optimized for lower storage costs rather than search speed. + +For better storage savings, you can keep [fully mounted indices](../../tools/snapshot-and-restore/searchable-snapshots.md#fully-mounted) of [{{search-snaps}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-searchable-snapshot.html) on the cold tier. Unlike regular indices, these fully mounted indices don’t require replicas for reliability. In the event of a failure, they can recover data from the underlying snapshot instead. This potentially halves the local storage needed for the data. A snapshot repository is required to use fully mounted indices in the cold tier. Fully mounted indices are read-only. + +Alternatively, you can use the cold tier to store regular indices with replicas instead of using {{search-snaps}}. This lets you store older data on less expensive hardware but doesn’t reduce required disk space compared to the warm tier. + +To create a dedicated cold node, set: + +```yaml +node.roles: [ data_cold ] +``` + + +#### Frozen data node [data-frozen-node] + +Frozen data nodes are part of the frozen tier. Once data is no longer being queried, or being queried rarely, it may move from the cold tier to the frozen tier where it stays for the rest of its life. + +The frozen tier requires a snapshot repository. The frozen tier uses [partially mounted indices](../../tools/snapshot-and-restore/searchable-snapshots.md#partially-mounted) to store and load data from a snapshot repository. This reduces local storage and operating costs while still letting you search frozen data. Because {{es}} must sometimes fetch frozen data from the snapshot repository, searches on the frozen tier are typically slower than on the cold tier. + +To create a dedicated frozen node, set: + +```yaml +node.roles: [ data_frozen ] +``` + + +### Ingest node [node-ingest-node] + +Ingest nodes can execute pre-processing pipelines, composed of one or more ingest processors. Depending on the type of operations performed by the ingest processors and the required resources, it may make sense to have dedicated ingest nodes, that will only perform this specific task. + +To create a dedicated ingest node, set: + +```yaml +node.roles: [ ingest ] +``` + + +### Coordinating only node [coordinating-only-node-role] + +If you take away the ability to be able to handle master duties, to hold data, and pre-process documents, then you are left with a *coordinating* node that can only route requests, handle the search reduce phase, and distribute bulk indexing. Essentially, coordinating only nodes behave as smart load balancers. + +Coordinating only nodes can benefit large clusters by offloading the coordinating node role from data and master-eligible nodes. They join the cluster and receive the full [cluster state](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state.html), like every other node, and they use the cluster state to route requests directly to the appropriate place(s). + +::::{warning} +Adding too many coordinating only nodes to a cluster can increase the burden on the entire cluster because the elected master node must await acknowledgement of cluster state updates from every node! The benefit of coordinating only nodes should not be overstated — data nodes can happily serve the same purpose. +:::: + + +To create a dedicated coordinating node, set: + +```yaml +node.roles: [ ] +``` + + +### Remote-eligible node [remote-node] + +A remote-eligible node acts as a cross-cluster client and connects to [remote clusters](../../remote-clusters.md). Once connected, you can search remote clusters using [{{ccs}}](../../../solutions/search/cross-cluster-search.md). You can also sync data between clusters using [{{ccr}}](../../tools/cross-cluster-replication.md). + +```yaml +node.roles: [ remote_cluster_client ] +``` + + +### Machine learning node [ml-node-role] + +{{ml-cap}} nodes run jobs and handle {{ml}} API requests. For more information, see [Machine learning settings](../../deploy/self-managed/configure-elasticsearch.md). + +To create a dedicated {{ml}} node, set: + +```yaml +node.roles: [ ml, remote_cluster_client] +``` + +The `remote_cluster_client` role is optional but strongly recommended. Otherwise, {{ccs}} fails when used in {{ml}} jobs or {{dfeeds}}. If you use {{ccs}} in your {{anomaly-jobs}}, the `remote_cluster_client` role is also required on all master-eligible nodes. Otherwise, the {{dfeed}} cannot start. See [Remote-eligible node](#remote-node). + + +### {{transform-cap}} node [transform-node-role] + +{{transform-cap}} nodes run {{transforms}} and handle {{transform}} API requests. For more information, see [{{transforms-cap}} settings](../../deploy/self-managed/configure-elasticsearch.md). + +To create a dedicated {{transform}} node, set: + +```yaml +node.roles: [ transform, remote_cluster_client ] +``` + +The `remote_cluster_client` role is optional but strongly recommended. Otherwise, {{ccs}} fails when used in {{transforms}}. See [Remote-eligible node](#remote-node). + diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation.md b/deploy-manage/distributed-architecture/discovery-cluster-formation.md new file mode 100644 index 000000000..417923af1 --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation.md @@ -0,0 +1,41 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery.html +--- + +# Discovery and cluster formation [modules-discovery] + +The discovery and cluster formation processes are responsible for discovering nodes, electing a master, forming a cluster, and publishing the cluster state each time it changes. + +The following processes and settings are part of discovery and cluster formation: + +[Discovery](discovery-cluster-formation/discovery-hosts-providers.md) +: Discovery is the process where nodes find each other when the master is unknown, such as when a node has just started up or when the previous master has failed. + +[Quorum-based decision making](discovery-cluster-formation/modules-discovery-quorums.md) +: How {{es}} uses a quorum-based voting mechanism to make decisions even if some nodes are unavailable. + +[Voting configurations](discovery-cluster-formation/modules-discovery-voting.md) +: How {{es}} automatically updates voting configurations as nodes leave and join a cluster. + +[Bootstrapping a cluster](discovery-cluster-formation/modules-discovery-bootstrap-cluster.md) +: Bootstrapping a cluster is required when an {{es}} cluster starts up for the very first time. In [development mode](../deploy/self-managed/bootstrap-checks.md#dev-vs-prod-mode), with no discovery settings configured, this is automatically performed by the nodes themselves. As this auto-bootstrapping is [inherently unsafe](discovery-cluster-formation/modules-discovery-quorums.md), running a node in [production mode](../deploy/self-managed/bootstrap-checks.md#dev-vs-prod-mode) requires bootstrapping to be [explicitly configured](discovery-cluster-formation/modules-discovery-bootstrap-cluster.md). + +[Adding and removing master-eligible nodes](../maintenance/add-and-remove-elasticsearch-nodes.md) +: It is recommended to have a small and fixed number of master-eligible nodes in a cluster, and to scale the cluster up and down by adding and removing master-ineligible nodes only. However there are situations in which it may be desirable to add or remove some master-eligible nodes to or from a cluster. This section describes the process for adding or removing master-eligible nodes, including the extra steps that need to be performed when removing more than half of the master-eligible nodes at the same time. + +[Publishing the cluster state](discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing) +: Cluster state publishing is the process by which the elected master node updates the cluster state on all the other nodes in the cluster. + +[Cluster fault detection](discovery-cluster-formation/cluster-fault-detection.md) +: {{es}} performs health checks to detect and remove faulty nodes. + +[Settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html) +: There are settings that enable users to influence the discovery, cluster formation, master election and fault detection processes. + + + + + + + diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md b/deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md new file mode 100644 index 000000000..433695a4d --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-fault-detection.html +--- + +# Cluster fault detection [cluster-fault-detection] + +The elected master periodically checks each of the nodes in the cluster to ensure that they are still connected and healthy. Each node in the cluster also periodically checks the health of the elected master. These checks are known respectively as *follower checks* and *leader checks*. + +Elasticsearch allows these checks to occasionally fail or timeout without taking any action. It considers a node to be faulty only after a number of consecutive checks have failed. You can control fault detection behavior with [`cluster.fault_detection.*` settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html). + +If the elected master detects that a node has disconnected, however, this situation is treated as an immediate failure. The master bypasses the timeout and retry setting values and attempts to remove the node from the cluster. Similarly, if a node detects that the elected master has disconnected, this situation is treated as an immediate failure. The node bypasses the timeout and retry settings and restarts its discovery phase to try and find or elect a new master. + +$$$cluster-fault-detection-filesystem-health$$$ +Additionally, each node periodically verifies that its data path is healthy by writing a small file to disk and then deleting it again. If a node discovers its data path is unhealthy then it is removed from the cluster until the data path recovers. You can control this behavior with the [`monitor.fs.health` settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html). + +$$$cluster-fault-detection-cluster-state-publishing$$$ +The elected master node will also remove nodes from the cluster if nodes are unable to apply an updated cluster state within a reasonable time. The timeout defaults to 2 minutes starting from the beginning of the cluster state update. Refer to [Publishing the cluster state](cluster-state-overview.md#cluster-state-publishing) for a more detailed description. + +## Troubleshooting an unstable cluster [cluster-fault-detection-troubleshooting] + +See [*Troubleshooting an unstable cluster*](../../../troubleshoot/elasticsearch/troubleshooting-unstable-cluster.md). + + +#### Diagnosing `disconnected` nodes [_diagnosing_disconnected_nodes] + +See [Diagnosing `disconnected` nodes](../../../troubleshoot/elasticsearch/troubleshooting-unstable-cluster.md#troubleshooting-unstable-cluster-disconnected). + + +#### Diagnosing `lagging` nodes [_diagnosing_lagging_nodes] + +See [Diagnosing `lagging` nodes](../../../troubleshoot/elasticsearch/troubleshooting-unstable-cluster.md#troubleshooting-unstable-cluster-lagging). + + +#### Diagnosing `follower check retry count exceeded` nodes [_diagnosing_follower_check_retry_count_exceeded_nodes] + +See [Diagnosing `follower check retry count exceeded` nodes](../../../troubleshoot/elasticsearch/troubleshooting-unstable-cluster.md#troubleshooting-unstable-cluster-follower-check). + + +#### Diagnosing `ShardLockObtainFailedException` failures [_diagnosing_shardlockobtainfailedexception_failures] + +See [Diagnosing `ShardLockObtainFailedException` failures](../../../troubleshoot/elasticsearch/troubleshooting-unstable-cluster.md#troubleshooting-unstable-cluster-shardlockobtainfailedexception). + + +#### Diagnosing other network disconnections [_diagnosing_other_network_disconnections] + +See [Diagnosing other network disconnections](../../../troubleshoot/elasticsearch/troubleshooting-unstable-cluster.md#troubleshooting-unstable-cluster-network). + + diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md b/deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md new file mode 100644 index 000000000..190ac8060 --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation/cluster-state-overview.md @@ -0,0 +1,44 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state-overview.html +--- + +# Cluster state [cluster-state-overview] + +The *cluster state* is an internal data structure which keeps track of a variety of information needed by every node, including: + +* The identity and attributes of the other nodes in the cluster +* Cluster-wide settings +* Index metadata, including the mapping and settings for each index +* The location and status of every shard copy in the cluster + +The elected master node ensures that every node in the cluster has a copy of the same cluster state. The [cluster state API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state.html) lets you retrieve a representation of this internal state for debugging or diagnostic purposes. + +## Publishing the cluster state [cluster-state-publishing] + +The elected master node is the only node in a cluster that can make changes to the cluster state. The elected master node processes one batch of cluster state updates at a time, computing the required changes and publishing the updated cluster state to all the other nodes in the cluster. Each publication starts with the elected master broadcasting the updated cluster state to all nodes in the cluster. Each node responds with an acknowledgement but does not yet apply the newly-received state. Once the elected master has collected acknowledgements from enough master-eligible nodes, the new cluster state is said to be *committed* and the master broadcasts another message instructing nodes to apply the now-committed state. Each node receives this message, applies the updated state, and then sends a second acknowledgement back to the master. + +The elected master allows a limited amount of time for each cluster state update to be completely published to all nodes. It is defined by the `cluster.publish.timeout` setting, which defaults to `30s`, measured from the time the publication started. If this time is reached before the new cluster state is committed then the cluster state change is rejected and the elected master considers itself to have failed. It stands down and starts trying to elect a new master node. + +If the new cluster state is committed before `cluster.publish.timeout` has elapsed, the elected master node considers the change to have succeeded. It waits until the timeout has elapsed or until it has received acknowledgements that each node in the cluster has applied the updated state, and then starts processing and publishing the next cluster state update. If some acknowledgements have not been received (i.e. some nodes have not yet confirmed that they have applied the current update), these nodes are said to be *lagging* since their cluster states have fallen behind the elected master’s latest state. The elected master waits for the lagging nodes to catch up for a further time, `cluster.follower_lag.timeout`, which defaults to `90s`. If a node has still not successfully applied the cluster state update within this time then it is considered to have failed and the elected master removes it from the cluster. + +Cluster state updates are typically published as diffs to the previous cluster state, which reduces the time and network bandwidth needed to publish a cluster state update. For example, when updating the mappings for only a subset of the indices in the cluster state, only the updates for those indices need to be published to the nodes in the cluster, as long as those nodes have the previous cluster state. If a node is missing the previous cluster state, for example when rejoining a cluster, the elected master will publish the full cluster state to that node so that it can receive future updates as diffs. + +::::{note} +{{es}} is a peer to peer based system, in which nodes communicate with one another directly. The high-throughput APIs (index, delete, search) do not normally interact with the elected master node. The responsibility of the elected master node is to maintain the global cluster state which includes reassigning shards when nodes join or leave the cluster. Each time the cluster state is changed, the new state is published to all nodes in the cluster as described above. +:::: + + +The performance characteristics of cluster state updates are a function of the speed of the storage on each master-eligible node, as well as the reliability and latency of the network interconnections between all nodes in the cluster. You must therefore ensure that the storage and networking available to the nodes in your cluster are good enough to meet your performance goals. + + +## Dangling indices [dangling-index] + +When a node joins the cluster, if it finds any shards stored in its local data directory that do not already exist in the cluster state, it will consider those shards to belong to a "dangling" index. You can list, import or delete dangling indices using the [Dangling indices API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices.html#dangling-indices-api). + +::::{note} +The API cannot offer any guarantees as to whether the imported data truly represents the latest state of the data when the index was still part of the cluster. +:::: + + + diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md b/deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md new file mode 100644 index 000000000..d85653b6a --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md @@ -0,0 +1,90 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/discovery-hosts-providers.html +--- + +# Discovery [discovery-hosts-providers] + +Discovery is the process by which the cluster formation module finds other nodes with which to form a cluster. This process runs when you start an Elasticsearch node or when a node believes the master node failed and continues until the master node is found or a new master node is elected. + +This process starts with a list of *seed* addresses from one or more [seed hosts providers](#built-in-hosts-providers), together with the addresses of any master-eligible nodes that were in the last-known cluster. The process operates in two phases: First, each node probes the seed addresses by connecting to each address and attempting to identify the node to which it is connected and to verify that it is master-eligible. Secondly, if successful, it shares with the remote node a list of all of its known master-eligible peers and the remote node responds with *its* peers in turn. The node then probes all the new nodes that it just discovered, requests their peers, and so on. + +If the node is not master-eligible then it continues this discovery process until it has discovered an elected master node. If no elected master is discovered then the node will retry after `discovery.find_peers_interval` which defaults to `1s`. + +If the node is master-eligible then it continues this discovery process until it has either discovered an elected master node or else it has discovered enough masterless master-eligible nodes to complete an election. If neither of these occur quickly enough then the node will retry after `discovery.find_peers_interval` which defaults to `1s`. + +Once a master is elected, it will normally remain as the elected master until it is deliberately stopped. It may also stop acting as the master if [fault detection](cluster-fault-detection.md) determines the cluster to be faulty. When a node stops being the elected master, it begins the discovery process again. + +Refer to [Troubleshooting discovery](../../../troubleshoot/elasticsearch/discovery-troubleshooting.md) for troubleshooting issues with discovery. + +## Seed hosts providers [built-in-hosts-providers] + +By default the cluster formation module offers two seed hosts providers to configure the list of seed nodes: a *settings*-based and a *file*-based seed hosts provider. It can be extended to support cloud environments and other forms of seed hosts providers via [discovery plugins](https://www.elastic.co/guide/en/elasticsearch/plugins/current/discovery.html). Seed hosts providers are configured using the `discovery.seed_providers` setting, which defaults to the *settings*-based hosts provider. This setting accepts a list of different providers, allowing you to make use of multiple ways to find the seed hosts for your cluster. + +Each seed hosts provider yields the IP addresses or hostnames of the seed nodes. If it returns any hostnames then these are resolved to IP addresses using a DNS lookup. If a hostname resolves to multiple IP addresses then {{es}} tries to find a seed node at all of these addresses. If the hosts provider does not explicitly give the TCP port of the node by then, it will implicitly use the first port in the port range given by `transport.profiles.default.port`, or by `transport.port` if `transport.profiles.default.port` is not set. The number of concurrent lookups is controlled by `discovery.seed_resolver.max_concurrent_resolvers` which defaults to `10`, and the timeout for each lookup is controlled by `discovery.seed_resolver.timeout` which defaults to `5s`. Note that DNS lookups are subject to [JVM DNS caching](../../deploy/self-managed/networkaddress-cache-ttl.md). + + +#### Settings-based seed hosts provider [settings-based-hosts-provider] + +The settings-based seed hosts provider uses a node setting to configure a static list of the addresses of the seed nodes. These addresses can be given as hostnames or IP addresses; hosts specified as hostnames are resolved to IP addresses during each round of discovery. + +The list of hosts is set using the [`discovery.seed_hosts`](../../deploy/self-managed/important-settings-configuration.md#unicast.hosts) static setting. For example: + +```yaml +discovery.seed_hosts: + - 192.168.1.10:9300 + - 192.168.1.11 <1> + - seeds.mydomain.com <2> +``` + +1. The port will default to `transport.profiles.default.port` and fallback to `transport.port` if not specified. +2. If a hostname resolves to multiple IP addresses, {{es}} will attempt to connect to every resolved address. + + + +#### File-based seed hosts provider [file-based-hosts-provider] + +The file-based seed hosts provider configures a list of hosts via an external file. {{es}} reloads this file when it changes, so that the list of seed nodes can change dynamically without needing to restart each node. For example, this gives a convenient mechanism for an {{es}} instance that is run in a Docker container to be dynamically supplied with a list of IP addresses to connect to when those IP addresses may not be known at node startup. + +To enable file-based discovery, configure the `file` hosts provider as follows in the `elasticsearch.yml` file: + +```yaml +discovery.seed_providers: file +``` + +Then create a file at `$ES_PATH_CONF/unicast_hosts.txt` in the format described below. Any time a change is made to the `unicast_hosts.txt` file the new changes will be picked up by {{es}} and the new hosts list will be used. + +Note that the file-based discovery plugin augments the unicast hosts list in `elasticsearch.yml`: if there are valid seed addresses in `discovery.seed_hosts` then {{es}} uses those addresses in addition to those supplied in `unicast_hosts.txt`. + +The `unicast_hosts.txt` file contains one node entry per line. Each node entry consists of the host (host name or IP address) and an optional transport port number. If the port number is specified, it must come immediately after the host (on the same line) separated by a `:`. If the port number is not specified, {{es}} will implicitly use the first port in the port range given by `transport.profiles.default.port`, or by `transport.port` if `transport.profiles.default.port` is not set. + +For example, this is an example of `unicast_hosts.txt` for a cluster with four nodes that participate in discovery, some of which are not running on the default port: + +```txt +10.10.10.5 +10.10.10.6:9305 +10.10.10.5:10005 +# an IPv6 address +[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:9301 +``` + +Host names are allowed instead of IP addresses and are resolved by DNS as described above. IPv6 addresses must be given in brackets with the port, if needed, coming after the brackets. + +You can also add comments to this file. All comments must appear on their lines starting with `#` (i.e. comments cannot start in the middle of a line). + + +#### EC2 hosts provider [ec2-hosts-provider] + +The [EC2 discovery plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/discovery-ec2.html) adds a hosts provider that uses the [AWS API](https://github.com/aws/aws-sdk-java) to find a list of seed nodes. + + +#### Azure Classic hosts provider [azure-classic-hosts-provider] + +The [Azure Classic discovery plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/discovery-azure-classic.html) adds a hosts provider that uses the Azure Classic API find a list of seed nodes. + + +#### Google Compute Engine hosts provider [gce-hosts-provider] + +The [GCE discovery plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/discovery-gce.html) adds a hosts provider that uses the GCE API find a list of seed nodes. + + diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md b/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md new file mode 100644 index 000000000..ae49a37f7 --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md @@ -0,0 +1,103 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-bootstrap-cluster.html +--- + +# Bootstrapping a cluster [modules-discovery-bootstrap-cluster] + +Starting an Elasticsearch cluster for the very first time requires the initial set of [master-eligible nodes](../clusters-nodes-shards/node-roles.md#master-node-role) to be explicitly defined on one or more of the master-eligible nodes in the cluster. This is known as *cluster bootstrapping*. This is only required the first time a cluster starts up. Freshly-started nodes that are joining a running cluster obtain this information from the cluster’s elected master. + +The initial set of master-eligible nodes is defined in the [`cluster.initial_master_nodes` setting](../../deploy/self-managed/important-settings-configuration.md#initial_master_nodes). This should be set to a list containing one of the following items for each master-eligible node: + +* The [node name](../../deploy/self-managed/important-settings-configuration.md#node-name) of the node. +* The node’s hostname if `node.name` is not set, because `node.name` defaults to the node’s hostname. You must use either the fully-qualified hostname or the bare hostname [depending on your system configuration](#modules-discovery-bootstrap-cluster-fqdns). +* The IP address of the node’s [transport publish address](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#modules-network-binding-publishing), if it is not possible to use the `node.name` of the node. This is normally the IP address to which [`network.host`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#common-network-settings) resolves but [this can be overridden](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#advanced-network-settings). +* The IP address and port of the node’s publish address, in the form `IP:PORT`, if it is not possible to use the `node.name` of the node and there are multiple nodes sharing a single IP address. + +Do not set `cluster.initial_master_nodes` on master-ineligible nodes. + +::::{important} +After the cluster has formed, remove the `cluster.initial_master_nodes` setting from each node’s configuration and never set it again for this cluster. Do not configure this setting on nodes joining an existing cluster. Do not configure this setting on nodes which are restarting. Do not configure this setting when performing a full-cluster restart. + +If you leave `cluster.initial_master_nodes` in place once the cluster has formed then there is a risk that a future misconfiguration may result in bootstrapping a new cluster alongside your existing cluster. It may not be possible to recover from this situation without losing data. + +:::: + + +The simplest way to create a new cluster is for you to select one of your master-eligible nodes that will bootstrap itself into a single-node cluster, which all the other nodes will then join. This simple approach is not resilient to failures until the other master-eligible nodes have joined the cluster. For example, if you have a master-eligible node with [node name](../../deploy/self-managed/important-settings-configuration.md#node-name) `master-a` then configure it as follows (omitting `cluster.initial_master_nodes` from the configuration of all other nodes): + +```yaml +cluster.initial_master_nodes: master-a +``` + +For fault-tolerant cluster bootstrapping, use all the master-eligible nodes. For instance, if your cluster has 3 master-eligible nodes with [node names](../../deploy/self-managed/important-settings-configuration.md#node-name) `master-a`, `master-b` and `master-c` then configure them all as follows: + +```yaml +cluster.initial_master_nodes: + - master-a + - master-b + - master-c +``` + +::::{important} +You must set `cluster.initial_master_nodes` to the same list of nodes on each node on which it is set in order to be sure that only a single cluster forms during bootstrapping. If `cluster.initial_master_nodes` varies across the nodes on which it is set then you may bootstrap multiple clusters. It is usually not possible to recover from this situation without losing data. +:::: + + +::::{admonition} Node name formats must match +:name: modules-discovery-bootstrap-cluster-fqdns + +The node names used in the `cluster.initial_master_nodes` list must exactly match the `node.name` properties of the nodes. By default the node name is set to the machine’s hostname which may or may not be fully-qualified depending on your system configuration. If each node name is a fully-qualified domain name such as `master-a.example.com` then you must use fully-qualified domain names in the `cluster.initial_master_nodes` list too; conversely if your node names are bare hostnames (without the `.example.com` suffix) then you must use bare hostnames in the `cluster.initial_master_nodes` list. If you use a mix of fully-qualified and bare hostnames, or there is some other mismatch between `node.name` and `cluster.initial_master_nodes`, then the cluster will not form successfully and you will see log messages like the following. + +```text +[master-a.example.com] master not discovered yet, this node has +not previously joined a bootstrapped (v7+) cluster, and this +node must discover master-eligible nodes [master-a, master-b] to +bootstrap a cluster: have discovered [{master-b.example.com}{... +``` + +This message shows the node names `master-a.example.com` and `master-b.example.com` as well as the `cluster.initial_master_nodes` entries `master-a` and `master-b`, and it is clear from this message that they do not match exactly. + +:::: + + +## Choosing a cluster name [bootstrap-cluster-name] + +The [`cluster.name`](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-name) setting enables you to create multiple clusters which are separated from each other. Nodes verify that they agree on their cluster name when they first connect to each other, and Elasticsearch will only form a cluster from nodes that all have the same cluster name. The default value for the cluster name is `elasticsearch`, but it is recommended to change this to reflect the logical name of the cluster. + + +## Auto-bootstrapping in development mode [bootstrap-auto-bootstrap] + +By default each node will automatically bootstrap itself into a single-node cluster the first time it starts. If any of the following settings are configured then auto-bootstrapping will not take place: + +* `discovery.seed_providers` +* `discovery.seed_hosts` +* `cluster.initial_master_nodes` + +To add a new node into an existing cluster, configure `discovery.seed_hosts` or other relevant discovery settings so that the new node can discover the existing master-eligible nodes in the cluster. To bootstrap a new multi-node cluster, configure `cluster.initial_master_nodes` as described in the [section on cluster bootstrapping]() as well as `discovery.seed_hosts` or other relevant discovery settings. + +::::{admonition} Forming a single cluster +:name: modules-discovery-bootstrap-cluster-joining + +Once an {{es}} node has joined an existing cluster, or bootstrapped a new cluster, it will not join a different cluster. {{es}} will not merge separate clusters together after they have formed, even if you subsequently try and configure all the nodes into a single cluster. This is because there is no way to merge these separate clusters together without a risk of data loss. You can tell that you have formed separate clusters by checking the cluster UUID reported by `GET /` on each node. + +If you intended to add a node into an existing cluster but instead bootstrapped a separate single-node cluster then you must start again: + +1. Shut down the node. +2. Completely wipe the node by deleting the contents of its [data folder](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#data-path). +3. Configure `discovery.seed_hosts` or `discovery.seed_providers` and other relevant discovery settings. Ensure `cluster.initial_master_nodes` is not set on any node. +4. Restart the node and verify that it joins the existing cluster rather than forming its own one-node cluster. + +If you intended to form a new multi-node cluster but instead bootstrapped a collection of single-node clusters then you must start again: + +1. Shut down all the nodes. +2. Completely wipe each node by deleting the contents of their [data folders](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#data-path). +3. Configure `cluster.initial_master_nodes` as described above. +4. Configure `discovery.seed_hosts` or `discovery.seed_providers` and other relevant discovery settings. +5. Restart all the nodes and verify that they have formed a single cluster. +6. Remove `cluster.initial_master_nodes` from every node’s configuration. + +:::: + + + diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md b/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md new file mode 100644 index 000000000..268d45786 --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md @@ -0,0 +1,32 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-quorums.html +--- + +# Quorum-based decision making [modules-discovery-quorums] + +Electing a master node and changing the cluster state are the two fundamental tasks that master-eligible nodes must work together to perform. It is important that these activities work robustly even if some nodes have failed. Elasticsearch achieves this robustness by considering each action to have succeeded on receipt of responses from a *quorum*, which is a subset of the master-eligible nodes in the cluster. The advantage of requiring only a subset of the nodes to respond is that it means some of the nodes can fail without preventing the cluster from making progress. The quorums are carefully chosen so the cluster does not have a "split brain" scenario where it’s partitioned into two pieces such that each piece may make decisions that are inconsistent with those of the other piece. + +Elasticsearch allows you to add and remove master-eligible nodes to a running cluster. In many cases you can do this simply by starting or stopping the nodes as required. See [*Add and remove nodes in your cluster*](../../maintenance/add-and-remove-elasticsearch-nodes.md) for more information. + +As nodes are added or removed Elasticsearch maintains an optimal level of fault tolerance by updating the cluster’s [voting configuration](modules-discovery-voting.md), which is the set of master-eligible nodes whose responses are counted when making decisions such as electing a new master or committing a new cluster state. A decision is made only after more than half of the nodes in the voting configuration have responded. Usually the voting configuration is the same as the set of all the master-eligible nodes that are currently in the cluster. However, there are some situations in which they may be different. + +::::{important} +To be sure that the cluster remains available you **must not stop half or more of the nodes in the voting configuration at the same time**. As long as more than half of the voting nodes are available the cluster can still work normally. This means that if there are three or four master-eligible nodes, the cluster can tolerate one of them being unavailable. If there are two or fewer master-eligible nodes, they must all remain available. + +If you stop half or more of the nodes in the voting configuration at the same time then the cluster will be unavailable until you bring enough nodes back online to form a quorum again. While the cluster is unavailable, any remaining nodes will report in their logs that they cannot discover or elect a master node. See [*Troubleshooting discovery*](../../../troubleshoot/elasticsearch/discovery-troubleshooting.md) for more information. + +:::: + + +After a master-eligible node has joined or left the cluster the elected master may issue a cluster-state update that adjusts the voting configuration to match, and this can take a short time to complete. It is important to wait for this adjustment to complete before removing more nodes from the cluster. See [Removing master-eligible nodes](../../maintenance/add-and-remove-elasticsearch-nodes.md#modules-discovery-removing-nodes) for more information. + + +## Master elections [_master_elections] + +Elasticsearch uses an election process to agree on an elected master node, both at startup and if the existing elected master fails. Any master-eligible node can start an election, and normally the first election that takes place will succeed. Elections only usually fail when two nodes both happen to start their elections at about the same time, so elections are scheduled randomly on each node to reduce the probability of this happening. Nodes will retry elections until a master is elected, backing off on failure, so that eventually an election will succeed (with arbitrarily high probability). The scheduling of master elections are controlled by the [master election settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html#master-election-settings). + + +## Cluster maintenance, rolling restarts and migrations [_cluster_maintenance_rolling_restarts_and_migrations] + +Many cluster maintenance tasks involve temporarily shutting down one or more nodes and then starting them back up again. By default {{es}} can remain available if one of its master-eligible nodes is taken offline, such as during a rolling upgrade. Furthermore, if multiple nodes are stopped and then started again then it will automatically recover, such as during a full cluster restart. There is no need to take any further action with the APIs described here in these cases, because the set of master nodes is not changing permanently. diff --git a/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-voting.md b/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-voting.md new file mode 100644 index 000000000..fbc109695 --- /dev/null +++ b/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-voting.md @@ -0,0 +1,67 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-voting.html +--- + +# Voting configurations [modules-discovery-voting] + +Each {{es}} cluster has a *voting configuration*, which is the set of [master-eligible nodes](../clusters-nodes-shards/node-roles.md#master-node-role) whose responses are counted when making decisions such as electing a new master or committing a new cluster state. Decisions are made only after a majority (more than half) of the nodes in the voting configuration respond. + +Usually the voting configuration is the same as the set of all the master-eligible nodes that are currently in the cluster. However, there are some situations in which they may be different. + +::::{important} +To be sure that the cluster remains available you **must not stop half or more of the nodes in the voting configuration at the same time**. As long as more than half of the voting nodes are available the cluster can still work normally. This means that if there are three or four master-eligible nodes, the cluster can tolerate one of them being unavailable. If there are two or fewer master-eligible nodes, they must all remain available. + +If you stop half or more of the nodes in the voting configuration at the same time then the cluster will be unavailable until you bring enough nodes back online to form a quorum again. While the cluster is unavailable, any remaining nodes will report in their logs that they cannot discover or elect a master node. See [*Troubleshooting discovery*](../../../troubleshoot/elasticsearch/discovery-troubleshooting.md) for more information. + +:::: + + +After a node joins or leaves the cluster, {{es}} reacts by automatically making corresponding changes to the voting configuration in order to ensure that the cluster is as resilient as possible. It is important to wait for this adjustment to complete before you remove more nodes from the cluster. For more information, see [*Add and remove nodes in your cluster*](../../maintenance/add-and-remove-elasticsearch-nodes.md). + +The current voting configuration is stored in the cluster state so you can inspect its current contents as follows: + +```console +GET /_cluster/state?filter_path=metadata.cluster_coordination.last_committed_config +``` + +::::{note} +The current voting configuration is not necessarily the same as the set of all available master-eligible nodes in the cluster. Altering the voting configuration involves taking a vote, so it takes some time to adjust the configuration as nodes join or leave the cluster. Also, there are situations where the most resilient configuration includes unavailable nodes or does not include some available nodes. In these situations, the voting configuration differs from the set of available master-eligible nodes in the cluster. +:::: + + +Larger voting configurations are usually more resilient, so Elasticsearch normally prefers to add master-eligible nodes to the voting configuration after they join the cluster. Similarly, if a node in the voting configuration leaves the cluster and there is another master-eligible node in the cluster that is not in the voting configuration then it is preferable to swap these two nodes over. The size of the voting configuration is thus unchanged but its resilience increases. + +It is not so straightforward to automatically remove nodes from the voting configuration after they have left the cluster. Different strategies have different benefits and drawbacks, so the right choice depends on how the cluster will be used. You can control whether the voting configuration automatically shrinks by using the [`cluster.auto_shrink_voting_configuration` setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html). + +::::{note} +If `cluster.auto_shrink_voting_configuration` is set to `true` (which is the default and recommended value) and there are at least three master-eligible nodes in the cluster, Elasticsearch remains capable of processing cluster state updates as long as all but one of its master-eligible nodes are healthy. +:::: + + +There are situations in which Elasticsearch might tolerate the loss of multiple nodes, but this is not guaranteed under all sequences of failures. If the `cluster.auto_shrink_voting_configuration` setting is `false`, you must remove departed nodes from the voting configuration manually. Use the [voting exclusions API](https://www.elastic.co/guide/en/elasticsearch/reference/current/voting-config-exclusions.html) to achieve the desired level of resilience. + +No matter how it is configured, Elasticsearch will not suffer from a "split-brain" inconsistency. The `cluster.auto_shrink_voting_configuration` setting affects only its availability in the event of the failure of some of its nodes and the administrative tasks that must be performed as nodes join and leave the cluster. + + +## Even numbers of master-eligible nodes [_even_numbers_of_master_eligible_nodes] + +There should normally be an odd number of master-eligible nodes in a cluster. If there is an even number, Elasticsearch leaves one of them out of the voting configuration to ensure that it has an odd size. This omission does not decrease the failure-tolerance of the cluster. In fact, improves it slightly: if the cluster suffers from a network partition that divides it into two equally-sized halves then one of the halves will contain a majority of the voting configuration and will be able to keep operating. If all of the votes from master-eligible nodes were counted, neither side would contain a strict majority of the nodes and so the cluster would not be able to make any progress. + +For instance if there are four master-eligible nodes in the cluster and the voting configuration contained all of them, any quorum-based decision would require votes from at least three of them. This situation means that the cluster can tolerate the loss of only a single master-eligible node. If this cluster were split into two equal halves, neither half would contain three master-eligible nodes and the cluster would not be able to make any progress. If the voting configuration contains only three of the four master-eligible nodes, however, the cluster is still only fully tolerant to the loss of one node, but quorum-based decisions require votes from two of the three voting nodes. In the event of an even split, one half will contain two of the three voting nodes so that half will remain available. + + +## Setting the initial voting configuration [_setting_the_initial_voting_configuration] + +When a brand-new cluster starts up for the first time, it must elect its first master node. To do this election, it needs to know the set of master-eligible nodes whose votes should count. This initial voting configuration is known as the *bootstrap configuration* and is set in the [cluster bootstrapping process](modules-discovery-bootstrap-cluster.md). + +It is important that the bootstrap configuration identifies exactly which nodes should vote in the first election. It is not sufficient to configure each node with an expectation of how many nodes there should be in the cluster. It is also important to note that the bootstrap configuration must come from outside the cluster: there is no safe way for the cluster to determine the bootstrap configuration correctly on its own. + +If the bootstrap configuration is not set correctly, when you start a brand-new cluster there is a risk that you will accidentally form two separate clusters instead of one. This situation can lead to data loss: you might start using both clusters before you notice that anything has gone wrong and it is impossible to merge them together later. + +::::{note} +To illustrate the problem with configuring each node to expect a certain cluster size, imagine starting up a three-node cluster in which each node knows that it is going to be part of a three-node cluster. A majority of three nodes is two, so normally the first two nodes to discover each other form a cluster and the third node joins them a short time later. However, imagine that four nodes were erroneously started instead of three. In this case, there are enough nodes to form two separate clusters. Of course if each node is started manually then it’s unlikely that too many nodes are started. If you’re using an automated orchestrator, however, it’s certainly possible to get into this situation-- particularly if the orchestrator is not resilient to failures such as network partitions. +:::: + + +The initial quorum is only required the very first time a whole cluster starts up. New nodes joining an established cluster can safely obtain all the information they need from the elected master. Nodes that have previously been part of a cluster will have stored to disk all the information that is required when they restart. diff --git a/deploy-manage/distributed-architecture/kibana-tasks-management.md b/deploy-manage/distributed-architecture/kibana-tasks-management.md new file mode 100644 index 000000000..9090653c0 --- /dev/null +++ b/deploy-manage/distributed-architecture/kibana-tasks-management.md @@ -0,0 +1,167 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/task-manager-production-considerations.html +--- + +# Kibana tasks management [task-manager-production-considerations] + +{{kib}} Task Manager is leveraged by features such as Alerting, Actions, and Reporting to run mission critical work as persistent background tasks. These background tasks distribute work across multiple {{kib}} instances. This has three major benefits: + +* **Persistence**: All task state and scheduling is stored in {{es}}, so if you restart {{kib}}, tasks will pick up where they left off. +* **Scaling**: Multiple {{kib}} instances can read from and update the same task queue in {{es}}, allowing the work load to be distributed across instances. If a {{kib}} instance no longer has capacity to run tasks, you can increase capacity by adding additional {{kib}} instances. +* **Load Balancing**: Task Manager is equipped with a reactive self-healing mechanism, which allows it to reduce the amount of work it executes in reaction to an increased load related error rate in {{es}}. Additionally, when Task Manager experiences an increase in recurring tasks, it attempts to space out the work to better balance the load. + +::::{important} +Task definitions for alerts and actions are stored in the index called `.kibana_task_manager`. + +You must have at least one replica of this index for production deployments. + +If you lose this index, all scheduled alerts and actions are lost. + +:::: + + + +## Running background tasks [task-manager-background-tasks] + +{{kib}} background tasks are managed as follows: + +* An {{es}} task index is polled for overdue tasks at 3-second intervals. You can change this interval using the [`xpack.task_manager.poll_interval`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting. +* Tasks are claimed by updating them in the {{es}} index, using optimistic concurrency control to prevent conflicts. Each {{kib}} instance can run a maximum of 10 concurrent tasks, so a maximum of 10 tasks are claimed each interval. +* Tasks are run on the {{kib}} server. +* Task Manager ensures that tasks: + + * Are only executed once + * Are retried when they fail (if configured to do so) + * Are rescheduled to run again at a future point in time (if configured to do so) + + +::::{important} +It is possible for tasks to run late or at an inconsistent schedule. + +This is usually a symptom of the specific usage or scaling strategy of the cluster in question. + +To address these issues, tweak the {{kib}} Task Manager settings or the cluster scaling strategy to better suit the unique use case. + +For details on the settings that can influence the performance and throughput of Task Manager, see [Task Manager Settings](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html). + +For detailed troubleshooting guidance, see [Troubleshooting](../../troubleshoot/kibana/task-manager.md). + +:::: + + + +## Deployment considerations [_deployment_considerations] + +{{es}} and {{kib}} instances use the system clock to determine the current time. To ensure schedules are triggered when expected, synchronize the clocks of all nodes in the cluster using a time service such as [Network Time Protocol](http://www.ntp.org/). + + +## Scaling guidance [task-manager-scaling-guidance] + +How you deploy {{kib}} largely depends on your use case. Predicting the throughout a deployment might require to support Task Management is difficult because features can schedule an unpredictable number of tasks at a variety of scheduled cadences. + +However, there is a relatively straight forward method you can follow to produce a rough estimate based on your expected usage. + + +### Default scale [task-manager-default-scaling] + +By default, {{kib}} polls for tasks at a rate of 10 tasks every 3 seconds. This means that you can expect a single {{kib}} instance to support up to 200 *tasks per minute* (`200/tpm`). + +In practice, a {{kib}} instance will only achieve the upper bound of `200/tpm` if the duration of task execution is below the polling rate of 3 seconds. For the most part, the duration of tasks is below that threshold, but it can vary greatly as {{es}} and {{kib}} usage grow and task complexity increases (such as alerts executing heavy queries across large datasets). + +By [estimating a rough throughput requirement](#task-manager-rough-throughput-estimation), you can estimate the number of {{kib}} instances required to reliably execute tasks in a timely manner. An appropriate number of {{kib}} instances can be estimated to match the required scale. + +For details on monitoring the health of {{kib}} Task Manager, follow the guidance in [Health monitoring](../monitor/kibana-task-manager-health-monitoring.md). + + +### Scaling horizontally [task-manager-scaling-horizontally] + +At times, the sustainable approach might be to expand the throughput of your cluster by provisioning additional {{kib}} instances. By default, each additional {{kib}} instance will add an additional 10 tasks that your cluster can run concurrently, but you can also scale each {{kib}} instance vertically, if your diagnosis indicates that they can handle the additional workload. + + +### Scaling vertically [task-manager-scaling-vertically] + +Other times it, might be preferable to increase the throughput of individual {{kib}} instances. + +Tweak the capacity with the [`xpack.task_manager.capacity`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting, which enables each {{kib}} instance to pull a higher number of tasks per interval. This setting can impact the performance of each instance as the workload will be higher. + +Tweak the poll interval with the [`xpack.task_manager.poll_interval`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting, which enables each {{kib}} instance to pull scheduled tasks at a higher rate. This setting can impact the performance of the {{es}} cluster as the workload will be higher. + + +### Choosing a scaling strategy [task-manager-choosing-scaling-strategy] + +Each scaling strategy comes with its own considerations, and the appropriate strategy largely depends on your use case. + +Scaling {{kib}} instances vertically causes higher resource usage in each {{kib}} instance, as it will perform more concurrent work. Scaling {{kib}} instances horizontally requires a higher degree of coordination, which can impact overall performance. + +A recommended strategy is to follow these steps: + +1. Produce a [rough throughput estimate](#task-manager-rough-throughput-estimation) as a guide to provisioning as many {{kib}} instances as needed. Include any growth in tasks that you predict experiencing in the near future, and a buffer to better address ad-hoc tasks. +2. After provisioning a deployment, assess whether the provisioned {{kib}} instances achieve the required throughput by evaluating the [Health monitoring](../monitor/kibana-task-manager-health-monitoring.md) as described in [Insufficient throughput to handle the scheduled workload](../../troubleshoot/kibana/task-manager.md#task-manager-theory-insufficient-throughput). +3. If the throughput is insufficient, and {{kib}} instances exhibit low resource usage, incrementally scale vertically while [monitoring](../monitor/monitoring-data/kibana-page.md) the impact of these changes. +4. If the throughput is insufficient, and {{kib}} instances are exhibiting high resource usage, incrementally scale horizontally by provisioning new {{kib}} instances and reassess. + +Task Manager, like the rest of the Elastic Stack, is designed to scale horizontally. Take advantage of this ability to ensure mission critical services, such as Alerting, Actions, and Reporting, always have the capacity they need. + +Scaling horizontally requires a higher degree of coordination between {{kib}} instances. One way Task Manager coordinates with other instances is by delaying its polling schedule to avoid conflicts with other instances. By using [health monitoring](../monitor/kibana-task-manager-health-monitoring.md) to evaluate the [date of the `last_polling_delay`](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-runtime) across a deployment, you can estimate the frequency at which Task Manager resets its delay mechanism. A higher frequency suggests {{kib}} instances conflict at a high rate, which you can address by scaling vertically rather than horizontally, reducing the required coordination. + + +### Rough throughput estimation [task-manager-rough-throughput-estimation] + +Predicting the required throughput a deployment might need to support Task Management is difficult, as features can schedule an unpredictable number of tasks at a variety of scheduled cadences. However, a rough lower bound can be estimated, which is then used as a guide. + +Throughput is best thought of as a measurements in tasks per minute. + +A default {{kib}} instance can support up to `200/tpm`. + + +#### Automatic estimation [_automatic_estimation] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +As demonstrated in [Evaluate your capacity estimation](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-capacity-estimation), the Task Manager [health monitoring](../monitor/kibana-task-manager-health-monitoring.md) performs these estimations automatically. + +These estimates are based on historical data and should not be used as predictions, but can be used as a rough guide when scaling the system. + +We recommend provisioning enough {{kib}} instances to ensure a buffer between the observed maximum throughput (as estimated under `observed.max_throughput_per_minute`) and the average required throughput (as estimated under `observed.avg_required_throughput_per_minute`). Otherwise there might be insufficient capacity to handle spikes of ad-hoc tasks. How much of a buffer is needed largely depends on your use case, but keep in mind that estimated throughput takes into account recent spikes and, as long as they are representative of your system’s behaviour, shouldn’t require much of a buffer. + +We recommend provisioning at least as many {{kib}} instances as proposed by `proposed.provisioned_kibana`, but keep in mind that this number is based on the estimated required throughput, which is based on average historical performance, and cannot accurately predict future requirements. + +::::{warning} +Automatic capacity estimation is performed by each {{kib}} instance independently. This estimation is performed by observing the task throughput in that instance, the number of {{kib}} instances executing tasks at that moment in time, and the recurring workload in {{es}}. + +If a {{kib}} instance is idle at the moment of capacity estimation, the number of active {{kib}} instances might be miscounted and the available throughput miscalculated. + +When evaluating the proposed {{kib}} instance number under `proposed.provisioned_kibana`, we highly recommend verifying that the `observed.observed_kibana_instances` matches the number of provisioned {{kib}} instances. + +:::: + + + +#### Manual estimation [_manual_estimation] + +By [evaluating the workload](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-workload), you can make a rough estimate as to the required throughput as a *tasks per minute* measurement. + +For example, suppose your current workload reveals a required throughput of `440/tpm`. You can address this scale by provisioning 3 {{kib}} instances, with an upper throughput of `600/tpm`. This scale would provide approximately 25% additional capacity to handle ad-hoc non-recurring tasks and potential growth in recurring tasks. + +Given a deployment of 100 recurring tasks, estimating the required throughput depends on the scheduled cadence. Suppose you expect to run 50 tasks at a cadence of `10s`, the other 50 tasks at `20m`. In addition, you expect a couple dozen non-recurring tasks every minute. + +A non-recurring task requires a single execution, which means that a single {{kib}} instance could execute all 100 tasks in less than a minute, using only half of its capacity. As these tasks are only executed once, the {{kib}} instance will sit idle once all tasks are executed. For that reason, don’t include non-recurring tasks in your *tasks per minute* calculation. Instead, include a buffer in the final *lower bound* to incur the cost of ad-hoc non-recurring tasks. + +A recurring task requires as many executions as its cadence can fit in a minute. A recurring task with a `10s` schedule will require `6/tpm`, as it will execute 6 times per minute. A recurring task with a `20m` schedule only executes 3 times per hour and only requires a throughput of `0.05/tpm`, a number so small it that is difficult to take it into account. + +For this reason, we recommend grouping tasks by *tasks per minute* and *tasks per hour*, as demonstrated in [Evaluate your workload](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-workload), averaging the *per hour* measurement across all minutes. + +It is highly recommended that you maintain at least 20% additional capacity, beyond your expected workload, as spikes in ad-hoc tasks is possible at times of high activity (such as a spike in actions in response to an active alert). + +Given the predicted workload, you can estimate a lower bound throughput of `340/tpm` (`6/tpm` * 50 + `3/tph` * 50 + 20% buffer). As a default, a {{kib}} instance provides a throughput of `200/tpm`. A good starting point for your deployment is to provision 2 {{kib}} instances. You could then monitor their performance and reassess as the required throughput becomes clearer. + +Although this is a *rough* estimate, the *tasks per minute* provides the lower bound needed to execute tasks on time. + +Once you estimate *tasks per minute* , add a buffer for non-recurring tasks. How much of a buffer is required largely depends on your use case. Ensure enough of a buffer is provisioned by [evaluating your workload](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-workload) as it grows and tracking the ratio of recurring to non-recurring tasks by [evaluating your runtime](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-runtime). + + + diff --git a/deploy-manage/distributed-architecture/reading-and-writing-documents.md b/deploy-manage/distributed-architecture/reading-and-writing-documents.md new file mode 100644 index 000000000..9641e118d --- /dev/null +++ b/deploy-manage/distributed-architecture/reading-and-writing-documents.md @@ -0,0 +1,111 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-replication.html +--- + +# Reading and writing documents [docs-replication] + + +## Introduction [_introduction] + +Each index in Elasticsearch is [divided into shards](../../deploy-manage/index.md) and each shard can have multiple copies. These copies are known as a *replication group* and must be kept in sync when documents are added or removed. If we fail to do so, reading from one copy will result in very different results than reading from another. The process of keeping the shard copies in sync and serving reads from them is what we call the *data replication model*. + +Elasticsearch’s data replication model is based on the *primary-backup model* and is described very well in the [PacificA paper](https://www.microsoft.com/en-us/research/publication/pacifica-replication-in-log-based-distributed-storage-systems/) of Microsoft Research. That model is based on having a single copy from the replication group that acts as the primary shard. The other copies are called *replica shards*. The primary serves as the main entry point for all indexing operations. It is in charge of validating them and making sure they are correct. Once an index operation has been accepted by the primary, the primary is also responsible for replicating the operation to the other copies. + +This purpose of this section is to give a high level overview of the Elasticsearch replication model and discuss the implications it has for various interactions between write and read operations. + + +## Basic write model [basic-write-model] + +Every indexing operation in Elasticsearch is first resolved to a replication group using [routing](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#index-routing), typically based on the document ID. Once the replication group has been determined, the operation is forwarded internally to the current *primary shard* of the group. This stage of indexing is referred to as the *coordinating stage*. + +:::{image} ../../images/elasticsearch-reference-data_processing_flow.png +:alt: An example of a basic write model. +::: + +The next stage of indexing is the *primary stage*, performed on the primary shard. The primary shard is responsible for validating the operation and forwarding it to the other replicas. Since replicas can be offline, the primary is not required to replicate to all replicas. Instead, Elasticsearch maintains a list of shard copies that should receive the operation. This list is called the *in-sync copies* and is maintained by the master node. As the name implies, these are the set of "good" shard copies that are guaranteed to have processed all of the index and delete operations that have been acknowledged to the user. The primary is responsible for maintaining this invariant and thus has to replicate all operations to each copy in this set. + +The primary shard follows this basic flow: + +1. Validate incoming operation and reject it if structurally invalid (Example: have an object field where a number is expected) +2. Execute the operation locally i.e. indexing or deleting the relevant document. This will also validate the content of fields and reject if needed (Example: a keyword value is too long for indexing in Lucene). +3. Forward the operation to each replica in the current in-sync copies set. If there are multiple replicas, this is done in parallel. +4. Once all in-sync replicas have successfully performed the operation and responded to the primary, the primary acknowledges the successful completion of the request to the client. + +Each in-sync replica copy performs the indexing operation locally so that it has a copy. This stage of indexing is the *replica stage*. + +These indexing stages (coordinating, primary, and replica) are sequential. To enable internal retries, the lifetime of each stage encompasses the lifetime of each subsequent stage. For example, the coordinating stage is not complete until each primary stage, which may be spread out across different primary shards, has completed. Each primary stage will not complete until the in-sync replicas have finished indexing the docs locally and responded to the replica requests. + + +### Failure handling [_failure_handling] + +Many things can go wrong during indexing — disks can get corrupted, nodes can be disconnected from each other, or some configuration mistake could cause an operation to fail on a replica despite it being successful on the primary. These are infrequent but the primary has to respond to them. + +In the case that the primary itself fails, the node hosting the primary will send a message to the master about it. The indexing operation will wait (up to 1 minute, by [default](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#dynamic-index-settings)) for the master to promote one of the replicas to be a new primary. The operation will then be forwarded to the new primary for processing. Note that the master also monitors the health of the nodes and may decide to proactively demote a primary. This typically happens when the node holding the primary is isolated from the cluster by a networking issue. See [here](#demoted-primary) for more details. + +Once the operation has been successfully performed on the primary, the primary has to deal with potential failures when executing it on the replica shards. This may be caused by an actual failure on the replica or due to a network issue preventing the operation from reaching the replica (or preventing the replica from responding). All of these share the same end result: a replica which is part of the in-sync replica set misses an operation that is about to be acknowledged. In order to avoid violating the invariant, the primary sends a message to the master requesting that the problematic shard be removed from the in-sync replica set. Only once removal of the shard has been acknowledged by the master does the primary acknowledge the operation. Note that the master will also instruct another node to start building a new shard copy in order to restore the system to a healthy state. + +$$$demoted-primary$$$ +While forwarding an operation to the replicas, the primary will use the replicas to validate that it is still the active primary. If the primary has been isolated due to a network partition (or a long GC) it may continue to process incoming indexing operations before realising that it has been demoted. Operations that come from a stale primary will be rejected by the replicas. When the primary receives a response from the replica rejecting its request because it is no longer the primary then it will reach out to the master and will learn that it has been replaced. The operation is then routed to the new primary. + +::::{admonition} What happens if there are no replicas? +This is a valid scenario that can happen due to index configuration or simply because all the replicas have failed. In that case the primary is processing operations without any external validation, which may seem problematic. On the other hand, the primary cannot fail other shards on its own but request the master to do so on its behalf. This means that the master knows that the primary is the only single good copy. We are therefore guaranteed that the master will not promote any other (out-of-date) shard copy to be a new primary and that any operation indexed into the primary will not be lost. Of course, since at that point we are running with only single copy of the data, physical hardware issues can cause data loss. See [Active shards](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#index-wait-for-active-shards) for some mitigation options. + +:::: + + + +## Basic read model [_basic_read_model] + +Reads in Elasticsearch can be very lightweight lookups by ID or a heavy search request with complex aggregations that take non-trivial CPU power. One of the beauties of the primary-backup model is that it keeps all shard copies identical (with the exception of in-flight operations). As such, a single in-sync copy is sufficient to serve read requests. + +When a read request is received by a node, that node is responsible for forwarding it to the nodes that hold the relevant shards, collating the responses, and responding to the client. We call that node the *coordinating node* for that request. The basic flow is as follows: + +1. Resolve the read requests to the relevant shards. Note that since most searches will be sent to one or more indices, they typically need to read from multiple shards, each representing a different subset of the data. +2. Select an active copy of each relevant shard, from the shard replication group. This can be either the primary or a replica. By default, {{es}} uses [adaptive replica selection](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-shard-routing.html#search-adaptive-replica) to select the shard copies. +3. Send shard level read requests to the selected copies. +4. Combine the results and respond. Note that in the case of get by ID look up, only one shard is relevant and this step can be skipped. + + +### Shard failures [shard-failures] + +When a shard fails to respond to a read request, the coordinating node sends the request to another shard copy in the same replication group. Repeated failures can result in no available shard copies. + +To ensure fast responses, the following APIs will respond with partial results if one or more shards fail: + +* [Search](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) +* [Multi Search](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html) +* [Multi Get](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html) + +Responses containing partial results still provide a `200 OK` HTTP status code. Shard failures are indicated by the `timed_out` and `_shards` fields of the response header. + + +## A few simple implications [_a_few_simple_implications] + +Each of these basic flows determines how Elasticsearch behaves as a system for both reads and writes. Furthermore, since read and write requests can be executed concurrently, these two basic flows interact with each other. This has a few inherent implications: + +Efficient reads +: Under normal operation each read operation is performed once for each relevant replication group. Only under failure conditions do multiple copies of the same shard execute the same search. + +Read unacknowledged +: Since the primary first indexes locally and then replicates the request, it is possible for a concurrent read to already see the change before it has been acknowledged. + +Two copies by default +: This model can be fault tolerant while maintaining only two copies of the data. This is in contrast to quorum-based system where the minimum number of copies for fault tolerance is 3. + + +## Failures [_failures] + +Under failures, the following is possible: + +A single shard can slow down indexing +: Because the primary waits for all replicas in the in-sync copies set during each operation, a single slow shard can slow down the entire replication group. This is the price we pay for the read efficiency mentioned above. Of course a single slow shard will also slow down unlucky searches that have been routed to it. + +Dirty reads +: An isolated primary can expose writes that will not be acknowledged. This is caused by the fact that an isolated primary will only realize that it is isolated once it sends requests to its replicas or when reaching out to the master. At that point the operation is already indexed into the primary and can be read by a concurrent read. Elasticsearch mitigates this risk by pinging the master every second (by default) and rejecting indexing operations if no master is known. + + +## The Tip of the Iceberg [_the_tip_of_the_iceberg] + +This document provides a high level overview of how Elasticsearch deals with data. Of course, there is much more going on under the hood. Things like primary terms, cluster state publishing, and master election all play a role in keeping this system behaving correctly. This document also doesn’t cover known and important bugs (both closed and open). We recognize that [GitHub is hard to keep up with](https://github.com/elastic/elasticsearch/issues?q=label%3Aresiliency). To help people stay on top of those, we maintain a dedicated [resiliency page](https://www.elastic.co/guide/en/elasticsearch/resiliency/current/index.html) on our website. We strongly advise reading it. + diff --git a/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery.md b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery.md new file mode 100644 index 000000000..856a248bf --- /dev/null +++ b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery.md @@ -0,0 +1,98 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-allocation-relocation-recovery.html +--- + +# Shard allocation, relocation, and recovery [shard-allocation-relocation-recovery] + +Each [index](../../manage-data/data-store/index-basics.md) in Elasticsearch is divided into one or more [shards](../../deploy-manage/index.md). Each document in an index belongs to a single shard. + +A cluster can contain multiple copies of a shard. Each shard has one distinguished shard copy called the *primary*, and zero or more non-primary copies called *replicas*. The primary shard copy serves as the main entry point for all indexing operations. The operations on the primary shard copy are then forwarded to its replicas. + +Replicas maintain redundant copies of your data across the [nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html) in your cluster, protecting against hardware failure and increasing capacity to serve read requests like searching or retrieving a document. If the primary shard copy fails, then a replica is promoted to primary and takes over the primary’s responsibilities. + +Over the course of normal operation, Elasticsearch allocates shard copies to nodes, relocates shard copies across nodes to balance the cluster or satisfy new allocation constraints, and recovers shards to initialize new copies. In this topic, you’ll learn how these operations work and how you can control them. + +::::{tip} +To learn about optimizing the number and size of shards in your cluster, refer to [Size your shards](../production-guidance/optimize-performance/size-shards.md). To learn about how read and write operations are replicated across shards and shard copies, refer to [Reading and writing documents](reading-and-writing-documents.md). +:::: + + + +## Shard allocation [shard-allocation] + +Shard allocation is the process of assigning shard copies to nodes. This can happen during initial recovery, replica allocation, rebalancing, when nodes are added to or removed from the cluster, or when cluster or index settings that impact allocation are updated. + +By default, the primary and replica shard copies for an index can be allocated to any node in the cluster, and may be relocated to rebalance the cluster. + + +### Adjust shard allocation settings [_adjust_shard_allocation_settings] + +You can control how shard copies are allocated using the following settings: + +* [Cluster-level shard allocation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html): Use these settings to control how shard copies are allocated and balanced across the entire cluster. For example, you might want to [allocate nodes availability zones](shard-allocation-relocation-recovery/shard-allocation-awareness.md), or prevent certain nodes from being used so you can perform maintenance. +* [Index-level shard allocation settings](shard-allocation-relocation-recovery/index-level-shard-allocation.md): Use these settings to control how the shard copies for a specific index are allocated. For example, you might want to allocate an index to a node in a specific data tier, or to an node with specific attributes. + + +### Monitor shard allocation [_monitor_shard_allocation] + +If a shard copy is unassigned, it means that the shard copy is not allocated to any node in the cluster. This can happen if there are not enough nodes in the cluster to allocate the shard copy, or if the shard copy can’t be allocated to any node that satisfies the shard allocation filtering rules. When a shard copy is unassigned, your cluster is considered unhealthy and returns a yellow or red cluster health status. + +You can use the following APIs to monitor shard allocation: + +* [Cluster allocation explain](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-allocation-explain.html) +* [cat allocation](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-allocation.html) +* [cluster health](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html) + +[Learn more about troubleshooting unassigned shard copies and recovering your cluster health](../../troubleshoot/elasticsearch/red-yellow-cluster-status.md). + + +## Shard recovery [shard-recovery] + +Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or creating a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. + +Recovery automatically occurs during the following processes: + +* When creating an index for the first time. +* When a node rejoins the cluster and starts up any missing primary shard copies using the data that it holds in its data path. +* Creation of new replica shard copies from the primary. +* Relocation of a shard copy to a different node in the same cluster. +* A [snapshot restore](../tools/snapshot-and-restore/restore-snapshot.md) operation. +* A [clone](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-clone-index.html), [shrink](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html), or [split](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) operation. + +You can determine the cause of a shard recovery using the [recovery](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-recovery.html) or [cat recovery](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-recovery.html) APIs. + + +### Adjust shard recovery settings [_adjust_shard_recovery_settings] + +To control how shards are recovered, for example the resources that can be used by recovery operations, and which indices should be prioritized for recovery, you can adjust the following settings: + +* [Index recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html) +* [Cluster-level shard allocation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html) +* [Index-level shard allocation settings](shard-allocation-relocation-recovery/index-level-shard-allocation.md), including [delayed allocation](shard-allocation-relocation-recovery/delaying-allocation-when-node-leaves.md) and [index recovery prioritization](shard-allocation-relocation-recovery/index-level-shard-allocation.md) + +Shard recovery operations also respect general shard allocation settings. + + +### Monitor shard recovery [_monitor_shard_recovery] + +You can use the following APIs to monitor shard allocation: + +* View a list of in-progress and completed recoveries using the [cat recovery API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-recovery.html) +* View detailed information about a specific recovery using the [index recovery API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-recovery.html) + + +## Shard relocation [shard-relocation] + +Shard relocation is the process of moving shard copies from one node to another. This can happen when a node joins or leaves the cluster, or when the cluster is rebalancing. + +When a shard copy is relocated, it is created as a new shard copy on the target node. When the shard copy is fully allocated and recovered, the old shard copy is deleted. If the shard copy being relocated is a primary, then the new shard copy is marked as primary before the old shard copy is deleted. + + +### Adjust shard relocation settings [_adjust_shard_relocation_settings] + +You can control how and when shard copies are relocated. For example, you can adjust the rebalancing settings that control when shard copies are relocated to balance the cluster, or the high watermark for disk-based shard allocation that can trigger relocation. These settings are part of the [cluster-level shard allocation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html). + +Shard relocation operations also respect shard allocation and recovery settings. + + diff --git a/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/delaying-allocation-when-node-leaves.md b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/delaying-allocation-when-node-leaves.md new file mode 100644 index 000000000..660868743 --- /dev/null +++ b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/delaying-allocation-when-node-leaves.md @@ -0,0 +1,89 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/delayed-allocation.html +--- + +# Delaying allocation when a node leaves [delayed-allocation] + +When a node leaves the cluster for whatever reason, intentional or otherwise, the master reacts by: + +* Promoting a replica shard to primary to replace any primaries that were on the node. +* Allocating replica shards to replace the missing replicas (assuming there are enough nodes). +* Rebalancing shards evenly across the remaining nodes. + +These actions are intended to protect the cluster against data loss by ensuring that every shard is fully replicated as soon as possible. + +Even though we throttle concurrent recoveries both at the [node level](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html) and at the [cluster level](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-shard-allocation-settings), this shard-shuffle can still put a lot of extra load on the cluster which may not be necessary if the missing node is likely to return soon. Imagine this scenario: + +* Node 5 loses network connectivity. +* The master promotes a replica shard to primary for each primary that was on Node 5. +* The master allocates new replicas to other nodes in the cluster. +* Each new replica makes an entire copy of the primary shard across the network. +* More shards are moved to different nodes to rebalance the cluster. +* Node 5 returns after a few minutes. +* The master rebalances the cluster by allocating shards to Node 5. + +If the master had just waited for a few minutes, then the missing shards could have been re-allocated to Node 5 with the minimum of network traffic. This process would be even quicker for idle shards (shards not receiving indexing requests) which have been automatically [flushed](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-flush.html). + +The allocation of replica shards which become unassigned because a node has left can be delayed with the `index.unassigned.node_left.delayed_timeout` dynamic setting, which defaults to `1m`. + +This setting can be updated on a live index (or on all indices): + +```console +PUT _all/_settings +{ + "settings": { + "index.unassigned.node_left.delayed_timeout": "5m" + } +} +``` + +With delayed allocation enabled, the above scenario changes to look like this: + +* Node 5 loses network connectivity. +* The master promotes a replica shard to primary for each primary that was on Node 5. +* The master logs a message that allocation of unassigned shards has been delayed, and for how long. +* The cluster remains yellow because there are unassigned replica shards. +* Node 5 returns after a few minutes, before the `timeout` expires. +* The missing replicas are re-allocated to Node 5 (and sync-flushed shards recover almost immediately). + +::::{note} +This setting will not affect the promotion of replicas to primaries, nor will it affect the assignment of replicas that have not been assigned previously. In particular, delayed allocation does not come into effect after a full cluster restart. Also, in case of a master failover situation, elapsed delay time is forgotten (i.e. reset to the full initial delay). +:::: + + +## Cancellation of shard relocation [_cancellation_of_shard_relocation] + +If delayed allocation times out, the master assigns the missing shards to another node which will start recovery. If the missing node rejoins the cluster, and its shards still have the same sync-id as the primary, shard relocation will be cancelled and the synced shard will be used for recovery instead. + +For this reason, the default `timeout` is set to just one minute: even if shard relocation begins, cancelling recovery in favour of the synced shard is cheap. + + +## Monitoring delayed unassigned shards [_monitoring_delayed_unassigned_shards] + +The number of shards whose allocation has been delayed by this timeout setting can be viewed with the [cluster health API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html): + +```console +GET _cluster/health <1> +``` + +1. This request will return a `delayed_unassigned_shards` value. + + + +## Removing a node permanently [_removing_a_node_permanently] + +If a node is not going to return and you would like Elasticsearch to allocate the missing shards immediately, just update the timeout to zero: + +```console +PUT _all/_settings +{ + "settings": { + "index.unassigned.node_left.delayed_timeout": "0" + } +} +``` + +You can reset the timeout as soon as the missing shards have started to recover. + + diff --git a/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/index-level-shard-allocation.md b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/index-level-shard-allocation.md new file mode 100644 index 000000000..bc0ccdfc2 --- /dev/null +++ b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/index-level-shard-allocation.md @@ -0,0 +1,21 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-allocation.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-allocation-filtering.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery-prioritization.html +--- + +# Index-level shard allocation + +% What needs to be done: Refine + +% Scope notes: also reference https://www.elastic.co/guide/en/elasticsearch/reference/current/allocation-total-shards.html and https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tier-shard-filtering.html + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/index-modules-allocation.md +% Notes: conceptual content +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/shard-allocation-filtering.md +% Notes: conceptual content +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/recovery-prioritization.md +% Notes: conceptual content \ No newline at end of file diff --git a/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md new file mode 100644 index 000000000..99b4c7708 --- /dev/null +++ b/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md @@ -0,0 +1,98 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-allocation-awareness.html +--- + +# Shard allocation awareness [shard-allocation-awareness] + +You can use custom node attributes as *awareness attributes* to enable {{es}} to take your physical hardware configuration into account when allocating shards. If {{es}} knows which nodes are on the same physical server, in the same rack, or in the same zone, it can distribute the primary shard and its replica shards to minimize the risk of losing all shard copies in the event of a failure. + +When shard allocation awareness is enabled with the `cluster.routing.allocation.awareness.attributes` setting, shards are only allocated to nodes that have values set for the specified awareness attributes. If you use multiple awareness attributes, {{es}} considers each attribute separately when allocating shards. + +::::{note} +The number of attribute values determines how many shard copies are allocated in each location. If the number of nodes in each location is unbalanced and there are a lot of replicas, replica shards might be left unassigned. +:::: + + +::::{tip} +Learn more about [designing resilient clusters](../../production-guidance/availability-and-resilience/resilience-in-larger-clusters.md). +:::: + + +## Enabling shard allocation awareness [enabling-awareness] + +To enable shard allocation awareness: + +1. Specify the location of each node with a [custom node attribute](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#custom-node-attributes). For example, if you want Elasticsearch to distribute shards across different racks, you might use an awareness attribute called `rack_id`. + + You can set custom attributes in two ways: + + * By editing the `elasticsearch.yml` config file: + + ```yaml + node.attr.rack_id: rack_one + ``` + + * Using the `-E` command line argument when you start a node: + + ```sh + ./bin/elasticsearch -Enode.attr.rack_id=rack_one + ``` + +2. Tell {{es}} to take one or more awareness attributes into account when allocating shards by setting `cluster.routing.allocation.awareness.attributes` in **every** master-eligible node’s `elasticsearch.yml` config file. + + ```yaml + cluster.routing.allocation.awareness.attributes: rack_id <1> + ``` + + 1. Specify multiple attributes as a comma-separated list. + + + You can also use the [cluster-update-settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) API to set or update a cluster’s awareness attributes: + + ```console + PUT /_cluster/settings + { + "persistent" : { + "cluster.routing.allocation.awareness.attributes" : "rack_id" + } + } + ``` + + +With this example configuration, if you start two nodes with `node.attr.rack_id` set to `rack_one` and create an index with 5 primary shards and 1 replica of each primary, all primaries and replicas are allocated across the two node. + +:::{image} ../../../images/elasticsearch-reference-shard-allocation-awareness-one-rack.png +:alt: All primaries and replicas are allocated across two nodes in the same rack +:title: All primaries and replicas allocated across two nodes in the same rack +::: + +If you add two nodes with `node.attr.rack_id` set to `rack_two`, {{es}} moves shards to the new nodes, ensuring (if possible) that no two copies of the same shard are in the same rack. + +:::{image} ../../../images/elasticsearch-reference-shard-allocation-awareness-two-racks.png +:alt: Primaries and replicas are allocated across four nodes in two racks with no two copies of the same shard in the same rack +:title: Primaries and replicas allocated across four nodes in two racks, with no two copies of the same shard in the same rack +::: + +If `rack_two` fails and takes down both its nodes, by default {{es}} allocates the lost shard copies to nodes in `rack_one`. To prevent multiple copies of a particular shard from being allocated in the same location, you can enable forced awareness. + + +## Forced awareness [forced-awareness] + +By default, if one location fails, {{es}} spreads its shards across the remaining locations. This might be undesirable if the cluster does not have sufficient resources to host all its shards when one location is missing. + +To prevent the remaining locations from being overloaded in the event of a whole-location failure, specify the attribute values that should exist with the `cluster.routing.allocation.awareness.force.*` settings. This will mean that {{es}} will prefer to leave some replicas unassigned in the event of a whole-location failure instead of overloading the nodes in the remaining locations. + +For example, if you have an awareness attribute called `zone` and configure nodes in `zone1` and `zone2`, you can use forced awareness to make {{es}} leave half of your shard copies unassigned if only one zone is available: + +```yaml +cluster.routing.allocation.awareness.attributes: zone +cluster.routing.allocation.awareness.force.zone.values: zone1,zone2 <1> +``` + +1. Specify all possible `zone` attribute values. + + +With this example configuration, if you have two nodes with `node.attr.zone` set to `zone1` and an index with `number_of_replicas` set to `1`, {{es}} allocates all the primary shards but none of the replicas. It will assign the replica shards once nodes with a different value for `node.attr.zone` join the cluster. In contrast, if you do not configure forced awareness, {{es}} will allocate all primaries and replicas to the two nodes even though they are in the same zone. + + diff --git a/deploy-manage/index.md b/deploy-manage/index.md index c29be98a7..554c70b5c 100644 --- a/deploy-manage/index.md +++ b/deploy-manage/index.md @@ -1,3 +1,49 @@ --- -title: Deploy and Manage ---- \ No newline at end of file +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/introduction.html + - https://www.elastic.co/guide/en/kibana/current/setup.html + - https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current/get-elastic.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html + - https://www.elastic.co/guide/en/cloud/current/ec-faq-technical.html + - https://www.elastic.co/guide/en/elastic-stack/current/overview.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-deployments.html + - https://www.elastic.co/guide/en/kibana/current/management.html +--- + +# Deploy and manage + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/332 + +% Scope notes: Explain that a basic deployment always has ES, usually has Kibana, might have xyz. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/introduction.md +% - [ ] ./raw-migrated-files/kibana/kibana/setup.md +% - [ ] ./raw-migrated-files/tech-content/starting-with-the-elasticsearch-platform-and-its-solutions/get-elastic.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/scalability.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-faq-technical.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/overview.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-administering-deployments.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/kibana/kibana/management.md +% Notes: redirect only + +$$$adding_index_privileges$$$ + +$$$faq-hw-architecture$$$ + +$$$faq-master-nodes$$$ + +$$$faq-ssl$$$ + +$$$faq-autoscale$$$ + +$$$faq-ip-sniffing$$$ + +$$$faq-encryption-at-rest$$$ + +$$$faq-static-ip-elastic-cloud$$$ \ No newline at end of file diff --git a/deploy-manage/license.md b/deploy-manage/license.md new file mode 100644 index 000000000..bf0bb782d --- /dev/null +++ b/deploy-manage/license.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-licensing.html +--- + +# Manage your license [ec-licensing] + +For more information on what is available with different subscription levels, check [Elasticsearch Service Subscriptions](https://www.elastic.co/elasticsearch/service/pricing). You are entitled to use all of the features in Elasticsearch Service that match your subscription level. Please use them to your heart’s content. + +Your subscription determines [which features are available](https://www.elastic.co/subscriptions/cloud). For example, machine learning requires a Platinum or Private subscription and is not available if you upgrade to a Gold subscription. Similarly, SAML Single Sign-On requires an Enterprise subscription. + diff --git a/deploy-manage/license/manage-your-license-in-ece.md b/deploy-manage/license/manage-your-license-in-ece.md new file mode 100644 index 000000000..4cdbdf43d --- /dev/null +++ b/deploy-manage/license/manage-your-license-in-ece.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-add-license.html +--- + +# Manage your license in ECE [ece-add-license] + +The use of Elastic Cloud Enterprise requires a valid license, which you can obtain from Elastic and add to your installation following the steps described in this document. When you first install ECE we automatically activate ECE with a trial license that is valid for 30 days. + +Full ECE licenses that you obtain from Elastic enable all ECE hosted deployments with the same products, features, and support that are available at our Enterprise subscription level on Elastic Cloud for the respective stack version, as described on the [Subscriptions page](https://www.elastic.co/subscriptions/cloud). + +::::{note} +The licenses used to activate the deployments might have a different expiration date than the license used to activate ECE. ECE manages the licenses of the hosted deployments and will automatically update the deployment license when needed. +:::: + + +::::{note} +If you have a license from 2018 or earlier, you might receive a warning that your cluster license is about to expire. Don’t panic, it isn’t really. Elastic Cloud Enterprise manages the cluster licenses so that you don’t have to. In rare cases, such as when a cluster is overloaded, it can take longer for Elastic Cloud Enterprise to reapply the cluster license. +:::: + + + +## Licenses Expiration [ece_licenses_expiration] + +Elastic Cloud Enterprise Licenses contains two types of licenses - the actual license for Elastic Cloud Enterprise that is validated to enable Elastic Cloud Enterprise features and the *cluster licenses*, which Elastic Cloud Enterprise installs into the individual clusters. + +Elastic Cloud Enterprise installs those cluster licenses with an approximately 3 month window, and updates the cluster licenses automatically as they get within a month of expiration. This is the same system that we use for our Elasticsearch Service on Cloud. + +When the Elastic Cloud Enterprise license expires, and consequently the cluster license that’s currently installed for all managed clusters since it has the same expiration date, the following takes place: + +* **Users cannot create new clusters or modify existing clusters**: They can only delete them. These clusters are still fully accessible for the client though. +* **X-Pack features are degraded**: For the details about what functionality will be reduced when cluster license expires, read more about the [Elastic Stack license expiration](https://www.elastic.co/guide/en/elastic-stack-overview/current/license-expiration.html). + + +## Download a license [ece_download_a_license] + +To download a license from Elastic: + +1. Locate the email sent to you from Elastic that includes the link to the license. +2. Open the link, accept the licensing agreement, and select **Send**. +3. Download the ECE license. + + +## Add a license [ece_add_a_license] + +To add a license to your ECE installation: + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Select **Update license** and choose the license file that you downloaded. License files are in the JSON format. +4. Select **Add license**. + + If the operation is successful, the license is added. + + + +## Check your license expiry [ece_check_your_license_expiry] + +To check your current license expiry date: + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Check the **Expires** row under **License**: + + +## Request a trial extension [ece_request_a_trial_extension] + +To request a trial license extension from Elastic: + +1. Fill in the form at [https://www.elastic.co/contact](https://www.elastic.co/contact). Make sure to choose Elastic Cloud Enterprise as the area of interest and state that you request a trial license extension. + + Someone from Elastic will be in touch to respond to your trial extension request. + + + +## Delete a license [ece_delete_a_license] + +To delete an existing license for your ECE installation: + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. In the **License** section, select **Delete license** and confirm the action. + diff --git a/deploy-manage/license/manage-your-license-in-eck.md b/deploy-manage/license/manage-your-license-in-eck.md new file mode 100644 index 000000000..5029487c3 --- /dev/null +++ b/deploy-manage/license/manage-your-license-in-eck.md @@ -0,0 +1,171 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-licensing.html +--- + +# Manage your license in ECK [k8s-licensing] + +When you install the default distribution of ECK, you receive a Basic license. Any Elastic stack application you manage through ECK will also be Basic licensed. Go to [https://www.elastic.co/subscriptions](https://www.elastic.co/subscriptions) to check which features are included in the Basic license for free. + +::::{important} +ECK is only offered in two licensing tiers: Basic and Enterprise. Similar to the Elastic Stack, customers can download and use ECK with a Basic license for free. Basic license users can obtain support from GitHub or through our [community](https://discuss.elastic.co). A paid Enterprise subscription is required to engage the Elastic support team. For more details, check the [Elastic subscriptions](https://www.elastic.co/subscriptions). +:::: + + +In this section, you are going to learn how to: + +* [Start a trial](#k8s-start-trial) +* [Add a license](#k8s-add-license) +* [Update your license](#k8s-update-license) +* [Get usage data](#k8s-get-usage-data) + + +## Start a trial [k8s-start-trial] + +If you want to try the features included in the Enterprise subscription, you can start a 30-day trial. To start a trial, create a Kubernetes secret as shown in this example. Note that it must be in the same namespace as the operator: + +```yaml +cat < +EOF +``` + +1. By setting this annotation to `accepted` you are expressing that you have accepted the Elastic EULA which can be found at [https://www.elastic.co/eula](https://www.elastic.co/eula). + + +::::{note} +You can initiate a trial only if a trial has not been previously activated. +:::: + + +At the end of the trial period, the Platinum and Enterprise features operate in a [degraded mode](https://www.elastic.co/guide/en/elastic-stack-overview/current/license-expiration.html). You can revert to a Basic license, extend the trial, or purchase an Enterprise subscription. + + +## Add a license [k8s-add-license] + +If you have a valid Enterprise subscription or a trial license extension, you will receive a link to download a license as a JSON file. + +::::{note} +When downloading the license choose the "Orchestration license" option. +:::: + + +The downloaded JSON file contains the Enterprise orchestration license which enables ECK Enterprise features. Embedded in the orchestration license are also Enterprise stack licenses for recent Elasticsearch versions and Platinum licenses for older Elasticsearch versions that do not support Enterprise licenses. + +To add the license to your ECK installation, create a Kubernetes secret of the following form: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + labels: + license.k8s.elastic.co/scope: operator <1> + name: eck-license +type: Opaque +data: + license: "JSON license in base64 format" <2> +``` + +1. This label is required for ECK to identify your license secret. +2. The license file can have any name. + + +You can easily create this secret using `kubectl` built-in support for secrets. Note that it must be in the same namespace as the operator: + +```shell script +kubectl create secret generic eck-license --from-file=my-license-file.json -n elastic-system +kubectl label secret eck-license "license.k8s.elastic.co/scope"=operator -n elastic-system +``` + +After you install a license into ECK, the Enterprise features of the operator are available, like Elasticsearch autoscaling and support for Elastic Maps Server. All the Elastic Stack applications you manage with ECK will have Platinum and Enterprise features enabled. The [`_license`](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-license.html) API reports that individual Elasticsearch clusters are running under an Enterprise license, and the [elastic-licensing](#k8s-get-usage-data) ConfigMap contains the current license level of the ECK operator. The applications created before you installed the license are upgraded to Platinum or Enterprise features without interruption of service after a short delay. + +::::{note} +The Elasticsearch `_license` API for versions before 8.0.0 reports a Platinum license level for backwards compatibility even if an Enterprise license is installed. +:::: + + + +## Update your license [k8s-update-license] + +Before your current Enterprise license expires, you will receive a new Enterprise license from Elastic (provided that your subscription is valid). + +::::{note} +You can check the expiry date of your license in the [elastic-licensing](#k8s-get-usage-data) ConfigMap. Enterprise licenses are container licenses that include multiple licenses for individual Elasticsearch clusters with shorter expiry. Therefore, you get a different expiry in Kibana or through the Elasticsearch [`_license`](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-license.html) API. ECK automatically updates the Elasticsearch cluster licenses until the expiry date of the ECK Enterprise license is reached. +:::: + + +To avoid any unintended downgrade of individual Elasticsearch clusters to a Basic license while installing the new license, we recommend installing the new Enterprise license as a new Kubernetes secret next to your existing Enterprise license. Just replace `eck-license` with a different name in the [Kubernetes secret example](#k8s-add-license). ECK will use the correct license automatically. + +Once you have created the new license secret you can safely delete the old license secret. + + +## Get usage data [k8s-get-usage-data] + +The operator periodically writes the total amount of Elastic resources under management to a configmap named `elastic-licensing`, which is in the same namespace as the operator. Here is an example of retrieving the data: + +```shell +> kubectl -n elastic-system get configmap elastic-licensing -o json | jq .data +{ + "apm_memory": "0.50GiB", + "apm_memory_bytes": "536870912", + "eck_license_expiry_date": "2025-01-01T00:59:59+01:00", + "eck_license_level": "enterprise", + "elasticsearch_memory": "18.00GiB", + "elasticsearch_memory_bytes": "19327352832", + "enterprise_resource_units": "1", + "enterprise_search_memory": "4.00GiB", + "enterprise_search_memory_bytes": "4294967296", + "kibana_memory": "1.00GiB", + "kibana_memory_bytes": "1073741824", + "logstash_memory": "2.00GiB", + "logstash_memory_bytes": "2147483648", + "max_enterprise_resource_units": "250", + "timestamp": "2024-07-26T12:40:42+02:00", + "total_managed_memory": "25.50GiB", + "total_managed_memory_bytes": "27380416512" +} +``` + +If the operator metrics endpoint is enabled with the `--metrics-port` flag (check [*Configure ECK*](../deploy/cloud-on-k8s/configure-eck.md)), license usage data will be included in the reported metrics. + +```shell +> curl "$ECK_METRICS_ENDPOINT" | grep elastic_licensing +# HELP elastic_licensing_enterprise_resource_units_max Maximum number of enterprise resource units available +# TYPE elastic_licensing_enterprise_resource_units_max gauge +elastic_licensing_enterprise_resource_units_max{license_level="enterprise"} 250 +# HELP elastic_licensing_enterprise_resource_units_total Total enterprise resource units used +# TYPE elastic_licensing_enterprise_resource_units_total gauge +elastic_licensing_enterprise_resource_units_total{license_level="enterprise"} 1 +# HELP elastic_licensing_memory_gibibytes_apm Memory used by APM server in GiB +# TYPE elastic_licensing_memory_gibibytes_apm gauge +elastic_licensing_memory_gibibytes_apm{license_level="enterprise"} 0.5 +# HELP elastic_licensing_memory_gibibytes_elasticsearch Memory used by Elasticsearch in GiB +# TYPE elastic_licensing_memory_gibibytes_elasticsearch gauge +elastic_licensing_memory_gibibytes_elasticsearch{license_level="enterprise"} 18 +# HELP elastic_licensing_memory_gibibytes_enterprise_search Memory used by Enterprise Search in GiB +# TYPE elastic_licensing_memory_gibibytes_enterprise_search gauge +elastic_licensing_memory_gibibytes_enterprise_search{license_level="enterprise"} 4 +# HELP elastic_licensing_memory_gibibytes_kibana Memory used by Kibana in GiB +# TYPE elastic_licensing_memory_gibibytes_kibana gauge +elastic_licensing_memory_gibibytes_kibana{license_level="enterprise"} 1 +# HELP elastic_licensing_memory_gibibytes_logstash Memory used by Logstash in GiB +# TYPE elastic_licensing_memory_gibibytes_logstash gauge +elastic_licensing_memory_gibibytes_logstash{license_level="enterprise"} 2 +# HELP elastic_licensing_memory_gibibytes_total Total memory used in GiB +# TYPE elastic_licensing_memory_gibibytes_total gauge +elastic_licensing_memory_gibibytes_total{license_level="enterprise"} 25.5 +``` + +::::{note} +Logstash resources managed by ECK will be counted towards ERU usage for informational purposes. Billable consumption depends on license terms on a per customer basis (See [Self Managed Subscription Agreement](https://www.elastic.co/agreements/global/self-managed)) +:::: + + diff --git a/deploy-manage/license/manage-your-license-in-self-managed-cluster.md b/deploy-manage/license/manage-your-license-in-self-managed-cluster.md new file mode 100644 index 000000000..55a7db461 --- /dev/null +++ b/deploy-manage/license/manage-your-license-in-self-managed-cluster.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/managing-licenses.html +--- + +# Manage your license in self-managed cluster [managing-licenses] + +By default, new installations have a Basic license that never expires. For the full list of features available at the Free and Open Basic subscription level, refer to {{subscriptions}}. + +To explore all of the available solutions and features, start a 30-day free trial. You can activate a trial subscription once per major product version. If you need more than 30 days to complete your evaluation, request an extended trial at {{extendtrial}}. + +To view the status of your license, start a trial, or install a new license, go to the **License Management** page using the navigation menu or the [global search field](../../get-started/the-stack.md#kibana-navigation-search). + + +## Required permissions [_required_permissions_3] + +The `manage` cluster privilege is required to access **License Management**. + +To add the privilege, go to the **Roles** management page using the navigation menu or the [global search field](../../get-started/the-stack.md#kibana-navigation-search). + + +## License expiration [license-expiration] + +Licenses are valid for a specific time period. 30 days before the license expiration date, {{es}} starts logging expiration warnings. If monitoring is enabled, expiration warnings are displayed prominently in {{kib}}. + +If your license expires, your subscription level reverts to Basic and you will no longer be able to use [Platinum or Enterprise features](https://www.elastic.co/subscriptions). + + +## Update your license [update-license] + +Licenses are provided as a *JSON* file and have an effective date and an expiration date. You cannot install a new license before its effective date. License updates take effect immediately and do not require restarting {{es}}. + +You can update your license from **Stack Management > License Management** or through the [update license API](https://www.elastic.co/guide/en/elasticsearch/reference/current/update-license.html). + diff --git a/deploy-manage/maintenance.md b/deploy-manage/maintenance.md new file mode 100644 index 000000000..a6cca8f7b --- /dev/null +++ b/deploy-manage/maintenance.md @@ -0,0 +1,25 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-kibana.html +--- + +# Maintenance [ece-manage-kibana] + +Kibana is an open source analytics and visualization platform designed to work with Elasticsearch, that makes it easy to perform advanced data analysis and to visualize your data in a variety of charts, tables, and maps. Its simple, browser-based interface enables you to quickly create and share dynamic dashboards that display changes to Elasticsearch queries in real time. + +Most deployment templates include a Kibana instance, but if it wasn’t part of the initial deployment you can go to the **Kibana** page and **Enable** Kibana. + +The new Kibana instance takes a few moments to provision. After provisioning Kibana is complete, you can use the endpoint URL to access Kibana. + +::::{tip} +You can log into Kibana as the `elastic` superuser. The password was provided when you created your deployment or can be [reset](users-roles/cluster-or-deployment-auth/built-in-users.md). On AWS and not able to access Kibana? [Check if you need to update your endpoint URL first](../troubleshoot/deployments/cloud-enterprise/common-issues.md#ece-aws-private-ip). +:::: + + +From the deployment **Kibana** page you can also: + +* Terminate your Kibana instance, which stops it. The information is stored in your Elasticsearch cluster, so stopping and restarting should not risk your Kibana information. +* Restart it after stopping. +* Upgrade your Kibana instance version if it is out of sync with your Elasticsearch cluster. +* Delete to fully remove the instance, wipe it from the disk, and stop charges. + diff --git a/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md b/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md new file mode 100644 index 000000000..3dcba4236 --- /dev/null +++ b/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md @@ -0,0 +1,132 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/add-elasticsearch-nodes.html +--- + +# Add and Remove Elasticsearch nodes [add-elasticsearch-nodes] + +When you start an instance of {{es}}, you are starting a *node*. An {{es}} *cluster* is a group of nodes that have the same `cluster.name` attribute. As nodes join or leave a cluster, the cluster automatically reorganizes itself to evenly distribute the data across the available nodes. + +If you are running a single instance of {{es}}, you have a cluster of one node. All primary shards reside on the single node. No replica shards can be allocated, therefore the cluster state remains yellow. The cluster is fully functional but is at risk of data loss in the event of a failure. + +:::{image} ../../images/elasticsearch-reference-elas_0202.png +:alt: A cluster with one node and three primary shards +::: + +You add nodes to a cluster to increase its capacity and reliability. By default, a node is both a data node and eligible to be elected as the master node that controls the cluster. You can also configure a new node for a specific purpose, such as handling ingest requests. For more information, see [Nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html). + +When you add more nodes to a cluster, it automatically allocates replica shards. When all primary and replica shards are active, the cluster state changes to green. + +:::{image} ../../images/elasticsearch-reference-elas_0204.png +:alt: A cluster with three nodes +::: + + +## Enroll nodes in an existing cluster [_enroll_nodes_in_an_existing_cluster_5] + +You can enroll additional nodes on your local machine to experiment with how an {{es}} cluster with multiple nodes behaves. + +::::{note} +To add a node to a cluster running on multiple machines, you must also set [`discovery.seed_hosts`](../deploy/self-managed/important-settings-configuration.md#unicast.hosts) so that the new node can discover the rest of its cluster. + +:::: + + +When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to localhost. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration. + +Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically. + +Additionally, only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need to set `transport.host` to a [supported value](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#network-interface-values) (such as uncommenting the suggested value of `0.0.0.0`), or an IP address that’s bound to an interface where other hosts can reach it. Refer to [transport settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings) for more information. + +To enroll new nodes in your cluster, create an enrollment token with the `elasticsearch-create-enrollment-token` tool on any existing node in your cluster. You can then start a new node with the `--enrollment-token` parameter so that it joins an existing cluster. + +1. In a separate terminal from where {{es}} is running, navigate to the directory where you installed {{es}} and run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool to generate an enrollment token for your new nodes. + + ```sh + bin\elasticsearch-create-enrollment-token -s node + ``` + + Copy the enrollment token, which you’ll use to enroll new nodes with your {{es}} cluster. + +2. From the installation directory of your new node, start {{es}} and pass the enrollment token with the `--enrollment-token` parameter. + + ```sh + bin\elasticsearch --enrollment-token + ``` + + {{es}} automatically generates certificates and keys in the following directory: + + ```sh + config\certs + ``` + +3. Repeat the previous step for any new nodes that you want to enroll. + +For more information about discovery and shard allocation, refer to [*Discovery and cluster formation*](../distributed-architecture/discovery-cluster-formation.md) and [Cluster-level shard allocation and routing settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html). + + +## Master-eligible nodes [add-elasticsearch-nodes-master-eligible] + +As nodes are added or removed Elasticsearch maintains an optimal level of fault tolerance by automatically updating the cluster’s *voting configuration*, which is the set of [master-eligible nodes](../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role) whose responses are counted when making decisions such as electing a new master or committing a new cluster state. + +It is recommended to have a small and fixed number of master-eligible nodes in a cluster, and to scale the cluster up and down by adding and removing master-ineligible nodes only. However there are situations in which it may be desirable to add or remove some master-eligible nodes to or from a cluster. + + +### Adding master-eligible nodes [modules-discovery-adding-nodes] + +If you wish to add some nodes to your cluster, simply configure the new nodes to find the existing cluster and start them up. Elasticsearch adds the new nodes to the voting configuration if it is appropriate to do so. + +During master election or when joining an existing formed cluster, a node sends a join request to the master in order to be officially added to the cluster. + + +### Removing master-eligible nodes [modules-discovery-removing-nodes] + +When removing master-eligible nodes, it is important not to remove too many all at the same time. For instance, if there are currently seven master-eligible nodes and you wish to reduce this to three, it is not possible simply to stop four of the nodes at once: to do so would leave only three nodes remaining, which is less than half of the voting configuration, which means the cluster cannot take any further actions. + +More precisely, if you shut down half or more of the master-eligible nodes all at the same time then the cluster will normally become unavailable. If this happens then you can bring the cluster back online by starting the removed nodes again. + +As long as there are at least three master-eligible nodes in the cluster, as a general rule it is best to remove nodes one-at-a-time, allowing enough time for the cluster to [automatically adjust](../distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md) the voting configuration and adapt the fault tolerance level to the new set of nodes. + +If there are only two master-eligible nodes remaining then neither node can be safely removed since both are required to reliably make progress. To remove one of these nodes you must first inform {{es}} that it should not be part of the voting configuration, and that the voting power should instead be given to the other node. You can then take the excluded node offline without preventing the other node from making progress. A node which is added to a voting configuration exclusion list still works normally, but {{es}} tries to remove it from the voting configuration so its vote is no longer required. Importantly, {{es}} will never automatically move a node on the voting exclusions list back into the voting configuration. Once an excluded node has been successfully auto-reconfigured out of the voting configuration, it is safe to shut it down without affecting the cluster’s master-level availability. A node can be added to the voting configuration exclusion list using the [Voting configuration exclusions](https://www.elastic.co/guide/en/elasticsearch/reference/current/voting-config-exclusions.html) API. For example: + +```console +# Add node to voting configuration exclusions list and wait for the system +# to auto-reconfigure the node out of the voting configuration up to the +# default timeout of 30 seconds +POST /_cluster/voting_config_exclusions?node_names=node_name + +# Add node to voting configuration exclusions list and wait for +# auto-reconfiguration up to one minute +POST /_cluster/voting_config_exclusions?node_names=node_name&timeout=1m +``` + +The nodes that should be added to the exclusions list are specified by name using the `?node_names` query parameter, or by their persistent node IDs using the `?node_ids` query parameter. If a call to the voting configuration exclusions API fails, you can safely retry it. Only a successful response guarantees that the node has actually been removed from the voting configuration and will not be reinstated. If the elected master node is excluded from the voting configuration then it will abdicate to another master-eligible node that is still in the voting configuration if such a node is available. + +Although the voting configuration exclusions API is most useful for down-scaling a two-node to a one-node cluster, it is also possible to use it to remove multiple master-eligible nodes all at the same time. Adding multiple nodes to the exclusions list has the system try to auto-reconfigure all of these nodes out of the voting configuration, allowing them to be safely shut down while keeping the cluster available. In the example described above, shrinking a seven-master-node cluster down to only have three master nodes, you could add four nodes to the exclusions list, wait for confirmation, and then shut them down simultaneously. + +::::{note} +Voting exclusions are only required when removing at least half of the master-eligible nodes from a cluster in a short time period. They are not required when removing master-ineligible nodes, nor are they required when removing fewer than half of the master-eligible nodes. +:::: + + +Adding an exclusion for a node creates an entry for that node in the voting configuration exclusions list, which has the system automatically try to reconfigure the voting configuration to remove that node and prevents it from returning to the voting configuration once it has removed. The current list of exclusions is stored in the cluster state and can be inspected as follows: + +```console +GET /_cluster/state?filter_path=metadata.cluster_coordination.voting_config_exclusions +``` + +This list is limited in size by the `cluster.max_voting_config_exclusions` setting, which defaults to `10`. See [Discovery and cluster formation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html). Since voting configuration exclusions are persistent and limited in number, they must be cleaned up. Normally an exclusion is added when performing some maintenance on the cluster, and the exclusions should be cleaned up when the maintenance is complete. Clusters should have no voting configuration exclusions in normal operation. + +If a node is excluded from the voting configuration because it is to be shut down permanently, its exclusion can be removed after it is shut down and removed from the cluster. Exclusions can also be cleared if they were created in error or were only required temporarily by specifying `?wait_for_removal=false`. + +```console +# Wait for all the nodes with voting configuration exclusions to be removed from +# the cluster and then remove all the exclusions, allowing any node to return to +# the voting configuration in the future. +DELETE /_cluster/voting_config_exclusions + +# Immediately remove all the voting configuration exclusions, allowing any node +# to return to the voting configuration in the future. +DELETE /_cluster/voting_config_exclusions?wait_for_removal=false +``` + diff --git a/deploy-manage/maintenance/ece.md b/deploy-manage/maintenance/ece.md new file mode 100644 index 000000000..536f8426b --- /dev/null +++ b/deploy-manage/maintenance/ece.md @@ -0,0 +1,7 @@ +# ECE maintenance + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/353 + +% Scope notes: Introduction about ECE maintenance and activities / actions. Explain the difference between deployments maintenance and ECE hosts infrastructure maintenance. \ No newline at end of file diff --git a/deploy-manage/maintenance/ece/delete-ece-hosts.md b/deploy-manage/maintenance/ece/delete-ece-hosts.md new file mode 100644 index 000000000..ebb901db7 --- /dev/null +++ b/deploy-manage/maintenance/ece/delete-ece-hosts.md @@ -0,0 +1,37 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-delete-runner.html +--- + +# Delete ECE hosts [ece-delete-runner] + +You might need to delete hosts for several reasons: + +* To remove some resources from your Elastic Cloud Enterprise installation if they are no longer required. +* To remove a faulty host from the Cloud UI so that it is no longer part of your Elastic Cloud Enterprise installation. + +Deleting a host only removes the host from your installation, it does not [remove the Elastic Cloud Enterprise software from the host](../../uninstall/uninstall-elastic-cloud-enterprise.md). After the host has been deleted, you can repurpose or troubleshoot the physical host on which the Elastic Cloud Enterprise host was located. + +To delete hosts: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Hosts**. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. For hosts that hold the allocator role: + + 1. [Enable maintenance mode](enable-maintenance-mode.md) on the allocator. + 2. [Move all nodes off the allocator](move-nodes-instances-from-allocators.md) and to other allocators in your installation. + +4. Go to **Hosts** and select a host. +5. Select **Manage roles** from the **Manage host** menu and remove all assigned roles. +6. Select **Demote host** from the **Manage host** menu if present. If the **Delete host** option is already enabled, skip this step. +7. Remove *all running* containers from the host, starting from the container with name `frc-runners-runner`. Then remove the storage directory (the default `/mnt/data/elastic/`). You can use the recommended [cleanup command](../../uninstall/uninstall-elastic-cloud-enterprise.md). Upon doing so, the UI should reflect the host is **Disconnected**, allowing the host to be deleted. +8. Select **Delete host** and confirm. + +::::{tip} +Refresh the page if the button isn’t active. +:::: + + diff --git a/deploy-manage/maintenance/ece/deployments-maintenance.md b/deploy-manage/maintenance/ece/deployments-maintenance.md new file mode 100644 index 000000000..4a0718735 --- /dev/null +++ b/deploy-manage/maintenance/ece/deployments-maintenance.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-maintenance-mode-deployments.html +--- + +# Deployments maintenance [ece-maintenance-mode-deployments] + +In some circumstances, you might need to temporarily restrict access to a node so you can perform corrective actions that might otherwise be difficult to complete. For example, if your cluster is being overwhelmed by requests because it is undersized for its workload, its nodes might not respond to efforts to resize. + +These actions act as a maintenance mode for cluster node. Performing these actions can stop the cluster from becoming completely unresponsive so that you can resolve operational issues much more effectively. + +* [**Stop routing to the instance**](start-stop-routing-requests.md): Block requests from being routed to the cluster node. This is a less invasive action than pausing the cluster. +* [**Pause an instance**](pause-instance.md): Suspend the node immediately by stopping the container that the node runs on without completing existing requests. This is a more aggressive action to regain control of an unresponsive node. + +As an alternative, to quickly add capacity to a deployment if it is unhealthy or at capacity, you can also [override the resource limit for a deployment](../../deploy/cloud-enterprise/resource-overrides.md). + + + diff --git a/deploy-manage/maintenance/ece/enable-maintenance-mode.md b/deploy-manage/maintenance/ece/enable-maintenance-mode.md new file mode 100644 index 000000000..138879baf --- /dev/null +++ b/deploy-manage/maintenance/ece/enable-maintenance-mode.md @@ -0,0 +1,45 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-maintenance-mode.html +--- + +# Enable maintenance mode [ece-maintenance-mode] + +Maintenance mode lets you perform actions on an allocator safely that might otherwise carry some risk. For example, if you want to remove the allocator role from a host, enabling maintenance mode prevents new Elasticsearch clusters and Kibana instances from being provisioned on the allocator whilst you are moving the existing nodes to another allocator or whilst you are removing the role. + +To put an allocator into maintenance mode: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Allocators**. +3. Choose the allocator you want to work with and select **Enable Maintenance Mode**. Confirm the action. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + + +After the allocator enters maintenance mode, no new Elasticsearch nodes or Kibana instances will be started on the allocator. Existing nodes will continue to work as expected. You can now safely perform actions like [moving nodes off the allocator](move-nodes-instances-from-allocators.md). + +If you want to make the allocator fully active again, select **Disable Maintenance Mode**. Confirm the action. + +::::{tip} +If you need the existing instances to stop routing requests you can [stop routing requests](deployments-maintenance.md) to disable incoming requests to particular instances. You can also massively disable all allocator instances routing with the [allocator-toggle-routing-requests.sh](https://download.elastic.co/cloud/allocator-toggle-routing-requests.sh) script. The script runs with the following parameters in the form environment variables: + +* `API_URL` Url of the administration API. +* `AUTH_HEADER` Curl format string representing the authentication header. +* `ALLOCATOR_ID` Action target allocator id. +* `ENABLE_TRAFFIC` Wether traffic to the selected allocator instances should be enabled (`true`) or disabled (`false`). + +This is an example of script execution to disable routing on all instances running on a given allocator: In this example the script disables routing on all instances running on a given allocator: + +```bash +AUTH_HEADER="Authorization: ApiKey $(cat ~/api.key)" API_URL="https://adminconsole:12443" ALLOCATOR_ID="192.168.44.10" ENABLE_TRAFFIC=false ./allocator-toggle-routing-requests.sh +``` + +The same script can be used to enable traffic again: + +```bash +AUTH_HEADER="Authorization: ApiKey $(cat ~/api.key)" API_URL="https://adminconsole:12443" ALLOCATOR_ID="192.168.44.10" ENABLE_TRAFFIC=true ./allocator-toggle-routing-requests.sh +``` + +:::: + + diff --git a/deploy-manage/maintenance/ece/maintenance-activities.md b/deploy-manage/maintenance/ece/maintenance-activities.md new file mode 100644 index 000000000..43bd56c89 --- /dev/null +++ b/deploy-manage/maintenance/ece/maintenance-activities.md @@ -0,0 +1,7 @@ +# Maintenance activities + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/353 + +% Scope notes: summarize the list of activites \ No newline at end of file diff --git a/deploy-manage/maintenance/ece/move-nodes-instances-from-allocators.md b/deploy-manage/maintenance/ece/move-nodes-instances-from-allocators.md new file mode 100644 index 000000000..be82f5ded --- /dev/null +++ b/deploy-manage/maintenance/ece/move-nodes-instances-from-allocators.md @@ -0,0 +1,78 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-move-nodes.html +--- + +# Move nodes or instances from allocators [ece-move-nodes] + +You might need to move Elasticsearch nodes, Kibana instances, and other components of the Elastic Stack between allocators from time to time for a number of reasons: + +* To prepare for removing the allocator role from the first host on which you installed Elastic Cloud Enterprise. +* To avoid downtime during maintenance: You can create a new allocator, move all deployments from an existing allocator to the new one, and then deal with the allocator that needs maintenance. +* To make room on an allocator: You can move some smaller deployments to another allocator if you need additional room for a larger one on an allocator. +* To move deployments after a failure: When host failures happen, you can move all deployments from the affected allocator to a healthy allocator quickly before spending any time on fixing the failure. + +::::{tip} +When you move all nodes from an existing allocator to the new one, ECE migrates the data to new nodes. The migration can take some time, especially when deployments contain large amounts of data and have a heavy workload. Is your deployment under a heavy workload? You might need to [stop routing requests](deployments-maintenance.md) first. +:::: + + + +## Before you begin [ece_before_you_begin_9] + +Before you move the nodes and instances that are part of a deployment, you need to make sure that you have sufficient capacity on another allocator. For example: If you have a deployment with a single 32 GB Elasticsearch node and a 4 GB Kibana instance, the allocator that you are moving the deployment to needs to have at least 36 GB of capacity. Note that moving nodes does not actually move the same node onto a different allocator. Under the covers, Elastic Cloud Enterprise creates a new node and then migrates the data for you. + +Elastic Cloud Enterprise will adhere to the high availability configuration when moving nodes, so make sure you have the additional capacity available in the relevant availability zone. For example: If you selected to deploy your cluster accross 3 availability zones, nodes can only move to an allocator in the same availability zone as the failed allocator. This is meant to ensure that the cluster can tolerate the failure of 2 availability zones. + +If you followed our recommendation and [tagged your allocators](../../deploy/cloud-enterprise/ece-configuring-ece-tag-allocators.md) to indicate what allocators you want components of the Elastic Stack to run on, the spare capacity you plan to use must be available on an allocator with the same tags. If you did not tag your allocators and edit the default instance configurations, ECE will move nodes and instances to wherever there is space. + +When you move all nodes from an existing allocator to the new one, ECE migrates the data to new nodes. The migration can take some time, especially when clusters contain large amounts of data and have a heavy workload. Is your cluster under a heavy workload? You might need to [stop routing requests](deployments-maintenance.md) first. + +To move nodes from one allocator to another one: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Allocators**. +3. Review the list of all allocators that are part of this installation and look for allocators that are unhealthy or find the allocator that you want to free up. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +4. Recommended: [Put the allocator into maintenance mode](enable-maintenance-mode.md) before continuing. +5. Select the name of an unhealthy allocator and then choose **Move Nodes** from the menu. +6. Select the nodes you want, then choose **Move Nodes**. +7. To customize how you would like to move the nodes, select **Customize settings**, choose your options, then select **Move nodes**. + + ::::{important} + Review **Customize Settings** before proceeding to move nodes. + :::: + + + Gracefully move data + : (Default) Gracefully move the data from the instances we’re about to remove from the cluster before stopping them. Never disable this setting at the same time as enabling `override_failsafe` on a non-Highly Available cluster since it can result in data loss. + + Skip snapshot + : If an allocator has failed or is otherwise unhealthy, select this option to move the nodes but disable the snapshot attempt. As this can perform potentially destructive actions on the deployment, do not use this option on a healthy allocator unless you are an advanced user. + + Restore snapshot to latest success + : Restore the cluster to the last successful snapshot. Recommended for single-node clusters hosted on unhealthy allocators. Any data indexed after the last snapshot was taken is lost. + + Extended maintenance + : Keep new instances in maintenance mode until a snapshot has been restored. If not enabled, new instances remain in maintenance mode only until they can join a cluster. + + Set target allocators + : Request that instances be moved to the specified allocators. If no allocators are specified, or those specified are unsuitable for the instances being moved, then any suitable healthy allocator can be used. + + Reallocate + : Create new containers for all nodes in the cluster. + + Set Timeout + : On by default. + + +::::{tip} +If you did not enable maintenance mode, set a target allocator under the advanced options when moving nodes to make sure the nodes do not end up on the same allocator again. By default, moving a node moves it to any allocator that has enough capacity. +:::: + + +1. Repeat **step 6** for each of the node types until no nodes remain on the allocator. +2. Optionally, once the nodes have been moved, **Delete Allocator**. + diff --git a/deploy-manage/maintenance/ece/pause-instance.md b/deploy-manage/maintenance/ece/pause-instance.md new file mode 100644 index 000000000..6e6301d1c --- /dev/null +++ b/deploy-manage/maintenance/ece/pause-instance.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-maintenance-mode-pausing.html +--- + +# Pause instance [ece-maintenance-mode-pausing] + +If an individual instance is experiencing issues, then you can stop it by selecting **Pause instance** from its menu. + +Pausing an instance immediately suspends the container without completing existing requests by running either [Docker `stop`](https://docs.docker.com/reference/cli/docker/container/stop/) or [Podman `stop`](https://docs.podman.io/en/stable/markdown/podman-stop.1.md), as applicable. The instance will then be marked as **Paused**. + +You can start an instance by selecting **Resume instance** from the menu. + +Pausing and resuming an instance can be helpful when an individual instance needs restarted without restarting the entire product. For example, you might restart an instance if an {{es}} node is unresponsive to the cluster due to [stuck JVM](../../../troubleshoot/elasticsearch/high-jvm-memory-pressure.md). diff --git a/deploy-manage/maintenance/ece/perform-ece-hosts-maintenance.md b/deploy-manage/maintenance/ece/perform-ece-hosts-maintenance.md new file mode 100644 index 000000000..b99702e27 --- /dev/null +++ b/deploy-manage/maintenance/ece/perform-ece-hosts-maintenance.md @@ -0,0 +1,126 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-perform-host-maintenance.html +--- + +# Perform ECE hosts maintenance [ece-perform-host-maintenance] + +These steps show how you can safely perform maintenance on hosts in your ECE installation. Host maintenance refers to actions that are not part of taking care of Elastic Cloud Enterprise itself and that you might need to perform for a number of different reasons, including: + +* To apply urgent operating system patches or hot fixes +* To perform regularly scheduled software or hardware upgrades +* To enable new features, such as encryption of data at rest +* To meet updated installation prerequisites + +You can perform these maintenance actions on the hosts in your ECE installation using one of these methods: + +* [By disabling the Docker daemon (nondestructive)](#ece-perform-host-maintenance-docker-disable) +* [By deleting the host (destructive)](#ece-perform-host-maintenance-delete-runner) +* [By shutting down the host (less destructive)](#ece-perform-host-maintenance-delete-runner) + +Which method you choose depends on how invasive your host maintenance needs to be. If your host maintenance could affect ECE, use the destructive method that first deletes the host from your installation. These methods include a step that moves any hosted Elasticsearch clusters and Kibana instances off the affected hosts and are generally considered safe, provided that your ECE installation still has sufficient resources available to operate after the host has been removed. + + +## By disabling the Docker daemon [ece-perform-host-maintenance-docker-disable] + +This method lets you perform maintenance actions on hosts without first removing the associated host from your Elastic Cloud Enterprise installation. It works by disabling the Docker daemon. The host remains a part of your ECE installation throughout these steps but will be offline and the resources it provides will not be available. + +To perform host maintenance: + +1. Recommended: If the host holds the allocator role and you have enough spare capacity: + + 1. [Enable maintenance mode](enable-maintenance-mode.md) on the allocator. + 2. [Move all nodes off the allocator](move-nodes-instances-from-allocators.md) and to other allocators in your installation. Moving all nodes lets you retain the same level of redundancy for highly available Elasticsearch clusters and ensures that other clusters without high availability remain available. + + ::::{important} + Skipping Step 1 will affect the availability of clusters with nodes on the allocator. + :::: + +2. Disable the Docker daemon: + + ```sh + sudo systemctl disable docker + sudo systemctl disable docker.socket + ``` + +3. Reboot the host: + + ```sh + sudo reboot + ``` + +4. Perform your maintenance on the host, such as patching the operating system. +5. Enable the Docker daemon: + + ```sh + sudo systemctl enable docker + sudo systemctl enable docker.socket + ``` + +6. Reboot the host again: + + ```sh + sudo reboot + ``` + +7. If you enabled maintenance mode in Step 1: Take the allocator out of maintenance mode. +8. Optional for allocators: ECE will start using the allocator again as you create new or change existing clusters, but it will not automatically redistribute nodes to an allocator after it becomes available. If you want to move nodes back to the same allocator after host maintenance, you need to manually [move the nodes](move-nodes-instances-from-allocators.md) and specify the allocator as a target. +9. Verify that all ECE services and deployments are back up by checking that the host shows a green status in the Cloud UI. + +After the host shows a green status in the Cloud UI, it is fully functional again and can be used as before. + + +## By deleting the host (destructive) [ece-perform-host-maintenance-delete-runner] + +This method lets you perform potentially destructive maintenance actions on hosts. It works by deleting the associated host, which removes the host from your Elastic Cloud Enterprise installation. To add the host to your ECE installation again after host maintenance is complete, you must reinstall ECE. + +To perform host maintenance: + +1. If the host holds the allocator role: + + 1. [Enable maintenance mode](enable-maintenance-mode.md) on the allocator. + 2. [Move all nodes off the allocator](move-nodes-instances-from-allocators.md) and to other allocators in your installation. Moving all nodes lets you retain the same level of redundancy for highly available clusters and ensures that other clusters without high availability remain available. + + ::::{important} + Do not skip this step or you will affect the availability of clusters with nodes on the allocator. You are in the process of removing the host from your installation and whatever ECE artifacts are stored on it will be lost. + :::: + +2. [Delete the host from your ECE installation](delete-ece-hosts.md). +3. Perform the maintenance on your host, such as enabling encryption of data at rest. +4. [Reinstall ECE on the host as if it were a new host and assign the same roles as before](../../deploy/cloud-enterprise/install-ece-on-additional-hosts.md). +5. Optional for allocators: ECE will start using the allocator again as you create new or change existing clusters, but it will not automatically redistribute nodes to an allocator after it becomes available. If you want to move nodes back to the same allocator after host maintenance, you need to manually [move the nodes](move-nodes-instances-from-allocators.md) and specify the allocator as a target. + +After the host shows a green status in the Cloud UI, the host is part of your ECE installation again and can be used as before. + + +## By shutting down the host (less destructive) [ece-perform-host-maintenance-shutdown-host] + +This method lets you perform potentially destructive maintenance actions on hosts. It works by temporarily shutting down an ECE host, e.g. for data center moves or planned power outages. It is offered as an non-guaranteed and less destructive alternative to fully [deleting a host](#ece-perform-host-maintenance-delete-runner) from your ECE installation. + +To shut down the host: + +1. Disable traffic from load balancers. +2. Shut down all allocators: + + 1. [Enable maintenance mode](enable-maintenance-mode.md) on the allocator. + 2. [Move all nodes off the allocator](move-nodes-instances-from-allocators.md) and to other allocators in your installation. Moving all nodes lets you retain the same level of redundancy for highly available clusters and ensures that other clusters without high availability remain available. + + ::::{important} + Do not skip this step or you will affect the availability of clusters with nodes on the allocator. You are in the process of removing the host from your installation and whatever ECE artifacts are stored on it will be lost. + :::: + +3. Shut down all non-director hosts. +4. Shut down directors. + +After performing maintenance, start up the host: + +1. Start all directors. +2. Verify that there is a healthy Zookeeper quorum (at least one `zk_server_state leader`, and `zk_followers` + `zk_synced_followers` should match the number of Zookeeper followers): + + ```sh + docker exec frc-zookeeper-servers-zookeeper sh -c 'for i in $(seq 2191 2199); do echo "$(hostname) port is $i" && echo mntr | nc localhost ${i}; done' + ``` + +3. Start all remaining hosts. +4. Re-enable traffic from load balancers. + diff --git a/deploy-manage/maintenance/ece/scale-out-installation.md b/deploy-manage/maintenance/ece/scale-out-installation.md new file mode 100644 index 000000000..5237a1d9e --- /dev/null +++ b/deploy-manage/maintenance/ece/scale-out-installation.md @@ -0,0 +1,31 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-add-capacity.html +--- + +# Scale out your installation [ece-add-capacity] + +Elastic Cloud Enterprise scales to whatever capacity you need. If you need more processing capacity because your allocators are close to being maxed out or because you want to enable high availability and need an additional availability zone, simply add more capacity and change your deployment configuration to make use of it. + +Check the available capacity: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Allocators** to view the available capacity. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + + In this case 3 GB and 6 GB on two different allocators: + + :::{image} ../../../images/cloud-enterprise-ece-available-capacity.png + :alt: The available capacity in an installation + ::: + + +If this is not sufficient, add more capacity to your installation: + +* [Install Elastic Cloud Enterprise on additional hosts](../../deploy/cloud-enterprise/install-ece-on-additional-hosts.md) to create additional capacity. +* [Add capacity](https://www.elastic.co/guide/en/cloud-enterprise/current/set-allocator-settings.html) to existing allocators by updating the allocator settings when adding memory to the host. +* [Assign roles](../../deploy/cloud-enterprise/assign-roles-to-hosts.md) to the additional hosts. If you need to handle a larger search or logging workload, assign the new hosts the allocator role. +* (Optional) [Tag allocators](../../deploy/cloud-enterprise/ece-configuring-ece-tag-allocators.md) to the new host to indicate what kind of hardware you have available. +* [Resize your deployment](../../deploy/cloud-enterprise/resize-deployment.md) to handle a larger workload. + diff --git a/deploy-manage/maintenance/ece/start-stop-routing-requests.md b/deploy-manage/maintenance/ece/start-stop-routing-requests.md new file mode 100644 index 000000000..064f97ce7 --- /dev/null +++ b/deploy-manage/maintenance/ece/start-stop-routing-requests.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-maintenance-mode-routing.html + - https://www.elastic.co/guide/en/cloud/current/ec-maintenance-mode-routing.html +--- + +# Start and stop routing requests + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/353 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-maintenance-mode-routing.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-maintenance-mode-routing.md \ No newline at end of file diff --git a/deploy-manage/maintenance/start-stop-services.md b/deploy-manage/maintenance/start-stop-services.md new file mode 100644 index 000000000..59059deeb --- /dev/null +++ b/deploy-manage/maintenance/start-stop-services.md @@ -0,0 +1,7 @@ +# Start and stop services + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/353 + +% Scope notes: Super brief summary \ No newline at end of file diff --git a/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md b/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md new file mode 100644 index 000000000..1fb5925a9 --- /dev/null +++ b/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md @@ -0,0 +1,234 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/restart-cluster.html +--- + +# Full Cluster restart and rolling restart procedures [restart-cluster] + +There may be [situations where you want to perform a full-cluster restart](../../security/secure-cluster-communications.md) or a rolling restart. In the case of [full-cluster restart](#restart-cluster-full), you shut down and restart all the nodes in the cluster while in the case of [rolling restart](#restart-cluster-rolling), you shut down only one node at a time, so the service remains uninterrupted. + +::::{warning} +Nodes exceeding the low watermark threshold will be slow to restart. Reduce the disk usage below the [low watermark](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-routing-watermark-low) before restarting nodes. + +:::: + + + +## Full-cluster restart [restart-cluster-full] + +1. **Disable shard allocation.** + + When you shut down a data node, the allocation process waits for `index.unassigned.node_left.delayed_timeout` (by default, one minute) before starting to replicate the shards on that node to other nodes in the cluster, which can involve a lot of I/O. Since the node is shortly going to be restarted, this I/O is unnecessary. You can avoid racing the clock by [disabling allocation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-routing-allocation-enable) of replicas before shutting down [data nodes](../../distributed-architecture/clusters-nodes-shards/node-roles.md#data-node-role): + + ```console + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "primaries" + } + } + ``` + + You can also consider [gateway settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-gateway.html) when restarting large clusters to reduce initial strain while nodes are processing [through discovery](../../distributed-architecture/discovery-cluster-formation.md). + +2. **Stop indexing and perform a flush.** + + Performing a [flush](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-flush.html) speeds up shard recovery. + + ```console + POST /_flush + ``` + + +1. **Temporarily stop the tasks associated with active {{ml}} jobs and {{dfeeds}}.** (Optional) + + {{ml-cap}} features require specific [subscriptions](https://www.elastic.co/subscriptions). + + You have two options to handle {{ml}} jobs and {{dfeeds}} when you shut down a cluster: + + * Temporarily halt the tasks associated with your {{ml}} jobs and {{dfeeds}} and prevent new jobs from opening by using the [set upgrade mode API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html): + + ```console + POST _ml/set_upgrade_mode?enabled=true + ``` + + When you disable upgrade mode, the jobs resume using the last model state that was automatically saved. This option avoids the overhead of managing active jobs during the shutdown and is faster than explicitly stopping {{dfeeds}} and closing jobs. + + * [Stop all {{dfeeds}} and close all jobs](https://www.elastic.co/guide/en/machine-learning/current/stopping-ml.html). This option saves the model state at the time of closure. When you reopen the jobs after the cluster restart, they use the exact same model. However, saving the latest model state takes longer than using upgrade mode, especially if you have a lot of jobs or jobs with large model states. + +2. **Shut down all nodes.** + + * If you are running {{es}} with `systemd`: + + ```sh + sudo systemctl stop elasticsearch.service + ``` + + * If you are running {{es}} with SysV `init`: + + ```sh + sudo -i service elasticsearch stop + ``` + + * If you are running {{es}} as a daemon: + + ```sh + kill $(cat pid) + ``` + +3. **Perform any needed changes.** +4. **Restart nodes.** + + If you have dedicated master nodes, start them first and wait for them to form a cluster and elect a master before proceeding with your data nodes. You can check progress by looking at the logs. + + As soon as enough master-eligible nodes have discovered each other, they form a cluster and elect a master. At that point, you can use the [cat health](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-health.html) and [cat nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-nodes.html) APIs to monitor nodes joining the cluster: + + ```console + GET _cat/health + + GET _cat/nodes + ``` + + The `status` column returned by `_cat/health` shows the health of each node in the cluster: `red`, `yellow`, or `green`. + +5. **Wait for all nodes to join the cluster and report a status of yellow.** + + When a node joins the cluster, it begins to recover any primary shards that are stored locally. The [`_cat/health`](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-health.html) API initially reports a `status` of `red`, indicating that not all primary shards have been allocated. + + Once a node recovers its local shards, the cluster `status` switches to `yellow`, indicating that all primary shards have been recovered, but not all replica shards are allocated. This is to be expected because you have not yet re-enabled allocation. Delaying the allocation of replicas until all nodes are `yellow` allows the master to allocate replicas to nodes that already have local shard copies. + +6. **Re-enable allocation.** + + When all nodes have joined the cluster and recovered their primary shards, re-enable allocation by restoring `cluster.routing.allocation.enable` to its default: + + ```console + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": null + } + } + ``` + + Once allocation is re-enabled, the cluster starts allocating replica shards to the data nodes. At this point it is safe to resume indexing and searching, but your cluster will recover more quickly if you can wait until all primary and replica shards have been successfully allocated and the status of all nodes is `green`. + + You can monitor progress with the [`_cat/health`](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-health.html) and [`_cat/recovery`](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-recovery.html) APIs: + + ```console + GET _cat/health + + GET _cat/recovery + ``` + +7. **Restart machine learning jobs.** (Optional) + + If you temporarily halted the tasks associated with your {{ml}} jobs, use the [set upgrade mode API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html) to return them to active states: + + ```console + POST _ml/set_upgrade_mode?enabled=false + ``` + + If you closed all {{ml}} jobs before stopping the nodes, open the jobs and start the datafeeds from {{kib}} or with the [open jobs](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html) and [start datafeed](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-start-datafeed.html) APIs. + + + +## Rolling restart [restart-cluster-rolling] + +1. **Disable shard allocation.** + + When you shut down a data node, the allocation process waits for `index.unassigned.node_left.delayed_timeout` (by default, one minute) before starting to replicate the shards on that node to other nodes in the cluster, which can involve a lot of I/O. Since the node is shortly going to be restarted, this I/O is unnecessary. You can avoid racing the clock by [disabling allocation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-routing-allocation-enable) of replicas before shutting down [data nodes](../../distributed-architecture/clusters-nodes-shards/node-roles.md#data-node-role): + + ```console + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "primaries" + } + } + ``` + + You can also consider [gateway settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-gateway.html) when restarting large clusters to reduce initial strain while nodes are processing [through discovery](../../distributed-architecture/discovery-cluster-formation.md). + +2. **Stop non-essential indexing and perform a flush.** (Optional) + + While you can continue indexing during the rolling restart, shard recovery can be faster if you temporarily stop non-essential indexing and perform a [flush](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-flush.html). + + ```console + POST /_flush + ``` + +3. **Temporarily stop the tasks associated with active {{ml}} jobs and {{dfeeds}}.** (Optional) + + {{ml-cap}} features require specific [subscriptions](https://www.elastic.co/subscriptions). + + You have two options to handle {{ml}} jobs and {{dfeeds}} when you shut down a cluster: + + * Temporarily halt the tasks associated with your {{ml}} jobs and {{dfeeds}} and prevent new jobs from opening by using the [set upgrade mode API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html): + + ```console + POST _ml/set_upgrade_mode?enabled=true + ``` + + When you disable upgrade mode, the jobs resume using the last model state that was automatically saved. This option avoids the overhead of managing active jobs during the shutdown and is faster than explicitly stopping {{dfeeds}} and closing jobs. + + * [Stop all {{dfeeds}} and close all jobs](https://www.elastic.co/guide/en/machine-learning/current/stopping-ml.html). This option saves the model state at the time of closure. When you reopen the jobs after the cluster restart, they use the exact same model. However, saving the latest model state takes longer than using upgrade mode, especially if you have a lot of jobs or jobs with large model states. + + * If you perform a rolling restart, you can also leave your machine learning jobs running. When you shut down a machine learning node, its jobs automatically move to another node and restore the model states. This option enables your jobs to continue running during the shutdown but it puts increased load on the cluster. + +4. **Shut down a single node in case of rolling restart.** + + * If you are running {{es}} with `systemd`: + + ```sh + sudo systemctl stop elasticsearch.service + ``` + + * If you are running {{es}} with SysV `init`: + + ```sh + sudo -i service elasticsearch stop + ``` + + * If you are running {{es}} as a daemon: + + ```sh + kill $(cat pid) + ``` + +5. **Perform any needed changes.** +6. **Restart the node you changed.** + + Start the node and confirm that it joins the cluster by checking the log file or by submitting a `_cat/nodes` request: + + ```console + GET _cat/nodes + ``` + +7. **Reenable shard allocation.** + + For data nodes, once the node has joined the cluster, remove the `cluster.routing.allocation.enable` setting to enable shard allocation and start using the node: + + ```console + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": null + } + } + ``` + +8. **Repeat in case of rolling restart.** + + When the node has recovered and the cluster is stable, repeat these steps for each node that needs to be changed. + +9. **Restart machine learning jobs.** (Optional) + + If you temporarily halted the tasks associated with your {{ml}} jobs, use the [set upgrade mode API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html) to return them to active states: + + ```console + POST _ml/set_upgrade_mode?enabled=false + ``` + + If you closed all {{ml}} jobs before stopping the nodes, open the jobs and start the datafeeds from {{kib}} or with the [open jobs](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html) and [start datafeed](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-start-datafeed.html) APIs. + + diff --git a/deploy-manage/maintenance/start-stop-services/restart-an-ece-deployment.md b/deploy-manage/maintenance/start-stop-services/restart-an-ece-deployment.md new file mode 100644 index 000000000..bf5b1e0a4 --- /dev/null +++ b/deploy-manage/maintenance/start-stop-services/restart-an-ece-deployment.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restart-deployment.html +--- + +# Restart an ECE deployment [ece-restart-deployment] + +To restart a running or a stopped deployment: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. In the **Deployment Management** section, select **Restart** and follow the steps to restart a deployment. + +You can also edit the configuration of the deployment before restarting it. + diff --git a/deploy-manage/maintenance/start-stop-services/restart-cloud-hosted-deployment.md b/deploy-manage/maintenance/start-stop-services/restart-cloud-hosted-deployment.md new file mode 100644 index 000000000..549659e41 --- /dev/null +++ b/deploy-manage/maintenance/start-stop-services/restart-cloud-hosted-deployment.md @@ -0,0 +1,17 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-restart-deployment.html + - https://www.elastic.co/guide/en/cloud/current/ec-api-deployment-other.html +--- + +# Restart a Cloud Hosted deployment + +% What needs to be done: Refine + +% Scope notes: api example + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-restart-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-api-deployment-other.md +% Notes: api example \ No newline at end of file diff --git a/deploy-manage/maintenance/start-stop-services/start-stop-elasticsearch.md b/deploy-manage/maintenance/start-stop-services/start-stop-elasticsearch.md new file mode 100644 index 000000000..99f656346 --- /dev/null +++ b/deploy-manage/maintenance/start-stop-services/start-stop-elasticsearch.md @@ -0,0 +1,28 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/starting-elasticsearch.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/stopping-elasticsearch.html +--- + +# Start and stop Elasticsearch + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/353 + +% Scope notes: Combine into one topic + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/starting-elasticsearch.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/stopping-elasticsearch.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$start-deb$$$ + +$$$start-rpm$$$ + +$$$_enroll_nodes_in_an_existing_cluster_3$$$ + +$$$start-es-deb-systemd$$$ \ No newline at end of file diff --git a/deploy-manage/maintenance/start-stop-services/start-stop-kibana.md b/deploy-manage/maintenance/start-stop-services/start-stop-kibana.md new file mode 100644 index 000000000..8600febf3 --- /dev/null +++ b/deploy-manage/maintenance/start-stop-services/start-stop-kibana.md @@ -0,0 +1,90 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/start-stop.html +--- + +# Start and stop Kibana [start-stop] + +The method for starting and stopping {{kib}} varies depending on how you installed it. If a password protected keystore is used, the environment variable `KBN_KEYSTORE_PASSPHRASE_FILE` can be used to point to a file containing the password, the environment variable `KEYSTORE_PASSWORD` can be defined, or you will be prompted to enter to enter the password on startup, + + +## Archive packages (`.tar.gz`) [start-start-targz] + +If you installed {{kib}} on Linux or Darwin with a `.tar.gz` package, you can start and stop {{kib}} from the command line. + + +### Run {{kib}} from the command line [_run_kib_from_the_command_line] + +Kibana can be started from the command line as follows: + +```sh +./bin/kibana +``` + +By default, Kibana runs in the foreground, prints its logs to the standard output (`stdout`), and can be stopped by pressing **Ctrl-C**. + +If this is the first time you’re starting {{kib}}, this command generates a unique link in your terminal to enroll your {{kib}} instance with {{es}}. + +1. In your terminal, click the generated link to open {{kib}} in your browser. +2. In your browser, paste the enrollment token that was generated in the terminal when you started {{es}}, and then click the button to connect your {{kib}} instance with {{es}}. +3. Log in to {{kib}} as the `elastic` user with the password that was generated when you started {{es}}. + +::::{note} +If you need to reset the password for the `elastic` user or other built-in users, run the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) tool. To generate new enrollment tokens for {{kib}} or {{es}} nodes, run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool. These tools are available in the {{es}} `bin` directory. + +:::: + + + +## Archive packages (`.zip`) [start-stop-zip] + +If you installed {{kib}} on Windows with a `.zip` package, you can stop and start {{kib}} from the command line. + + +### Run {{kib}} from the command line [_run_kib_from_the_command_line_2] + +Kibana can be started from the command line as follows: + +```sh +.\bin\kibana.bat +``` + +By default, Kibana runs in the foreground, prints its logs to `STDOUT`, and can be stopped by pressing **Ctrl-C**. + +If this is the first time you’re starting {{kib}}, this command generates a unique link in your terminal to enroll your {{kib}} instance with {{es}}. + +1. In your terminal, click the generated link to open {{kib}} in your browser. +2. In your browser, paste the enrollment token that was generated in the terminal when you started {{es}}, and then click the button to connect your {{kib}} instance with {{es}}. +3. Log in to {{kib}} as the `elastic` user with the password that was generated when you started {{es}}. + +::::{note} +If you need to reset the password for the `elastic` user or other built-in users, run the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) tool. To generate new enrollment tokens for {{kib}} or {{es}} nodes, run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool. These tools are available in the {{es}} `bin` directory. + +:::: + + + +## Debian and RPM packages [start-stop-deb-rpm] + + +### Run {{kib}} with `systemd` [_run_kib_with_systemd] + +To configure {{kib}} to start automatically when the system starts, run the following commands: + +```sh +sudo /bin/systemctl daemon-reload +sudo /bin/systemctl enable kibana.service +``` + +{{kib}} can be started and stopped as follows: + +```sh +sudo systemctl start kibana.service +sudo systemctl stop kibana.service +``` + +These commands provide no feedback as to whether {{kib}} was started successfully or not. Log information can be accessed via `journalctl -u kibana.service`. + + + +$$$_run_kibana_from_the_command_line$$$ \ No newline at end of file diff --git a/deploy-manage/manage-connectors.md b/deploy-manage/manage-connectors.md new file mode 100644 index 000000000..3bfb4c045 --- /dev/null +++ b/deploy-manage/manage-connectors.md @@ -0,0 +1,21 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/action-types.html + - https://www.elastic.co/guide/en/serverless/current/action-connectors.html +--- + +# Manage connectors + +% What needs to be done: Align serverless/stateful + +% GitHub issue: https://github.com/elastic/docs-projects/issues/352 + +% Scope notes: Connectors management, probably moving some content to reference. We should align the serverless and stateful documentation. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/action-types.md +% Notes: 28 children +% - [ ] ./raw-migrated-files/docs-content/serverless/action-connectors.md + +$$$connector-management$$$ \ No newline at end of file diff --git a/deploy-manage/manage-spaces.md b/deploy-manage/manage-spaces.md new file mode 100644 index 000000000..b9ac03522 --- /dev/null +++ b/deploy-manage/manage-spaces.md @@ -0,0 +1,26 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/xpack-spaces.html + - https://www.elastic.co/guide/en/serverless/current/spaces.html +--- + +# Manage spaces + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/348 + +% Scope notes: Create a new landing page including the content that is relevant for both serverless and stateful Highlight the differences in subheadings for serverless and stateful Link to solution topics on spaces + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/xpack-spaces.md +% - [ ] ./raw-migrated-files/docs-content/serverless/spaces.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$spaces-control-feature-visibility$$$ + +$$$spaces-control-user-access$$$ + +$$$spaces-managing$$$ \ No newline at end of file diff --git a/deploy-manage/monitor.md b/deploy-manage/monitor.md new file mode 100644 index 000000000..1a607aa46 --- /dev/null +++ b/deploy-manage/monitor.md @@ -0,0 +1,19 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/monitor-elasticsearch-cluster.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/secure-monitoring.html +--- + +# Monitoring + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: one link left for redirection purposes. we have to write an introduction to this big section about Monitoring and Logging. Explain what is monitoring about (metrics and logs) and how orchestrators can help by automatically setting up the beats or monitoring agents. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/monitor-elasticsearch-cluster.md +% Notes: Existing articles about monitoring: Elasticsearch, Cloud, Cloud-enterprise, Cloud on Kubernetes, Kibana books Might need a new landing page +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/secure-monitoring.md \ No newline at end of file diff --git a/deploy-manage/monitor/autoops.md b/deploy-manage/monitor/autoops.md new file mode 100644 index 000000000..63e19c082 --- /dev/null +++ b/deploy-manage/monitor/autoops.md @@ -0,0 +1,60 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops.html +--- + +# AutoOps [ec-autoops] + +AutoOps diagnoses issues in Elasticsearch by analyzing hundreds of metrics, providing root-cause analysis and accurate resolution paths. With AutoOps, customers can prevent and resolve issues, cut down administration time, and optimize resource utilization. + +:::{image} ../../images/cloud-autoops-overview-page.png +:alt: The Overview page +::: + + +## AutoOps key features [ec_autoops_key_features] + +* Real-time root-cause analysis for hundreds of issues. +* Accurate resolution paths and customized recommendations. +* Insight into what occurred and detailed views into nodes, index, shards, and templates. +* Wide range of insights, including: + + * Cluster status, node failures, and shard sizes. + * High CPU, memory, disk usage, and other resource-related metrics. + * Misconfigurations and possible optimizations. + * Insights on data structure, shards, templates, and mapping optimizations. + * Unbalanced loads between nodes. + * Indexing latency, rejections, search latency, high index/search queues, and slow queries. + * Resource utilization. + + + +## Additional capabilities [ec_additional_capabilities] + +* Multi-deployment dashboard to quickly spot issues across all clusters. +* Possibility to customize event triggers and connect to different notification services such as PagerDuty, Slack, MS Teams, and webhooks. +* Long-term reports for sustained evaluation. This feature is currently not available and will be rolled out shortly. + + +## AutoOps retention period [ec_autoops_retention_period] + +AutoOps currently has a four-day retention period for all Cloud Hosted customers. + + +## AutoOps scope [ec_autoops_scope] + +AutoOps currently monitors only {{es}}, not the entire {{stack}}. Any deployment information pertains solely to {{es}}. AutoOps supports {{es}} version according to the [supported Elastic Stack versions](https://www.elastic.co/support/eol). There are plans to expand AutoOps monitoring to the entire stack. + + + + + + + + + + + + + + diff --git a/deploy-manage/monitor/autoops/ec-autoops-deployment-view.md b/deploy-manage/monitor/autoops/ec-autoops-deployment-view.md new file mode 100644 index 000000000..9f15ae799 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-deployment-view.md @@ -0,0 +1,51 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-deployment-view.html +--- + +# Deployment [ec-autoops-deployment-view] + +The **Deployment** view is the event control panel that allows you to see which issues are affecting the {{es}} cluster and get a list of action items to address them. + +:::{image} ../../../images/cloud-autoops-deployment-view.png +:alt: The Deployment view +::: + +## Events over time [ec-autoops-events-over-time] + +The **Events Over Time** panel lists all the recent events the {{es}} cluster has triggered, ordered by criticality. It also gives a color-coded heat map to help understand when and how often a particular event happened. Click on any mosaic to get details about a particular event, for example the specific node/index/shard affected, event time and duration, and a detailed description of the actions you can take to mitigate that event. + +Refer to [AutoOps events](ec-autoops-events.md) for more details. + + +## Open events [ec-autoops-open-events] + +The **Open Events** panel lists open events sorted by severity and time. When the conditions that triggered the event no longer exist, the event is automatically set to close and appear in the **Events History** panel. Closing an event does not necessarily indicate that the customer resolved the issue, but rather that AutoOps no longer detects it. + + +## Events History [ec-events-history] + +The **Events History** panel lists events that happened at some point and that have been triggered, but some conditions changed and are no longer active. For example, when your cluster experiences a peak in search rate, that might trigger a "Too many tasks on queue" event. Now, your cluster is more relaxed in terms of search rate, so this event is no longer an issue, but it was recorded for historical reasons. Events history is also sorted by severity first and then by time. + + +## Deployment Info [ec-deployment-information] + +The **Deployment Info** panel provides a quick overview of the {{es}} cluster resources in the selected deployment, such as {{es}} version, cluster status (indicated by the colors green, yellow, or red) at the top right, number of nodes distributed by role, and resources metrics. + +:::{image} ../../../images/cloud-autoops-deployment-info.png +:alt: The AutoOps Deployment Info +::: + + +## Performance [ec-deployment-performance] + +The **Performance** panel shows key performance metrics, aggregated at both the cluster level and the selected tier levels: + +:::{image} ../../../images/cloud-autoops-deployment-performance.png +:alt: The AutoOps Deployment Performance +::: + +* **Search rate**: The number of search requests executed per second across all shards in the deployment, as well as within the selected data tiers. +* **Search latency**: The average latency of search operations across all shards in the deployment, and within the selected data tiers. +* **Indexing rate**: The number of documents indexed per second across all shards in the deployment, as well as within the selected data tiers. +* **Indexing latency**: The average latency of indexing operations across all shards in the deployment, and within the selected data tiers. diff --git a/deploy-manage/monitor/autoops/ec-autoops-dismiss-event.md b/deploy-manage/monitor/autoops/ec-autoops-dismiss-event.md new file mode 100644 index 000000000..9f0c308e3 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-dismiss-event.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-dismiss-event.html +--- + +# Dismiss Events [ec-autoops-dismiss-event] + +Some events that are triggered may not require your attention immediately, or at all. Users with the appropriate permissions can choose to dismiss an event, preventing AutoOps from opening it. This action can be reversed using the Dismiss events report. + +:::{image} ../../../images/cloud-autoops-dismiss-events.png +:alt: Dismiss events +::: + diff --git a/deploy-manage/monitor/autoops/ec-autoops-event-settings.md b/deploy-manage/monitor/autoops/ec-autoops-event-settings.md new file mode 100644 index 000000000..32f4e1437 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-event-settings.md @@ -0,0 +1,37 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-event-settings.html +--- + +# Events Settings [ec-autoops-event-settings] + +AutoOps events are triggered when specific conditions are met and are closed when those conditions are no longer satisfied. An event can be triggered by multiple conditions, and each event comes with a default setting that can be adjusted differently for each connected deployment. + +::::{note} +Only a user with Cloud Organization Owner role can set up notifications. +:::: + + +To view event settings, go to the event details page and select **Customize** from the menu. Note that for some events, AutoOps doesn’t provide the option to customize it. + +The event settings include: + +* Event trigger threshold - This is a list of parameters explicitly set for an event. Default settings can be adjusted to meet operational and business needs. You can apply different settings to some or all deployments. +* Index patterns to exclude - AutoOps will exclude system indices to prevent unnecessary events from opening. You can add or remove indices from the list. +* Data roles tier to exclude from indications - Add threshold based on the type of data tier. + +:::{image} ../../../images/cloud-autoops-event-settings.png +:alt: Event settings +::: + + +## Event settings report [ec-event-settings-report] + +The **Event Settings** report provides a list of all the events for which the settings were modified. + +From the **Event Settings** report, you can click **Add** to add new settings, or select the edit icon to modify the existing settings. + +:::{image} ../../../images/cloud-autoops-events-settings-report.png +:alt: Event settings report +::: + diff --git a/deploy-manage/monitor/autoops/ec-autoops-events.md b/deploy-manage/monitor/autoops/ec-autoops-events.md new file mode 100644 index 000000000..313c62bff --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-events.md @@ -0,0 +1,64 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-events.html +--- + +# AutoOps events [ec-autoops-events] + +An AutoOps event provides a detailed analysis of a specific issue, including why it was triggered and the steps needed to resolve it. The following sections provide you with comprehensive insights and context around issues, the reasons why the event was created, as well as the affected nodes and indices with high indexing activity. + +:::{image} ../../../images/cloud-autoops-events.png +:alt: AutoOps events +::: + + +## What was detected [ec-autoops-what-was-detected] + +This section describes the reasons for which the event was created, as well as links to drill down into the issue. + + +## Recommendations [ec-autoops-recommendations] + +AutoOps provides a set of recommendations. The sequence of their appearance indicates the suggested order of steps to address the issue. + + +## Event duration [ec-autoops-event-duration] + +The time the event was detected (opened at) and the time AutoOps identified that the issue no longer exists (closed at). The closing of an event does not necessarily indicate that the customer resolved the issue, but rather that AutoOps no longer detects it. + + +## Background and impact [ec-autoops-background-impact] + +Provides background and context as to why an event is important, and the impact it can have on performance and stability. + + +## Event timeline chart [ec-autoops-event-timeline] + +This chart visually represents metrics related to an issue. It appears only for events with dynamic metrics. For example, load issues will have this section, while settings-related issues will not. The event timeline chart displays just the last 15 minutes. + + +## Event severity [ec-autoops-event-severity] + +Events are categorized into three levels of severity - high, medium, and low - based on their potential impact on cluster performance and stability: + +* **High**: Events can immediately cause significant usability, performance and stability problems. +* **Medium**: Events may lead to severe problems if not addressed. +* **Low**: Events have minimal/not urgent impact. + + +## Event settings [ec-autoops-event-customize] + +AutoOps events are set to `open` and `close` based on triggering mechanisms that have default settings for each event type. You can modify the default settings through the Customize option in the event settings. Be cautious while changing these settings, to avoid situations where alerts fail to trigger. + + +## Notifications [ec-autoops-notifications] + +AutoOps can send notifications to a variety of operation management tools like PagerDuty, Opsgenie, Slack, Teams and custom webhooks. Refer to [Notifications settings](ec-autoops-notifications-settings.md) for more details. + + +## Sharing events with others [ec-autoops-event-sharing] + +You can easily share event information with other users by sending them a direct link to the AutoOps event using the share event link located at the top right of the event window. + +Only users with access to the AutoOps deployment from which the link was copied can view the event details. + diff --git a/deploy-manage/monitor/autoops/ec-autoops-faq.md b/deploy-manage/monitor/autoops/ec-autoops-faq.md new file mode 100644 index 000000000..0cf1eff85 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-faq.md @@ -0,0 +1,39 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-faq.html +--- + +# AutoOps FAQ [ec-autoops-faq] + +This frequently-asked-questions list answers some of your more common questions about AutoOps. + +$$$faq-what-is-autoops$$$What is AutoOps? What does it do? +: AutoOps for Elasticsearch significantly simplifies cluster management with performance recommendations, resource utilization and cost insights, real-time issue detection and resolution paths. By analyzing hundreds of Elasticsearch metrics, your configuration, and usage patterns, AutoOps recommends operational and monitoring insights that deliver savings in administration time and hardware costs. + +$$$faq-autoops-availability$$$When will AutoOps be available for Self-hosted and Serverless users? +: AutoOps will be available for Self-hosted and Serverless customers with a different set of capabilities in the future. + +$$$faq-autoops-monitoring$$$Does AutoOps monitor the entire Elastic Stack? +: AutoOps is currently limited to {{es}} (not {{kib}}, Logstash and Beats). + +$$$faq-autoops-supported-versions$$$What versions of Elasticsearch are supported for Elastic Cloud Hosted? +: AutoOps is currently available for {{es}} versions 7.17 and above. + +$$$faq-autoops-license$$$How is AutoOps currently licensed? +: AutoOps current feature set is available to Elastic Cloud Hosted customers at all subscription tiers. For more information please refer to the [subscription page](https://www.elastic.co/subscriptions/cloud). + +$$$faq-autoops-installation$$$How does AutoOps get installed and why may I not see AutoOps available on specific deployments? +: AutoOps is automatically applied to {{es}} clusters on Elastic Cloud, rolling out in phases across CSPs and regions. Read more about AutoOps [roll out](ec-autoops-regions.md) status. + +$$$faq-autoops-issue-resolution$$$Can AutoOps currently automatically resolve issues? +: AutoOps only analyzes metrics, and is a “read-only” solution. + +$$$faq-autoops-data-retention$$$How long does Elastic retain AutoOps data? +: Currently, AutoOps has a four-day retention period for all Hosted customers. + +$$$faq-autoops-metrics-storage$$$Where are AutoOps metrics stored, and does AutoOps affect customer ECU usage? +: AutoOps metrics are stored internally within the Elastic infrastructure, not on customer deployments. Therefore, using AutoOps does not consume customer ECU). + +$$$faq-autoops-vs-stack-monitoring$$$Does AutoOps replace Stack Monitoring now? +: As of now, AutoOps provides insights on {{es}} (not {{kib}}, Logstash and Beats) and analyzes metrics, but not logs. Stack Monitoring covers the entire stack and with it you can analyze logs. + diff --git a/deploy-manage/monitor/autoops/ec-autoops-how-to-access.md b/deploy-manage/monitor/autoops/ec-autoops-how-to-access.md new file mode 100644 index 000000000..fd0bf60c2 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-how-to-access.md @@ -0,0 +1,22 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-how-to-access.html +--- + +# How to access AutoOps [ec-autoops-how-to-access] + +::::{note} +AutoOps supports {{es}} version according to the [supported Elastic Stack versions](https://www.elastic.co/support/eol). +:::: + + +To access AutoOps from your Elastic Cloud console, follow these steps: + +1. Log in to your Elastic Cloud Hosted account. Use your credentials to access your Elastic Cloud dashboard. +2. Navigate through your list of deployments and locate the one you want to manage. +3. Click **Manage** on the right side of the selected deployment. +4. On the deployment details page, click **Open AutoOps**. + +:::{image} ../../../images/cloud-autoops-how-to-access.png +:alt: How to access AutoOps +::: diff --git a/deploy-manage/monitor/autoops/ec-autoops-index-view.md b/deploy-manage/monitor/autoops/ec-autoops-index-view.md new file mode 100644 index 000000000..c2f10acef --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-index-view.md @@ -0,0 +1,43 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-index-view.html +--- + +# Indices [ec-autoops-index-view] + +The **Indices** view provides detailed statistics for each {{es}} index in your deployment. + +:::{image} ../../../images/cloud-autoops-index-view.png +:alt: The Indices view +::: + +The **Indices** view is essential for monitoring {{es}} indices, and offers comprehensive insights at a glance by displaying a clear and informative table about the following metrics: + +* Index Name +* Primary Shards and Total Shards +* Shard Size +* Size in Bytes +* Doc Count +* Indexing Rate/Sec +* Search Rate/Sec +* Index Latency +* Search Latency + +You can expand each index entry to dive deeper into real-time metrics. This is an intuitive and dynamic feature that allows you to visualize index activities and trends, in order to detect anomalies and optimize search efficiency. + +The **Indices** view offers you a powerful tool for managing and optimizing your {{es}} indices. By providing a detailed and up-to-date overview of index performance and usage, AutoOps ensures that your search and indexing operations run smoothly and efficiently. + + +## Index metrics [ec-autoops-index-metrics] + +| Metrics name | Metrics description | | +| --- | --- | --- | +| Size | Total size of all primary shards of the index | | +| Indexing rate | Number of documents being indexed per second on primary shards of the index | | +| Search rate | Number of search requests being executed per second on all shards of the index | | +| Document count | Total number of non-deleted documents in all primary shards of the index, including nested documents | | +| Indexing latency | Average latency for indexing documents, which is the time it takes to index documents divided by the number that were indexed in primary shards of the index | | +| Search latency | Average latency for searching, which is the time it takes to execute searches divided by the number of searches submitted to all shards of the index | | +| Errors | Number of failed indexing operations for the index | | +| Merge rate | Number of merge operations being executed per second on all primary shards of the index | | + diff --git a/deploy-manage/monitor/autoops/ec-autoops-nodes-view.md b/deploy-manage/monitor/autoops/ec-autoops-nodes-view.md new file mode 100644 index 000000000..47b4ec3d3 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-nodes-view.md @@ -0,0 +1,55 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-nodes-view.html +--- + +# Nodes [ec-autoops-nodes-view] + +The **Nodes** view provides a thorough overview on the essential metrics for all monitored deployment nodes. You can delve into specific nodes to observe metrics over extended periods. This includes data on the indexing rate and latency, search rate and latency, as well as details concerning thread pools, data, circuit breakers, network, disk, and additional elements. + +:::{image} ../../../images/cloud-autoops-node-view.png +:alt: The Node view +::: + +Similar to the **Deployment** view, the list of open events is sorted by severity and open time. + +The following table lists all the nodes used by the Deployment {{es}} cluster, presenting node name, role and status. The elected master node will be marked with a start sign. + +| Area | Metrics name | Metrics description | | +| --- | --- | --- | --- | +| Activity | Indexing rate | Number of documents being indexed per second on all primary and replica shards hosted on the node. | | +| | Indexing latency | Average latency for indexing documents, which is the time it takes to index documents divided by the number that were indexed in all primary and replica shards hosted on the node. | | +| | Search rate | Number of search requests being executed per second on all shards hosted on the node. | | +| | Search latency | Average latency for searching, which is the time it takes to execute searches divided by the number of searches submitted to the node. | | +| Host and Process | Load | Load average of the node over the last five minutes. | | +| | CPU | Percentage of the CPU usage for the {{es}} process running on the node. | | +| | Heap used in bytes | Total JVM heap memory used by the {{es}} process running on the node. | | +| | GC | Average time spent doing GC in milliseconds on the node. | | +| Thread pools | Write | Number of index, bulk and write operations in the queue, as well as the total number of completed and rejected operations in those pools. | | +| | Search | Number of search operations in the queue, as well as the total number of completed and rejected operations in that pool. | | +| | Management | Number of management operations in the queue, as well as the total number of completed and rejected operations in that pool. | | +| | Snapshot | Number of snapshot operations in the queue, as well as the total number of completed and rejected operations in that pool. | | +| Data | Disk usage | Amount of used disk storage on the node. | | +| | Shards count | Number of primary and replica shards hosted on the node. | | +| | Segment count | Number of segments hosted on the node. | | +| | Documents count | Number of documents hosted on the node. | | +| HTTP | HTTP current open | Current number of open HTTP connections for the node. | | +| | HTTP connections open rate | Number of HTTP connections opened per second. | | +| Circuit breakers | Parent Used | Estimated memory used for the parent circuit breaker. | | +| | Field Data used | Estimated memory used for the field data circuit breaker. | | +| | Request used | Estimated memory used for the request circuit breaker. | | +| | Parent tripped | Total number of times the parent circuit breaker has been triggered and prevented an out-of-memory error. | | +| | Field data tripped | Total number of times the field data circuit breaker has been triggered and prevented an-out-of memory error. | | +| | Request tripped | Total number of times the request circuit breaker has been triggered and prevented an out-of-memory error. | | +| Network | Network rx bytes | Size of RX packets received by the node during internal cluster communication. | | +| | Network rx count | Total number of RX packets received by the node during internal cluster communication. | | +| | Network tx bytes | Size of TX packets sent by the node during internal cluster communication. | | +| | Network tx count | Total number of TX packets received by the node during internal cluster communication. | | +| Disk | Disk read bytes | The total number of bytes read across all devices used by {{es}}. | | +| | Disk read IOPS | The total number of completed read operations across all devices used by {{es}}. | | +| | Disk write bytes | The total number of bytes written across all devices used by {{es}}. | | +| | Disk write IOPS | The total number of completed write operations across all devices used by {{es}}. | | +| Activity-Additional | Merge rate | Number of merge operations being executed per second on all shards hosted on the node. | | +| | Merge latency | Average latency for merging, which is the time it takes to execute merges divided by the number of merge operations submitted to the node. | | +| | Indexing failed | Number of failed indexing operations on the node. | | + diff --git a/deploy-manage/monitor/autoops/ec-autoops-notifications-settings.md b/deploy-manage/monitor/autoops/ec-autoops-notifications-settings.md new file mode 100644 index 000000000..0143922b1 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-notifications-settings.md @@ -0,0 +1,206 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-notifications-settings.html +--- + +# Notifications settings [ec-autoops-notifications-settings] + +AutoOps can notify you of new events opened or closed through various methods and operation management tools. With a customizable mechanism, you can specify which events you want to be notified about, how you wish to receive these notifications, and their frequency. + +::::{note} +Only organization owners can configure these settings. +:::: + + +To set up notifications you have to: + +1. Set up connectors to specify where the notifications will be sent. +2. Add notification filters to determine which events will be sent to each connector. + + +## AutoOps connectors [ec-autoops-connectors] + +To receive notifications for new events, the first step is to specify where the notifications should be sent. AutoOps provides a selection of [built-in connectors](#ec-built-in-connectors) to choose from. You can set up multiple connectors, even of the same type, based on your needs. + + +## Set up a connector [ec-setup-autoops-connectors] + +1. On the **Notifications Settings** page, navigate to the **Connector Settings** tab and click **Add**. +2. From the drop-down list, choose the connector you want to set up and follow the instructions. +3. Click **Validate** to send a test message. +4. Save your settings. + + +## Add notification filters [ec-add-notification-filters] + +A notification filter lets you choose which events to receive notifications for and how you want to be notified. You can create an unlimited number of filters, and the same connector can be used across multiple filters. + +To set up a filter, follow these steps: + +1. On the **Notification settings** page, navigate to the **Filter Setting** tab and click **Add**. +2. Choose a name that best describes the type of alert notification. This name will appear in other reports and dashboards. +3. Select the deployments that the new created events will trigger the alert for. +4. Select the connectors to receive the notification. +5. Use the **Delay** field to set the period of time AutoOps will hold before sending the notification. If during this time all of the events listed in this filter are closed by AutoOps, no notification will be sent. +6. Choose the type of events this filter applies to. + + +## Built-in connectors [ec-built-in-connectors] + +The following connectors are available with AutoOps: + +* [PagerDuty integration](#ec-autoops-pagerduty-integration) +* [Slack integration](#ec-autoops-slack-integration) +* [VictorOps integration](#ec-autoops-victorops-integration) +* [Opsgenie integration](#ec-autoops-opsgenie-integration) +* [Microsoft Teams Configuration integration](#ec-autoops-ms-configuration-integration) +* [Webhook integration](#ec-autoops-webhook-integration) + + +### PagerDuty integration [ec-autoops-pagerduty-integration] + +The PagerDuty integration consists of the following parts: + +**PagerDuty configuration** + +1. Follow the steps described in the [Events Integration Functionality](https://developer.pagerduty.com/docs/8a76ad16d6b52-events-integration-functionality) section. +2. Save the integration URL key as you will need it later. + +**AutoOps configuration** + +1. Add a new PagerDuty endpoint using the PagerDuty configuration application key. +2. To receive Slack notifications, add a notification filter. Scroll down the Notification page and click **Add**. +3. Fill in the filter details. +4. Select the events that should be sent to this output. + + +### Slack integration [ec-autoops-slack-integration] + +To set up a webhook to send AutoOps notifications to a Slack channel, go through the following steps. + +1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) +2. Click **Create new App**. +3. Select **From Scratch**. +4. Choose a name for your webhook and the workspace to create the app. Click **Create App**. +5. From the left menu, select **Incoming Webhooks**. +6. Toggle the **Activate Incoming Webhooks** to On. +7. Click **Request to Add New Webhook**. +8. Select a Slack channel from the list to receive the notifications and click **Allow**. +9. Copy the webhook URL to set up the webhook notification endpoint in AutoOps. +10. Add the webhook URL when creating the endpoint. + + +### VictorOps integration [ec-autoops-victorops-integration] + +The VictorOps integration consists of the following parts: + +**VictorOps configuration** + +1. Follow the steps described in the [REST Endpoint Integration Guide](https://help.victorops.com/knowledge-base/rest-endpoint-integration-guide/). +2. Save the integration URL key as you will need it later. + +**AutoOps configuration** + +1. Add a new PagerDuty endpoint using the PagerDuty configuration application key. +2. To receive Slack notifications, add a notification filter. Scroll down the Notification page and click Add. +3. Fill in the filter details. +4. Select the events that should be sent to this output. + + +### Opsgenie integration [ec-autoops-opsgenie-integration] + +The Opsgenie integration consists of the following parts: + +**Opsgenie configuration** + +1. Open the main page of your Opsgenie account and click the **Teams** tab (a team must be defined). +2. Go to the **Settings** tab of your Opsgenie page, and select Integrations. +3. Select your **Team** and click **Integrations** from the left menu. +4. Click **Add Integration**. On the **Integration List**, search for API. +5. Name your integration and click **Save**. + +**AutoOps configuration** + +1. Open AutoOps and go to **User Profile**. Then, select **Notifications**. +2. Click **Add** and select **Opsgenie** from the dropdown list. +3. Name your endpoint and add Api Key from opsgenie API configuration. Click the validate button to make sure that your notification setting is working. Don’t forget to save your notification endpoint! +4. To receive notifications on Opsgenie, you need to add a notification filter. Scroll down the **Notification** page and click **Add**. +5. Fill in the filter details. +6. Select events that should be sent to this output. + + +### Microsoft Teams Configuration integration [ec-autoops-ms-configuration-integration] + +To create an incoming webhook on your Microsoft Teams, follow [these instructions](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). + +Save the URL displayed during the creation of the incoming webhook, as you will use it during the AutoOps configuration. + +**AutoOps configuration** + +1. Add a new MS team endpoint using the URL from Microsoft Teams. +2. To receive notifications into Microsoft Teams, you need to add a notification filter. Scroll down the Notification page and click Add. +3. Fill in the filter details. +4. Select events that should be sent to this output. + + +### Webhook integration [ec-autoops-webhook-integration] + +A webhook enables an application to provide other applications with real-time information. A webhook is a user-defined HTTP callback (HTTP POST), which is triggered by specific events. + +**How to add a webhook notification** + +1. Go to **Settings** → **Notifications*** → ***Endpoint settings** and click **Add**. +2. Select Webhook from the drop-dowon list and enter the following details: + + * Name: It must be a unique name for this webhook. + * URL: This is the endpoint to which HTTP POST requests will be sent when events occur. + * Method: POST + * Header: Content-Type, application/Json + +3. Review and update the message as it appears in the body section. AutoOps provides a set of optional fields to use in the message. Read your application documentation for the expected message schema. + + * RESOURCE_ID – Customer Deployment ID + * RESOURCE_NAME – Customer Deployment name + * TITLE – The title of the event. + * DESCRIPTION – The description of the issue that was found. + * SEVERITY – One of the 3 severity levels (High, Medium and Low). + * STATUS – Indicate if the event is currently open or close. + * MESSAGE – The background and impact of the issue + * START_TIME – The time the event was open. + * END_TIME – The time the event was closed. + * ENDPOINT_TYPE – The type of the endpoint (Slack, PagerDuty, Webhook, Opsgenie, VictorOps and MS Teams). + * AFFECTED_NODES – List of node names. + * AFFECTED_INDICES – List of indices names. + * EVENT_LINK – Direct link to the event in AutoOps. + +4. Click Validate to check your settings and click **Save**. +5. Optionally, you can test the webhook integration by using the [webhook.site](https://webhook.site/#!/view/fe9d630e-2f01-44b7-9e41-ef9520fbe9a7). + +::::{note} +When the Endpoint settings have been completed, continue to set up the notification filter to define which events you’d like to be notified about. +:::: + + + +## Notifications report [ec-notification-report] + +From the **Notifications** report, you can check all the notifications sent. The report lists all the events that were set up in the notification filters and provide their status. + +:::{image} ../../../images/cloud-autoops-notifications-report.png +:alt: The Notifications report +::: + +The notification can have one of the following statuses: + +* Notification sent +* Connector not defined +* Notification muted +* Sending notification +* Notification failed to send +* Event closed before notification sent + +The notification status appears also in the event details window. + +:::{image} ../../../images/cloud-autoops-notification-status.png +:alt: Notification status +::: diff --git a/deploy-manage/monitor/autoops/ec-autoops-overview-view.md b/deploy-manage/monitor/autoops/ec-autoops-overview-view.md new file mode 100644 index 000000000..1479e4c1e --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-overview-view.md @@ -0,0 +1,44 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-overview-view.html +--- + +# Overview [ec-autoops-overview-view] + +The **Overview** page displays the current status of customer deployments in Elastic Cloud Hosted that are linked to the same Elastic organization. + +:::{image} ../../../images/cloud-autoops-overview-page.png +:alt: The Overview page +::: + +::::{note} +The **Overview** page displays a complete list of deployments only if AutoOps is available in the specific Cloud Service Provider (CSP) region. +:::: + + +High-level metrics are available, including the most important and currently open events in a single pane. You can view the cluster status, the number of open events in each {{es}} deployments over different periods of time, and navigate to a specific deployment for more details. + + +## Deployments table [ec-autoops-deployment-table] + +The deployment view table lists all active deployments with {{es}} clusters and also deployments for which AutoOps collected the information but are no longer active. AutoOps provides real-time indications on {{es}} status, number of open critical events, number of {{es}} nodes and total number of shards. Select one of the deployments to get a more detailed view of all open and closed events. + + +## {{es}} Info [ec-autoops-es-info] + +This section shows the number of active deployments, the number of nodes, and a summary of used resources, such as total disk size used and total memory connected for all clusters connected. + + +## Top events [ec-autoops-top-events] + +This section provides a quick overview of the top open events in the selected period. You can filter by deployment, severity, name, and search for a specific event across all of the connected deployments. + +The default view lists the top 10 important events across all deployments, sorted by severity. + +The event card indicates when the last event occurred, the number of occurrences across all deployments, the deployments impacted by the event, and it includes a direct link to the event to get additional details. + + +## Events in time period [ec-autoops-events-time-period] + +This time series chart displays all events identified across the connected deployments during the selected period. This allows you to detect which deployment is generating the most events, investigate, and take appropriate actions to resolve any issues. + diff --git a/deploy-manage/monitor/autoops/ec-autoops-regions.md b/deploy-manage/monitor/autoops/ec-autoops-regions.md new file mode 100644 index 000000000..ee1eeecba --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-regions.md @@ -0,0 +1,22 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-regions.html +--- + +# AutoOps regions [ec-autoops-regions] + +A region is the geographic area where the cloud provider’s data center that hosts your deployments is located. Based on a planned release schedule, Elastic is enabling the AutoOps service on the following cloud service providers: AWS, Azure, and GCP. + +AutoOps is currently available in the following regions: + +| Provider | Region | Name | | +| --- | --- | --- | --- | +| AWS | us-east-1 | US East (N. Virginia) | | +| AWS | us-west-2 | Oregon | | +| AWS | eu-west-1 | Ireland | | + +::::{note} +Currently, a limited number of AWS regions are available. More regions for AWS, Azure and GCP will be added in the future. Also, AutoOps is currently not available for GovCloud customers. +:::: + + diff --git a/deploy-manage/monitor/autoops/ec-autoops-shards-view.md b/deploy-manage/monitor/autoops/ec-autoops-shards-view.md new file mode 100644 index 000000000..64b898316 --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-shards-view.md @@ -0,0 +1,33 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-shards-view.html +--- + +# Shards [ec-autoops-shards-view] + +The **Shards** view allows you to manage and monitor shards allocated to each node, ensuring optimal performance and reliability of your search and indexing operations. + +:::{image} ../../../images/cloud-autoops-shard-view.png +:alt: The Shards view +::: + +The **Shards** view provides: + +* Detailed Shard Breakdown: Gain insights into each shard with a granular breakdown. View stats for shards from specific indices on any given node, allowing for in-depth performance and distribution analysis. +* Size Information: Quickly assess the storage footprint of each shard with precise size metrics, facilitating efficient resource management. +* Document Count: Monitor the number of documents contained within each shard to track and manage the shard load effectively. +* Indexing Rate and Latency: Keep an eye on indexing performance with real-time indexing rates and latencies. This ensures efficient and timely data indexing, helping maintain optimal performance. +* Search Rate and Latency: Optimize search functionalities by monitoring search rates and latencies. This ensures your search queries are processed quickly and effectively. + +You can get different views using the sorting fields: + +* Indexing Latency +* Indexing Rate +* Merge Latency +* Merge Rate +* Search Latency +* Search Rate +* Size in Bytes + +Use the slider on the top right side of the metrics table to move forward and backward in time to view how shards data changes. + diff --git a/deploy-manage/monitor/autoops/ec-autoops-template-optimizer.md b/deploy-manage/monitor/autoops/ec-autoops-template-optimizer.md new file mode 100644 index 000000000..75e939acc --- /dev/null +++ b/deploy-manage/monitor/autoops/ec-autoops-template-optimizer.md @@ -0,0 +1,15 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-autoops-template-optimizer.html +--- + +# Template Optimizer [ec-autoops-template-optimizer] + +The **Template Optimizer View** offers detailed recommendations for optimizing templates. + +:::{image} ../../../images/cloud-autoops-template-optimizer.png +:alt: The Template Optimizer view +::: + +When AutoOps identifies a recommended change, it logs the template separately, allowing you to track past impactful changes. You can navigate between different deployments to view all template recommendations. + diff --git a/deploy-manage/monitor/kibana-task-manager-health-monitoring.md b/deploy-manage/monitor/kibana-task-manager-health-monitoring.md new file mode 100644 index 000000000..fde3dcb27 --- /dev/null +++ b/deploy-manage/monitor/kibana-task-manager-health-monitoring.md @@ -0,0 +1,117 @@ +--- +navigation_title: "Health monitoring" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/task-manager-health-monitoring.html +--- + + + +# Kibana task manager health monitoring [task-manager-health-monitoring] + + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +The Task Manager has an internal monitoring mechanism to keep track of a variety of metrics, which can be consumed with either the health monitoring API or the {{kib}} server log. + +The health monitoring API provides a reliable endpoint that can be monitored. Consuming this endpoint doesn’t cause additional load, but rather returns the latest health checks made by the system. This design enables consumption by external monitoring services at a regular cadence without additional load to the system. + +Each {{kib}} instance exposes its own endpoint at: + +```kibana +$ curl -X GET api/task_manager/_health +``` + +Monitoring the `_health` endpoint of each {{kib}} instance in the cluster is the recommended method of ensuring confidence in mission critical services such as Alerting, Actions, and Reporting. + + +## Configuring the monitored health statistics [task-manager-configuring-health-monitoring] + +The health monitoring API monitors the performance of Task Manager out of the box. However, certain performance considerations are deployment specific and you can configure them. + +A health threshold is the threshold for failed task executions. Once a task exceeds this threshold, a status of `warn` or `error` is set on the task type execution. To configure a health threshold, use the [`xpack.task_manager.monitored_task_execution_thresholds`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-health-settings) setting. You can apply this this setting to all task types in the system, or to a custom task type. + +By default, this setting marks the health of every task type as `warning` when it exceeds 80% failed executions, and as `error` at 90%. Set this value to a number between 0 to 100. The threshold is hit when the value **exceeds** this number. To avoid a status of `error`, set the threshold at 100. To hit `error` the moment any task fails, set the threshold to 0. + +Create a custom configuration to set lower thresholds for task types you consider critical, such as alerting tasks that you want to detect sooner in an external monitoring service. + +```yaml +xpack.task_manager.monitored_task_execution_thresholds: + default: <1> + error_threshold: 70 + warn_threshold: 50 + custom: + "alerting:.index-threshold": <2> + error_threshold: 50 + warn_threshold: 0 +``` + +1. A default configuration that sets the system-wide `warn` threshold at a 50% failure rate, and `error` at 70% failure rate. +2. A custom configuration for the `alerting:.index-threshold` task type that sets a system wide `warn` threshold at 0% (which sets a `warn` status the moment any task of that type fails), and `error` at a 50% failure rate. + + + +## Consuming health stats [task-manager-consuming-health-stats] + +The health API is best consumed by via the `/api/task_manager/_health` endpoint. + +Additionally, there are two ways to consume these metrics: + +**Debug logging** + +The metrics are logged in the {{kib}} `DEBUG` logger at a regular cadence. To enable Task Manager debug logging in your {{kib}} instance, add the following to your `kibana.yml`: + +```yaml +logging: + loggers: + - context: plugins.taskManager + appenders: [console] + level: debug +``` + +These stats are logged based on the number of milliseconds set in your [`xpack.task_manager.poll_interval`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting, which could add substantial noise to your logs. Only enable this level of logging temporarily. + +**Automatic logging** + +By default, the health API runs at a regular cadence, and each time it runs, it attempts to self evaluate its performance. If this self evaluation yields a potential problem, a message will log to the {{kib}} server log. In addition, the health API will look at how long tasks have waited to start (from when they were scheduled to start). If this number exceeds a configurable threshold ([`xpack.task_manager.monitored_stats_health_verbose_log.warn_delayed_task_start_in_seconds`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings)), the same message as above will log to the {{kib}} server log. + +This message looks like: + +```log +Detected potential performance issue with Task Manager. Set 'xpack.task_manager.monitored_stats_health_verbose_log.enabled: true' in your Kibana.yml to enable debug logging` +``` + +If this message appears, set [`xpack.task_manager.monitored_stats_health_verbose_log.enabled`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) to `true` in your `kibana.yml`. This will start logging the health metrics at either a `warn` or `error` log level, depending on the detected severity of the potential problem. + + +## Making sense of Task Manager health stats [making-sense-of-task-manager-health-stats] + +The health monitoring API exposes three sections: `configuration`, `workload` and `runtime`: + +| | | +| --- | --- | +| Configuration | This section summarizes the current configuration of Task Manager. This includes dynamic configurations that change over time, such as `poll_interval` and `max_workers`, which can adjust in reaction to changing load on the system. | +| Workload | This section summarizes the work load across the cluster, including the tasks in the system, their types, and current status. | +| Runtime | This section tracks execution performance of Task Manager, tracking task *drift*, worker *load*, and execution stats broken down by type, including duration and execution results. | +| Capacity Estimation | This section provides a rough estimate about the sufficiency of its capacity. As the name suggests, these are estimates based on historical data and should not be used as predictions. Use these estimations when following the Task Manager [Scaling guidance](../distributed-architecture/kibana-tasks-management.md#task-manager-scaling-guidance). | + +Each section has a `timestamp` and a `status` that indicates when the last update to this section took place and whether the health of this section was evaluated as `OK`, `Warning` or `Error`. + +The root `status` indicates the `status` of the system overall. + +The Runtime `status` indicates whether task executions have exceeded any of the [configured health thresholds](#task-manager-configuring-health-monitoring). An `OK` status means none of the threshold have been exceeded. A `Warning` status means that at least one warning threshold has been exceeded. An `Error` status means that at least one error threshold has been exceeded. + +::::{important} +Some tasks (such as [connectors](../manage-connectors.md)) will incorrectly report their status as successful even if the task failed. The runtime and workload block will return data about success and failures and will not take this into consideration. + +To get a better sense of action failures, please refer to the [Event log index](../../explore-analyze/alerts/kibana/event-log-index.md) for more accurate context into failures and successes. + +:::: + + +The Capacity Estimation `status` indicates the sufficiency of the observed capacity. An `OK` status means capacity is sufficient. A `Warning` status means that capacity is sufficient for the scheduled recurring tasks, but non-recurring tasks often cause the cluster to exceed capacity. An `Error` status means that there is insufficient capacity across all types of tasks. + +By monitoring the `status` of the system overall, and the `status` of specific task types of interest, you can evaluate the health of the {{kib}} Task Management system. + diff --git a/deploy-manage/monitor/logging-configuration.md b/deploy-manage/monitor/logging-configuration.md new file mode 100644 index 000000000..6d2a21122 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration.md @@ -0,0 +1,5 @@ +# Logging configuration + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 \ No newline at end of file diff --git a/deploy-manage/monitor/logging-configuration/_cli_configuration.md b/deploy-manage/monitor/logging-configuration/_cli_configuration.md new file mode 100644 index 000000000..f16638fa4 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/_cli_configuration.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/_cli_configuration.html +--- + +# Cli configuration [_cli_configuration] + + +## Logging configuration via CLI [logging-cli-migration] + +As is the case for any of Kibana’s config settings, you can specify your logging configuration via the CLI. For convenience, the `--verbose` and `--silent` flags exist as shortcuts and will continue to be supported beyond v7. + +If you wish to override these flags, you can always do so by passing your preferred logging configuration directly to the CLI. For example, with the following configuration: + +```yaml +logging: + appenders: + custom: + type: console + layout: + type: pattern + pattern: "[%date][%level] %message" + root: + level: warn + appenders: [custom] +``` + +you can override the root logging level with: + +| legacy logging | {{kib}} Platform logging | cli shortcuts | +| --- | --- | --- | +| --verbose | --logging.root.level=debug | --verbose | +| --silent | --logging.root.level=off | --silent | + diff --git a/deploy-manage/monitor/logging-configuration/auditing-search-queries.md b/deploy-manage/monitor/logging-configuration/auditing-search-queries.md new file mode 100644 index 000000000..03aec6569 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/auditing-search-queries.md @@ -0,0 +1,33 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-search-queries.html +--- + +# Auditing search queries [auditing-search-queries] + +There is no [audit event type](elasticsearch-audit-events.md) specifically dedicated to search queries. Search queries are analyzed and then processed; the processing triggers authorization actions that are audited. However, the original raw query, as submitted by the client, is not accessible downstream when authorization auditing occurs. + +Search queries are contained inside HTTP request bodies, however, and some audit events that are generated by the REST layer, on the coordinating node, can be toggled to output the request body to the audit log. Therefore, one must audit request bodies in order to audit search queries. + +To make certain audit events include the request body, edit the following setting in the `elasticsearch.yml` file: + +```yaml +xpack.security.audit.logfile.events.emit_request_body: true +``` + +::::{important} +No filtering is performed when auditing, so sensitive data might be audited in plain text when audit events include the request body. Also, the request body can contain malicious content that can break a parser consuming the audit logs. +:::: + + +The request body is printed as an escaped JSON string value (RFC 4627) to the `request.body` event attribute. + +Not all events contain the `request.body` attribute, even when the above setting is toggled. The ones that do are: `authentication_success`, `authentication_failed`, `realm_authentication_failed`, `tampered_request`, `run_as_denied`, and `anonymous_access_denied`. The `request.body` attribute is printed on the coordinating node only (the node that handles the REST request). Most of these event types are [not included by default](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#xpack-sa-lf-events-include). + +A good practical piece of advice is to add `authentication_success` to the event types that are audited (add it to the list in the `xpack.security.audit.logfile.events.include`), as this event type is not audited by default. + +::::{note} +Typically, the include list contains other event types as well, such as `access_granted` or `access_denied`. +:::: + + diff --git a/deploy-manage/monitor/logging-configuration/correlating-kibana-elasticsearch-audit-logs.md b/deploy-manage/monitor/logging-configuration/correlating-kibana-elasticsearch-audit-logs.md new file mode 100644 index 000000000..4cdc2c8ff --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/correlating-kibana-elasticsearch-audit-logs.md @@ -0,0 +1,404 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/xpack-security-audit-logging.html +--- + +# Correlating Kibana and Elasticsearch audit logs [xpack-security-audit-logging] + +Audit logging is a [subscription feature](https://www.elastic.co/subscriptions) that you can enable to keep track of security-related events, such as authorization success and failures. Logging these events enables you to monitor {{kib}} for suspicious activity and provides evidence in the event of an attack. + +Use the {{kib}} audit logs in conjunction with [{{es}} audit logging](enabling-elasticsearch-audit-logs.md) to get a holistic view of all security related events. {{kib}} defers to the {{es}} security model for authentication, data index authorization, and features that are driven by cluster-wide privileges. For more information on enabling audit logging in {{es}}, refer to [Auditing security events](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing.html). + +::::{note} +Audit logs are **disabled** by default. To enable this functionality, you must set `xpack.security.audit.enabled` to `true` in `kibana.yml`. + +You can optionally configure audit logs location, file/rolling file appenders and ignore filters using [Audit logging settings](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-settings). + +:::: + + +## Audit events [xpack-security-ecs-audit-logging] + +Refer to the table of events that can be logged for auditing purposes. + +Each event is broken down into [category](enabling-kibana-audit-logs.md#field-event-category), [type](enabling-kibana-audit-logs.md#field-event-type), [action](enabling-kibana-audit-logs.md#field-event-action) and [outcome](enabling-kibana-audit-logs.md#field-event-outcome) fields to make it easy to filter, query and aggregate the resulting logs. The [trace.id](enabling-kibana-audit-logs.md#field-trace-id) field can be used to correlate multiple events that originate from the same request. + +Refer to [Audit schema](enabling-kibana-audit-logs.md#xpack-security-ecs-audit-schema) for a table of fields that get logged with audit event. + +::::{note} +To ensure that a record of every operation is persisted even in case of an unexpected error, asynchronous write operations are logged immediately after all authorization checks have passed, but before the response from {{es}} is received. Refer to the corresponding {{es}} logs for potential write errors. + +:::: + + +| | +| --- | +| #### Category: authentication [_category_authentication]


| +| **Action** | **Outcome** | **Description** | +| `user_login` | `success` | User has logged in successfully. | +| `failure` | Failed login attempt (e.g. due to invalid credentials). | +| `user_logout` | `unknown` | User is logging out. | +| `session_cleanup` | `unknown` | Removing invalid or expired session. | +| `access_agreement_acknowledged` | n/a | User has acknowledged the access agreement. | +| #### Category: database [_category_database]

##### Type: creation [_type_creation]



| +| **Action** | **Outcome** | **Description** | +| `saved_object_create` | `unknown` | User is creating a saved object. | +| `failure` | User is not authorized to create a saved object. | +| `saved_object_open_point_in_time` | `unknown` | User is creating a Point In Time to use when querying saved objects. | +| `failure` | User is not authorized to create a Point In Time for the provided saved object types. | +| `connector_create` | `unknown` | User is creating a connector. | +| `failure` | User is not authorized to create a connector. | +| `rule_create` | `unknown` | User is creating a rule. | +| `failure` | User is not authorized to create a rule. | +| `ad_hoc_run_create` | `unknown` | User is creating an ad hoc run. | +| `failure` | User is not authorized to create an ad hoc run. | +| `space_create` | `unknown` | User is creating a space. | +| `failure` | User is not authorized to create a space. | +| `case_create` | `unknown` | User is creating a case. | +| `failure` | User is not authorized to create a case. | +| `case_configuration_create` | `unknown` | User is creating a case configuration. | +| `failure` | User is not authorized to create a case configuration. | +| `case_comment_create` | `unknown` | User is creating a case comment. | +| `failure` | User is not authorized to create a case comment. | +| `case_comment_bulk_create` | `unknown` | User is creating multiple case comments. | +| `failure` | User is not authorized to create multiple case comments. | +| `case_user_action_create_comment` | `success` | User has created a case comment. | +| `case_user_action_create_case` | `success` | User has created a case. | +| `ml_put_ad_job` | `success` | Creating anomaly detection job. | +| `failure` | Failed to create anomaly detection job. | +| `ml_put_ad_datafeed` | `success` | Creating anomaly detection datafeed. | +| `failure` | Failed to create anomaly detection datafeed. | +| `ml_put_calendar` | `success` | Creating calendar. | +| `failure` | Failed to create calendar. | +| `ml_post_calendar_events` | `success` | Adding events to calendar. | +| `failure` | Failed to add events to calendar. | +| `ml_forecast` | `success` | Creating anomaly detection forecast. | +| `failure` | Failed to create anomaly detection forecast. | +| `ml_put_filter` | `success` | Creating filter. | +| `failure` | Failed to create filter. | +| `ml_put_dfa_job` | `success` | Creating data frame analytics job. | +| `failure` | Failed to create data frame analytics job. | +| `ml_put_trained_model` | `success` | Creating trained model. | +| `failure` | Failed to create trained model. | +| `product_documentation_create` | `unknown` | User requested to install the product documentation for use in AI Assistants. | +| `knowledge_base_entry_create` | `success` | User has created knowledge base entry [id=x] | +| `failure` | Failed attempt to create a knowledge base entry | +| `knowledge_base_entry_update` | `success` | User has updated knowledge base entry [id=x] | +| `failure` | Failed attempt to update a knowledge base entry | +| `knowledge_base_entry_delete` | `success` | User has deleted knowledge base entry [id=x] | +| `failure` | Failed attempt to delete a knowledge base entry | +| ##### Type: change [_type_change]


| +| **Action** | **Outcome** | **Description** | +| `saved_object_update` | `unknown` | User is updating a saved object. | +| `failure` | User is not authorized to update a saved object. | +| `saved_object_update_objects_spaces` | `unknown` | User is adding and/or removing a saved object to/from other spaces. | +| `failure` | User is not authorized to add or remove a saved object to or from other spaces. | +| `saved_object_remove_references` | `unknown` | User is removing references to a saved object. | +| `failure` | User is not authorized to remove references to a saved object. | +| `saved_object_collect_multinamespace_references` | `success` | User has accessed references to a multi-space saved object. | +| `failure` | User is not authorized to access references to a multi-space saved object. | +| `connector_update` | `unknown` | User is updating a connector. | +| `failure` | User is not authorized to update a connector. | +| `rule_update` | `unknown` | User is updating a rule. | +| `failure` | User is not authorized to update a rule. | +| `rule_update_api_key` | `unknown` | User is updating the API key of a rule. | +| `failure` | User is not authorized to update the API key of a rule. | +| `rule_enable` | `unknown` | User is enabling a rule. | +| `failure` | User is not authorized to enable a rule. | +| `rule_disable` | `unknown` | User is disabling a rule. | +| `failure` | User is not authorized to disable a rule. | +| `rule_mute` | `unknown` | User is muting a rule. | +| `failure` | User is not authorized to mute a rule. | +| `rule_unmute` | `unknown` | User is unmuting a rule. | +| `failure` | User is not authorized to unmute a rule. | +| `rule_alert_mute` | `unknown` | User is muting an alert. | +| `failure` | User is not authorized to mute an alert. | +| `rule_alert_unmute` | `unknown` | User is unmuting an alert. | +| `failure` | User is not authorized to unmute an alert. | +| `space_update` | `unknown` | User is updating a space. | +| `failure` | User is not authorized to update a space. | +| `alert_update` | `unknown` | User is updating an alert. | +| `failure` | User is not authorized to update an alert. | +| `rule_snooze` | `unknown` | User is snoozing a rule. | +| `failure` | User is not authorized to snooze a rule. | +| `rule_unsnooze` | `unknown` | User is unsnoozing a rule. | +| `failure` | User is not authorized to unsnooze a rule. | +| `case_update` | `unknown` | User is updating a case. | +| `failure` | User is not authorized to update a case. | +| `case_push` | `unknown` | User is pushing a case to an external service. | +| `failure` | User is not authorized to push a case to an external service. | +| `case_configuration_update` | `unknown` | User is updating a case configuration. | +| `failure` | User is not authorized to update a case configuration. | +| `case_comment_update` | `unknown` | User is updating a case comment. | +| `failure` | User is not authorized to update a case comment. | +| `case_user_action_add_case_assignees` | `success` | User has added a case assignee. | +| `case_user_action_update_case_connector` | `success` | User has updated a case connector. | +| `case_user_action_update_case_description` | `success` | User has updated a case description. | +| `case_user_action_update_case_settings` | `success` | User has updated the case settings. | +| `case_user_action_update_case_severity` | `success` | User has updated the case severity. | +| `case_user_action_update_case_status` | `success` | User has updated the case status. | +| `case_user_action_pushed_case` | `success` | User has pushed a case to an external service. | +| `case_user_action_add_case_tags` | `success` | User has added tags to a case. | +| `case_user_action_update_case_title` | `success` | User has updated the case title. | +| `ml_open_ad_job` | `success` | Opening anomaly detection job. | +| `failure` | Failed to open anomaly detection job. | +| `ml_close_ad_job` | `success` | Closing anomaly detection job. | +| `failure` | Failed to close anomaly detection job. | +| `ml_start_ad_datafeed` | `success` | Starting anomaly detection datafeed. | +| `failure` | Failed to start anomaly detection datafeed. | +| `ml_stop_ad_datafeed` | `success` | Stopping anomaly detection datafeed. | +| `failure` | Failed to stop anomaly detection datafeed. | +| `ml_update_ad_job` | `success` | Updating anomaly detection job. | +| `failure` | Failed to update anomaly detection job. | +| `ml_reset_ad_job` | `success` | Resetting anomaly detection job. | +| `failure` | Failed to reset anomaly detection job. | +| `ml_revert_ad_snapshot` | `success` | Reverting anomaly detection snapshot. | +| `failure` | Failed to revert anomaly detection snapshot. | +| `ml_update_ad_datafeed` | `success` | Updating anomaly detection datafeed. | +| `failure` | Failed to update anomaly detection datafeed. | +| `ml_put_calendar_job` | `success` | Adding job to calendar. | +| `failure` | Failed to add job to calendar. | +| `ml_delete_calendar_job` | `success` | Removing job from calendar. | +| `failure` | Failed to remove job from calendar. | +| `ml_update_filter` | `success` | Updating filter. | +| `failure` | Failed to update filter. | +| `ml_start_dfa_job` | `success` | Starting data frame analytics job. | +| `failure` | Failed to start data frame analytics job. | +| `ml_stop_dfa_job` | `success` | Stopping data frame analytics job. | +| `failure` | Failed to stop data frame analytics job. | +| `ml_update_dfa_job` | `success` | Updating data frame analytics job. | +| `failure` | Failed to update data frame analytics job. | +| `ml_start_trained_model_deployment` | `success` | Starting trained model deployment. | +| `failure` | Failed to start trained model deployment. | +| `ml_stop_trained_model_deployment` | `success` | Stopping trained model deployment. | +| `failure` | Failed to stop trained model deployment. | +| `ml_update_trained_model_deployment` | `success` | Updating trained model deployment. | +| `failure` | Failed to update trained model deployment. | +| `product_documentation_update` | `unknown` | User requested to update the product documentation for use in AI Assistants. | +| ##### Type: deletion [_type_deletion]


| +| **Action** | **Outcome** | **Description** | +| `saved_object_delete` | `unknown` | User is deleting a saved object. | +| `failure` | User is not authorized to delete a saved object. | +| `saved_object_close_point_in_time` | `unknown` | User is deleting a Point In Time that was used to query saved objects. | +| `failure` | User is not authorized to delete a Point In Time. | +| `connector_delete` | `unknown` | User is deleting a connector. | +| `failure` | User is not authorized to delete a connector. | +| `rule_delete` | `unknown` | User is deleting a rule. | +| `failure` | User is not authorized to delete a rule. | +| `ad_hoc_run_delete` | `unknown` | User is deleting an ad hoc run. | +| `failure` | User is not authorized to delete an ad hoc run. | +| `space_delete` | `unknown` | User is deleting a space. | +| `failure` | User is not authorized to delete a space. | +| `case_delete` | `unknown` | User is deleting a case. | +| `failure` | User is not authorized to delete a case. | +| `case_comment_delete_all` | `unknown` | User is deleting all comments associated with a case. | +| `failure` | User is not authorized to delete all comments associated with a case. | +| `case_comment_delete` | `unknown` | User is deleting a case comment. | +| `failure` | User is not authorized to delete a case comment. | +| `case_user_action_delete_case_assignees` | `success` | User has removed a case assignee. | +| `case_user_action_delete_comment` | `success` | User has deleted a case comment. | +| `case_user_action_delete_case` | `success` | User has deleted a case. | +| `case_user_action_delete_case_tags` | `success` | User has removed tags from a case. | +| `ml_delete_ad_job` | `success` | Deleting anomaly detection job. | +| `failure` | Failed to delete anomaly detection job. | +| `ml_delete_model_snapshot` | `success` | Deleting model snapshot. | +| `failure` | Failed to delete model snapshot. | +| `ml_delete_ad_datafeed` | `success` | Deleting anomaly detection datafeed. | +| `failure` | Failed to delete anomaly detection datafeed. | +| `ml_delete_calendar` | `success` | Deleting calendar. | +| `failure` | Failed to delete calendar. | +| `ml_delete_calendar_event` | `success` | Deleting calendar event. | +| `failure` | Failed to delete calendar event. | +| `ml_delete_filter` | `success` | Deleting filter. | +| `failure` | Failed to delete filter. | +| `ml_delete_forecast` | `success` | Deleting forecast. | +| `failure` | Failed to delete forecast. | +| `ml_delete_dfa_job` | `success` | Deleting data frame analytics job. | +| `failure` | Failed to delete data frame analytics job. | +| `ml_delete_trained_model` | `success` | Deleting trained model. | +| `failure` | Failed to delete trained model. | +| `product_documentation_delete` | `unknown` | User requested to delete the product documentation for use in AI Assistants. | +| ##### Type: access [_type_access]


| +| **Action** | **Outcome** | **Description** | +| `saved_object_get` | `success` | User has accessed a saved object. | +| `failure` | User is not authorized to access a saved object. | +| `saved_object_resolve` | `success` | User has accessed a saved object. | +| `failure` | User is not authorized to access a saved object. | +| `saved_object_find` | `success` | User has accessed a saved object as part of a search operation. | +| `failure` | User is not authorized to search for saved objects. | +| `connector_get` | `success` | User has accessed a connector. | +| `failure` | User is not authorized to access a connector. | +| `connector_find` | `success` | User has accessed a connector as part of a search operation. | +| `failure` | User is not authorized to search for connectors. | +| `rule_get` | `success` | User has accessed a rule. | +| `failure` | User is not authorized to access a rule. | +| `rule_get_execution_log` | `success` | User has accessed execution log for a rule. | +| `failure` | User is not authorized to access execution log for a rule. | +| `rule_find` | `success` | User has accessed a rule as part of a search operation. | +| `failure` | User is not authorized to search for rules. | +| `rule_schedule_backfill` | `success` | User has accessed a rule as part of a backfill schedule operation. | +| `failure` | User is not authorized to access rule for backfill scheduling. | +| `ad_hoc_run_get` | `success` | User has accessed an ad hoc run. | +| `failure` | User is not authorized to access ad hoc run. | +| `ad_hoc_run_find` | `success` | User has accessed an ad hoc run as part of a search operation. | +| `failure` | User is not authorized to search for ad hoc runs. | +| `space_get` | `success` | User has accessed a space. | +| `failure` | User is not authorized to access a space. | +| `space_find` | `success` | User has accessed a space as part of a search operation. | +| `failure` | User is not authorized to search for spaces. | +| `alert_get` | `success` | User has accessed an alert. | +| `failure` | User is not authorized to access an alert. | +| `alert_find` | `success` | User has accessed an alert as part of a search operation. | +| `failure` | User is not authorized to access alerts. | +| `case_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_bulk_get` | `success` | User has accessed multiple cases. | +| `failure` | User is not authorized to access multiple cases. | +| `case_resolve` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_find` | `success` | User has accessed a case as part of a search operation. | +| `failure` | User is not authorized to search for cases. | +| `case_ids_by_alert_id_get` | `success` | User has accessed cases. | +| `failure` | User is not authorized to access cases. | +| `case_get_metrics` | `success` | User has accessed metrics for a case. | +| `failure` | User is not authorized to access metrics for a case. | +| `cases_get_metrics` | `success` | User has accessed metrics for cases. | +| `failure` | User is not authorized to access metrics for cases. | +| `case_configuration_find` | `success` | User has accessed a case configuration as part of a search operation. | +| `failure` | User is not authorized to search for case configurations. | +| `case_comment_get_metrics` | `success` | User has accessed metrics for case comments. | +| `failure` | User is not authorized to access metrics for case comments. | +| `case_comment_alerts_attach_to_case` | `success` | User has accessed case alerts. | +| `failure` | User is not authorized to access case alerts. | +| `case_comment_get` | `success` | User has accessed a case comment. | +| `failure` | User is not authorized to access a case comment. | +| `case_comment_bulk_get` | `success` | User has accessed multiple case comments. | +| `failure` | User is not authorized to access multiple case comments. | +| `case_comment_get_all` | `success` | User has accessed case comments. | +| `failure` | User is not authorized to access case comments. | +| `case_comment_find` | `success` | User has accessed a case comment as part of a search operation. | +| `failure` | User is not authorized to search for case comments. | +| `case_categories_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_tags_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_reporters_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_find_statuses` | `success` | User has accessed a case as part of a search operation. | +| `failure` | User is not authorized to search for cases. | +| `case_user_actions_get` | `success` | User has accessed the user activity of a case. | +| `failure` | User is not authorized to access the user activity of a case. | +| `case_user_actions_find` | `success` | User has accessed the user activity of a case as part of a search operation. | +| `failure` | User is not authorized to access the user activity of a case. | +| `case_user_action_get_metrics` | `success` | User has accessed metrics for the user activity of a case. | +| `failure` | User is not authorized to access metrics for the user activity of a case. | +| `case_user_action_get_users` | `success` | User has accessed the users associated with a case. | +| `failure` | User is not authorized to access the users associated with a case. | +| `case_connectors_get` | `success` | User has accessed the connectors of a case. | +| `failure` | User is not authorized to access the connectors of a case. | +| `ml_infer_trained_model` | `success` | Inferring using trained model. | +| `failure` | Failed to infer using trained model. | +| #### Category: web [_category_web]


| +| **Action** | **Outcome** | **Description** | +| `http_request` | `unknown` | User is making an HTTP request. | + + +## Audit schema [xpack-security-ecs-audit-schema] + +Audit logs are written in JSON using [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/1.6/index.html) specification. + +| | +| --- | +| #### Base Fields [_base_fields]


| +| **Field** | **Description** | +| `@timestamp` | Time when the event was generated.
Example: `2016-05-23T08:05:34.853Z` | +| `message` | Human readable description of the event. | +| #### Event Fields [_event_fields]


| +| **Field** | **Description** | +| $$$field-event-action$$$ `event.action` | The action captured by the event.
Refer to [Audit events](enabling-kibana-audit-logs.md#xpack-security-ecs-audit-logging) for a table of possible actions. | +| $$$field-event-category$$$ `event.category` | High level category associated with the event.
This field is closely related to `event.type`, which is used as a subcategory.
Possible values:`database`,`web`,`authentication` | +| $$$field-event-type$$$ `event.type` | Subcategory associated with the event.
This field can be used along with the `event.category` field to enable filtering events down to a level appropriate for single visualization.
Possible values:`creation`,`access`,`change`,`deletion` | +| $$$field-event-outcome$$$ `event.outcome` | Denotes whether the event represents a success or failure:

* Any actions that the user is not authorized to perform are logged with outcome: `failure`
* Authorized read operations are only logged after successfully fetching the data from {{es}} with outcome: `success`
* Authorized create, update, or delete operations are logged before attempting the operation in {{es}} with outcome: `unknown`

Possible values: `success`, `failure`, `unknown`
| +| #### User Fields [_user_fields]


| +| **Field** | **Description** | +| `user.id` | Unique identifier of the user across sessions (See [user profiles](../../users-roles/cluster-or-deployment-auth/user-profiles.md)). | +| `user.name` | Login name of the user.
Example: `jdoe` | +| `user.roles[]` | Set of user roles at the time of the event.
Example: `[kibana_admin, reporting_user]` | +| #### Kibana Fields [_kibana_fields]


| +| **Field** | **Description** | +| `kibana.space_id` | ID of the space associated with the event.
Example: `default` | +| `kibana.session_id` | ID of the user session associated with the event.
Each login attempt results in a unique session id. | +| `kibana.saved_object.type` | Type of saved object associated with the event.
Example: `dashboard` | +| `kibana.saved_object.id` | ID of the saved object associated with the event. | +| `kibana.authentication_provider` | Name of the authentication provider associated with the event.
Example: `my-saml-provider` | +| `kibana.authentication_type` | Type of the authentication provider associated with the event.
Example: `saml` | +| `kibana.authentication_realm` | Name of the Elasticsearch realm that has authenticated the user.
Example: `native` | +| `kibana.lookup_realm` | Name of the Elasticsearch realm where the user details were retrieved from.
Example: `native` | +| `kibana.add_to_spaces[]` | Set of space IDs that a saved object is being shared to as part of the event.
Example: `[default, marketing]` | +| `kibana.delete_from_spaces[]` | Set of space IDs that a saved object is being removed from as part of the event.
Example: `[marketing]` | +| #### Error Fields [_error_fields]


| +| **Field** | **Description** | +| `error.code` | Error code describing the error. | +| `error.message` | Error message. | +| #### HTTP and URL Fields [_http_and_url_fields]


| +| **Field** | **Description** | +| `client.ip` | Client IP address. | +| `http.request.method` | HTTP request method.
Example: `get`, `post`, `put`, `delete` | +| `http.request.headers.x-forwarded-for` | `X-Forwarded-For` request header used to identify the originating client IP address when connecting through proxy servers.
Example: `161.66.20.177, 236.198.214.101` | +| `url.domain` | Domain of the URL.
Example: `www.elastic.co` | +| `url.path` | Path of the request.
Example: `/search` | +| `url.port` | Port of the request.
Example: `443` | +| `url.query` | The query field describes the query string of the request.
Example: `q=elasticsearch` | +| `url.scheme` | Scheme of the request.
Example: `https` | +| #### Tracing Fields [_tracing_fields]


| +| **Field** | **Description** | +| $$$field-trace-id$$$ `trace.id` | Unique identifier allowing events of the same transaction from {{kib}} and {{es}} to be correlated. | + + +## Correlating audit events [xpack-security-ecs-audit-correlation] + +Audit events can be correlated in two ways: + +1. Multiple {{kib}} audit events that resulted from the same request can be correlated together. +2. If [{{es}} audit logging](enabling-elasticsearch-audit-logs.md) is enabled, {{kib}} audit events from one request can be correlated with backend calls that create {{es}} audit events. + +::::{note} +The examples below are simplified, many fields have been omitted and values have been shortened for clarity. +:::: + + +### Example 1: correlating multiple {{kib}} audit events [_example_1_correlating_multiple_kib_audit_events] + +When "thom" creates a new alerting rule, five audit events are written: + +```json +{"event":{"action":"http_request","category":["web"],"outcome":"unknown"},"http":{"request":{"method":"post"}},"url":{"domain":"localhost","path":"/api/alerting/rule","port":5601,"scheme":"https"},"user":{"name":"thom","roles":["superuser"]},"kibana":{"space_id":"default","session_id":"3dHCZRB..."},"@timestamp":"2022-01-25T13:05:34.449-05:00","message":"User is requesting [/api/alerting/rule] endpoint","trace":{"id":"e300e06..."}} +{"event":{"action":"space_get","category":["database"],"type":["access"],"outcome":"success"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"space","id":"default"}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.454-05:00","message":"User has accessed space [id=default]","trace":{"id":"e300e06..."}} +{"event":{"action":"connector_get","category":["database"],"type":["access"],"outcome":"success"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"action","id":"5e3b1ae..."}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.948-05:00","message":"User has accessed connector [id=5e3b1ae...]","trace":{"id":"e300e06..."}} +{"event":{"action":"connector_get","category":["database"],"type":["access"],"outcome":"success"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"action","id":"5e3b1ae..."}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.956-05:00","message":"User has accessed connector [id=5e3b1ae...]","trace":{"id":"e300e06..."}} +{"event":{"action":"rule_create","category":["database"],"type":["creation"],"outcome":"unknown"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"alert","id":"64517c3..."}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.956-05:00","message":"User is creating rule [id=64517c3...]","trace":{"id":"e300e06..."}} +``` + +All of these audit events can be correlated together by the same `trace.id` value `"e300e06..."`. The first event is the HTTP API call, the next audit events are checks to validate the space and the connectors, and the last audit event is the actual rule creation. + + +### Example 2: correlating a {{kib}} audit event with {{es}} audit events [_example_2_correlating_a_kib_audit_event_with_es_audit_events] + +When "thom" logs in, a "user_login" {{kib}} audit event is written: + +```json +{"event":{"action":"user_login","category":["authentication"],"outcome":"success"},"kibana":{"session_id":"ab93zdA..."},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T09:40:39.267-05:00","message":"User [thom] has logged in using basic provider [name=basic]","trace":{"id":"818cbf3..."}} +``` + +The `trace.id` value `"818cbf3..."` in the {{kib}} audit event can be correlated with the `opaque_id` value in these six {{es}} audit events: + +```json +{"type":"audit", "timestamp":"2022-01-25T09:40:38,604-0500", "event.action":"access_granted", "user.name":"thom", "user.roles":["superuser"], "request.id":"YCx8wxs...", "action":"cluster:admin/xpack/security/user/authenticate", "request.name":"AuthenticateRequest", "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/index", "request.name":"IndexRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/bulk", "request.name":"BulkRequest", "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/bulk[s]", "request.name":"BulkShardRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/index:op_type/create", "request.name":"BulkItemRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/bulk[s][p]", "request.name":"BulkShardRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +``` + +The {{es}} audit events show that "thom" authenticated, then subsequently "kibana_system" created a session for that user. diff --git a/deploy-manage/monitor/logging-configuration/elasticsearch-audit-events.md b/deploy-manage/monitor/logging-configuration/elasticsearch-audit-events.md new file mode 100644 index 000000000..1e4da56ad --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/elasticsearch-audit-events.md @@ -0,0 +1,893 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/audit-event-types.html +--- + +# Elasticsearch audit events [audit-event-types] + +When you are [auditing security events](enabling-elasticsearch-audit-logs.md), a single client request might generate multiple audit events, across multiple cluster nodes. The common `request.id` attribute can be used to correlate the associated events. + +Use the [`xpack.security.audit.logfile.events.include`](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#xpack-sa-lf-events-include) setting in `elasticsearch.yml` to specify the kind of events you want to include in the auditing output. + +::::{note} +Certain audit events require the `security_config_change` event type to audit the related event action. The description of impacted audit events indicate whether that event type is required. +:::: + + +$$$event-access-denied$$$ + +`access_denied` +: Logged when an authenticated user attempts to execute an action they do not have the necessary [privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to perform. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:30:06,949+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"transport", "event.action": + "access_denied", "authentication.type":"REALM", "user.name":"user1", + "user.realm":"default_native", "user.roles":["test_role"], "origin.type": + "rest", "origin.address":"[::1]:52434", "request.id":"yKOgWn2CRQCKYgZRz3phJw", + "action":"indices:admin/auto_create", "request.name":"CreateIndexRequest", + "indices":[""]} + ``` + + :::: + + +$$$event-access-granted$$$ + +`access_granted` +: Logged when an authenticated user attempts to execute an action they have the necessary privilege to perform. These events will be logged only for non-system users. + + If you want to include `access_granted` events for all users (including internal users such as `_xpack`), add [`system_access_granted`](#event-system-granted) to the list of event types in addition to `access_granted`. The `system_access_granted` privilege is not included by default to avoid cluttering the logs. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:30:06,947+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"transport", "event.action": + "access_granted", "authentication.type":"REALM", "user.name":"user1", "user + realm":"default_native", "user.roles":["test_role"], "origin.type":"rest", + "origin.address":"[::1]:52434", "request.id":"yKOgWn2CRQCKYgZRz3phJw", + "action":"indices:data/write/bulk", "request.name":"BulkRequest"} + ``` + + :::: + + +$$$event-anonymous-access-denied$$$ + +`anonymous_access_denied` +: Logged when a request is denied due to missing authentication credentials. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T21:56:43,608+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"rest", "event.action": + "anonymous_access_denied", "origin.type":"rest", "origin.address": + "[::1]:50543", "url.path":"/twitter/_async_search", "url.query":"pretty", + "request.method":"POST", "request.id":"TqA9OisyQ8WTl1ivJUV1AA"} + ``` + + :::: + + +$$$event-authentication-failed$$$ + +`authentication_failed` +: Logged when the authentication credentials cannot be matched to a known user. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:10:15,510+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"rest", "event.action": + "authentication_failed", "user.name":"elastic", "origin.type":"rest", + "origin.address":"[::1]:51504", "url.path":"/_security/user/user1", + "url.query":"pretty", "request.method":"POST", + "request.id":"POv8p_qeTl2tb5xoFl0HIg"} + ``` + + :::: + + +$$$event-authentication-success$$$ + +`authentication_success` +: Logged when a user successfully authenticates. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:03:35,018+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"rest", "event.action": + "authentication_success", "authentication.type":"REALM", "user.name": + "elastic", "user.realm":"reserved", "origin.type":"rest", "origin.address": + "[::1]:51014", "realm":"reserved", "url.path":"/twitter/_search", + "url.query":"pretty", "request.method":"POST", + "request.id":"nHV3UMOoSiu-TaSPWCfxGg"} + ``` + + :::: + + +$$$event-change-disable-user$$$ + +`change_disable_user` +: Logged when the [enable user API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user.html) is invoked to disable a native or a built-in user. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T23:17:28,308+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"change_disable_user", "request.id":"qvLIgw_eTvyK3cgV-GaLVg", + "change":{"disable":{"user":{"name":"user1"}}}} + ``` + + :::: + + +$$$event-change-enable-user$$$ + +`change_enable_user` +: Logged when the [enable user API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user.html) is invoked to enable a native or a built-in user. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T23:17:34,843+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"change_enable_user", "request.id":"BO3QU3qeTb-Ei0G0rUOalQ", + "change":{"enable":{"user":{"name":"user1"}}}} + ``` + + :::: + + +$$$event-change-password$$$ + +`change_password` +: Logged when the [change password API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-change-password.html) is invoked to change the password of a native or built-in user. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2019-12-30T22:19:41,345+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"change_password", "request.id":"bz5a1Cc3RrebDMitMGGNCw", + "change":{"password":{"user":{"name":"user1"}}}} + ``` + + :::: + + +$$$event-create-service-token$$$ + +`create_service_token` +: Logged when the [create service account token API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html) is invoked to create a new index-based token for a service account. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2021-04-30T23:17:42,952+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"create_service_token", "request.id":"az9a1Db5QrebDMacQ8yGKc", + "create":{"service_token":{"namespace":"elastic","service":"fleet-server","name":"token1"}}}` + ``` + + :::: + + +$$$event-connection-denied$$$ + +`connection_denied` +: Logged when an incoming TCP connection does not pass the [IP filter](../../security/ip-traffic-filtering.md) for a specific profile. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T21:47:31,526+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"ip_filter", "event.action": + "connection_denied", "origin.type":"rest", "origin.address":"10.10.0.20:52314", + "transport.profile":".http", "rule":"deny 10.10.0.0/16"} + ``` + + :::: + + +$$$event-connection-granted$$$ + +`connection_granted` +: Logged when an incoming TCP connection passes the [IP filter](../../security/ip-traffic-filtering.md) for a specific profile. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T21:47:31,526+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"ip_filter", "event.action": + "connection_granted", "origin.type":"rest", "origin.address":"[::1]:52314", + "transport.profile":".http", "rule":"allow ::1,127.0.0.1"} + ``` + + :::: + + +$$$event-create-apikey$$$ + +`create_apikey` +: Logged when the [create API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) or the [grant API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-grant-api-key.html) APIs are invoked to create a new API key. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:33:52,521+0200", "node.id": + "9clhpgjJRR-iKzOw20xBNQ", "event.type":"security_config_change", "event.action": + "create_apikey", "request.id":"9FteCmovTzWHVI-9Gpa_vQ", "create":{"apikey": + {"name":"test-api-key-1","expiration":"10d","role_descriptors":[{"cluster": + ["monitor","manage_ilm"],"indices":[{"names":["index-a*"],"privileges": + ["read","maintenance"]},{"names":["in*","alias*"],"privileges":["read"], + "field_security":{"grant":["field1*","@timestamp"],"except":["field11"]}}], + "applications":[],"run_as":[]},{"cluster":["all"],"indices":[{"names": + ["index-b*"],"privileges":["all"]}],"applications":[],"run_as":[]}], + "metadata":{"application":"my-application","environment":{"level": 1, + "tags":["dev","staging"]}}}}} + ``` + + :::: + + +$$$event-change-apikey$$$ + +`change_apikey` +: Logged when the [update API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-api-key.html) API is invoked to update the attributes of an existing API key. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:33:52,521+0200", "node.id": + "9clhpgjJRR-iKzOw20xBNQ", "event.type":"security_config_change", "event.action": + "change_apikey", "request.id":"9FteCmovTzWHVI-9Gpa_vQ", "change":{"apikey": + {"id":"zcwN3YEBBmnjw-K-hW5_","role_descriptors":[{"cluster": + ["monitor","manage_ilm"],"indices":[{"names":["index-a*"],"privileges": + ["read","maintenance"]},{"names":["in*","alias*"],"privileges":["read"], + "field_security":{"grant":["field1*","@timestamp"],"except":["field11"]}}], + "applications":[],"run_as":[]},{"cluster":["all"],"indices":[{"names": + ["index-b*"],"privileges":["all"]}],"applications":[],"run_as":[]}], + "metadata":{"application":"my-application","environment":{"level": 1, + "tags":["dev","staging"]}},"expiration":"10d"}}} + ``` + + :::: + + +$$$event-change-apikeys$$$ + +`change_apikeys` +: Logged when the [bulk update API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-bulk-update-api-keys.html) API is invoked to update the attributes of multiple existing API keys. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit","timestamp":"2020-12-31T00:33:52,521+0200","node.id": + "9clhpgjJRR-iKzOw20xBNQ","event.type":"security_config_change", + "event.action":"change_apikeys","request.id":"9FteCmovTzWHVI-9Gpa_vQ", + "change":{"apikeys": + {"ids":["zcwN3YEBBmnjw-K-hW5_","j7c0WYIBqecB5CbVR6Oq"],"role_descriptors": + [{"cluster":["monitor","manage_ilm"],"indices":[{"names":["index-a*"],"privileges": + ["read","maintenance"]},{"names":["in*","alias*"],"privileges":["read"], + "field_security":{"grant":["field1*","@timestamp"],"except":["field11"]}}], + "applications":[],"run_as":[]},{"cluster":["all"],"indices":[{"names": + ["index-b*"],"privileges":["all"]}],"applications":[],"run_as":[]}], + "metadata":{"application":"my-application","environment":{"level":1, + "tags":["dev","staging"]}},"expiration":"10d"}}} + ``` + + :::: + + +$$$event-delete-privileges$$$ + +`delete_privileges` +: Logged when the [delete application privileges API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-privilege.html) is invoked to remove one or more application privileges. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:39:30,246+0200", "node.id": + "9clhpgjJRR-iKzOw20xBNQ", "event.type":"security_config_change", "event. + action":"delete_privileges", "request.id":"7wRWVxxqTzCKEspeSP7J8g", + "delete":{"privileges":{"application":"myapp","privileges":["read"]}}} + ``` + + :::: + + +$$$event-delete-role$$$ + +`delete_role` +: Logged when the [delete role API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role.html) is invoked to delete a role. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:08:11,678+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event.action": + "delete_role", "request.id":"155IKq3zQdWq-12dgKZRnw", + "delete":{"role":{"name":"my_admin_role"}}} + ``` + + :::: + + +$$$event-delete-role-mapping$$$ + +`delete_role_mapping` +: Logged when the [delete role mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role-mapping.html) is invoked to delete a role mapping. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:12:09,349+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"delete_role_mapping", "request.id":"Stim-DuoSTCWom0S_xhf8g", + "delete":{"role_mapping":{"name":"mapping1"}}} + ``` + + :::: + + +$$$event-delete-service-token$$$ + +`delete_service_token` +: Logged when the [delete service account token API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-service-token.html) is invoked to delete an index-based token for a service account. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2021-04-30T23:17:42,952+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"delete_service_token", "request.id":"az9a1Db5QrebDMacQ8yGKc", + "delete":{"service_token":{"namespace":"elastic","service":"fleet-server","name":"token1"}}} + ``` + + :::: + + +$$$event-delete-user$$$ + +`delete_user` +: Logged when the [delete user API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-user.html) is invoked to delete a specific native user. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:19:41,345+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", + "event.action":"delete_user", "request.id":"au5a1Cc3RrebDMitMGGNCw", + "delete":{"user":{"name":"jacknich"}}} + ``` + + :::: + + +$$$event-invalidate-apikeys$$$ + +`invalidate_apikeys` +: Logged when the [invalidate API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html) is invoked to invalidate one or more API keys. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:36:30,247+0200", "node.id": + "9clhpgjJRR-iKzOw20xBNQ", "event.type":"security_config_change", "event. + action":"invalidate_apikeys", "request.id":"7lyIQU9QTFqSrTxD0CqnTQ", + "invalidate":{"apikeys":{"owned_by_authenticated_user":false, + "user":{"name":"myuser","realm":"native1"}}}} + ``` + + :::: + + +$$$event-put-privileges$$$ + +`put_privileges` +: Logged when the [create or update privileges API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-privileges.html) is invoked to add or update one or more application privileges. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:39:07,779+0200", "node.id": + "9clhpgjJRR-iKzOw20xBNQ", "event.type":"security_config_change", + "event.action":"put_privileges", "request.id":"1X2VVtNgRYO7FmE0nR_BGA", + "put":{"privileges":[{"application":"myapp","name":"read","actions": + ["data:read/*","action:login"],"metadata":{"description":"Read access to myapp"}}]}} + ``` + + :::: + + +$$$event-put-role$$$ + +`put_role` +: Logged when the [create or update role API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html) is invoked to create or update a role. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:27:01,978+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", + "event.action":"put_role", "request.id":"tDYQhv5CRMWM4Sc5Zkk2cQ", + "put":{"role":{"name":"test_role","role_descriptor":{"cluster":["all"], + "indices":[{"names":["apm*"],"privileges":["all"],"field_security": + {"grant":["granted"]},"query":"{\"term\": {\"service.name\": \"bar\"}}"}, + {"names":["apm-all*"],"privileges":["all"],"query":"{\"term\": + {\"service.name\": \"bar2\"}}"}],"applications":[],"run_as":[]}}}} + ``` + + :::: + + +$$$event-put-role-mapping$$$ + +`put_role_mapping` +: Logged when the [create or update role mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html) is invoked to create or update a role mapping. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-31T00:11:13,932+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", "event. + action":"put_role_mapping", "request.id":"kg4h1l_kTDegnLC-0A-XxA", + "put":{"role_mapping":{"name":"mapping1","roles":["user"],"rules": + {"field":{"username":"*"}},"enabled":true,"metadata":{"version":1}}}} + ``` + + :::: + + +$$$event-put-user$$$ + +`put_user` +: Logged when the [create or update user API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html) is invoked to create or update a native user. Note that user updates can also change the user’s password. + + You must include the `security_config_change` event type to audit the related event action. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:10:09,749+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"security_config_change", + "event.action":"put_user", "request.id":"VIiSvhp4Riim_tpkQCVSQA", + "put":{"user":{"name":"user1","enabled":false,"roles":["admin","other_role1"], + "full_name":"Jack Sparrow","email":"jack@blackpearl.com", + "has_password":true,"metadata":{"cunning":10}}}} + ``` + + :::: + + +$$$event-realm-auth-failed$$$ + +`realm_authentication_failed` +: Logged for every realm that fails to present a valid authentication token. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:10:15,510+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"rest", "event.action": + "realm_authentication_failed", "user.name":"elastic", "origin.type":"rest", + "origin.address":"[::1]:51504", "realm":"myTestRealm1", "url.path": + "/_security/user/user1", "url.query":"pretty", "request.method":"POST", + "request.id":"POv8p_qeTl2tb5xoFl0HIg"} + ``` + + :::: + + +$$$event-runas-denied$$$ + +`run_as_denied` +: Logged when an authenticated user attempts to [run as](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) another user that they do not have the necessary [privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to do so. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:49:34,859+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"transport", "event.action": + "run_as_denied", "user.name":"user1", "user.run_as.name":"user1", + "user.realm":"default_native", "user.run_as.realm":"default_native", + "user.roles":["test_role"], "origin.type":"rest", "origin.address": + "[::1]:52662", "request.id":"RcaSt872RG-R_WJBEGfYXA", + "action":"indices:data/read/search", "request.name":"SearchRequest", "indices":["alias1"]} + ``` + + :::: + + +$$$event-runas-granted$$$ + +`run_as_granted` +: Logged when an authenticated user attempts to [run as](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) another user that they have the necessary privileges to do so. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2020-12-30T22:44:42,068+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type":"transport", "event.action": + "run_as_granted", "user.name":"elastic", "user.run_as.name":"user1", + "user.realm":"reserved", "user.run_as.realm":"default_native", + "user.roles":["superuser"], "origin.type":"rest", "origin.address": + "[::1]:52623", "request.id":"dGqPTdEQSX2TAPS3cvc1qA", "action": + "indices:data/read/search", "request.name":"SearchRequest", "indices":["alias1"]} + ``` + + :::: + + +$$$event-system-granted$$$ + +`system_access_granted` +: Logs [`access_granted`](#event-access-granted) events only for [internal users](../../users-roles/cluster-or-deployment-auth/internal-users.md), such as `_xpack`. If you include this setting in addition to `access_granted`, then `access_granted` events are logged for *all* users. + + ::::{note} + This event type is disabled by default to avoid cluttering the logs. + :::: + + +$$$event-tampered-request$$$ + +`tampered_request` +: Logged when the {{security-features}} detect that the request has been tampered with. Typically relates to `search/scroll` requests when the scroll ID is believed to have been tampered with. + + ::::{dropdown} Example + ```js + {"type":"audit", "timestamp":"2019-11-27T22:00:00,947+0200", "node.id": + "0RMNyghkQYCc_gVd1G6tZQ", "event.type": "rest", "event.action": + "tampered_request", "origin.address":"[::1]:50543", "url.path": + "/twitter/_async_search", "url.query":"pretty", "request.method":"POST", + "request.id":"TqA9OisyQ8WTl1ivJUV1AA"} + ``` + + :::: + + + +## Audit event attributes [audit-event-attributes] + +The audit events are formatted as JSON documents, and each event is printed on a separate line in the audit log. The entries themselves do not contain an end-of-line delimiter. For more details, see [Log entry format](logfile-audit-output.md#audit-log-entry-format). + +The following list shows attributes that are common to all audit event types: + +`@timestamp` +: The time, in ISO9601 format, when the event occurred. + +`node.name` +: The name of the node. This can be changed in the `elasticsearch.yml` config file. + +`node.id` +: The node id. This is automatically generated and is persistent across full cluster restarts. + +`host.ip` +: The bound IP address of the node, with which the node can be communicated with. + +`host.name` +: The unresolved node’s hostname. + +`event.type` +: The internal processing layer that generated the event: `rest`, `transport`, `ip_filter` or `security_config_change`. This is different from `origin.type` because a request originating from the REST API is translated to a number of transport messages, generating audit events with `origin.type: rest` and `event.type: transport`. + +`event.action` +: The type of event that occurred: `anonymous_access_denied`, `authentication_failed`, `authentication_success`, `realm_authentication_failed`, `access_denied`, `access_granted`, `connection_denied`, `connection_granted`, `tampered_request`, `run_as_denied`, or `run_as_granted`. + + In addition, if `event.type` equals [`security_config_change`](#security-config-change), the `event.action` attribute takes one of the following values: `put_user`, `change_password`, `put_role`, `put_role_mapping`, `change_enable_user`, `change_disable_user`, `put_privileges`, `create_apikey`, `delete_user`, `delete_role`, `delete_role_mapping`, `invalidate_apikeys`, `delete_privileges`, `change_apikey`, or `change_apikeys`. + + +`request.id` +: A synthetic identifier that can be used to correlate the events associated with a particular REST request. + +In addition, all the events of types `rest`, `transport` and `ip_filter` (but not `security_config_change`) have the following extra attributes, which show more details about the requesting client: + +`origin.address` +: The source IP address of the request associated with this event. This could be the address of the remote client, the address of another cluster node, or the local node’s bound address, if the request originated locally. Unless the remote client connects directly to the cluster, the *client address* will actually be the address of the first OSI layer 3 proxy in front of the cluster. + +`origin.type` +: The origin type of the request associated with this event: `rest` (request originated from a REST API request), `transport` (request was received on the transport channel), or `local_node` (the local node issued the request). + +`opaque_id` +: The value of the `X-Opaque-Id` HTTP header (if present) of the request associated with this event. See more: [`X-Opaque-Id` HTTP header - API conventions](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#x-opaque-id) + +`trace_id` +: The identifier extracted from the `traceparent` HTTP header (if present) of the request associated with this event. It allows to surface audit logs into the Trace Logs feature of Elastic APM. + +`x_forwarded_for` +: The verbatim value of the `X-Forwarded-For` HTTP request header (if present) of the request associated with the audit event. This header is commonly added by proxies when they forward requests and the value is the address of the proxied client. When a request crosses multiple proxies the header is a comma delimited list with the last value being the address of the second to last proxy server (the address of the last proxy server is designated by the `origin.address` field). + +## Audit event attributes of the `rest` event type [_audit_event_attributes_of_the_rest_event_type] + +The events with `event.type` equal to `rest` have one of the following `event.action` attribute values: `authentication_success`, `anonymous_access_denied`, `authentication_failed`, `realm_authentication_failed`, `tampered_request` or `run_as_denied`. These events also have the following extra attributes (in addition to the common ones): + +`url.path` +: The path part of the URL (between the port and the query string) of the REST request associated with this event. This is URL encoded. + +`url.query` +: The query part of the URL (after "?", if present) of the REST request associated with this event. This is URL encoded. + +`request.method` +: The HTTP method of the REST request associated with this event. It is one of GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH, TRACE and CONNECT. + +`request.body` +: The full content of the REST request associated with this event, if enabled. This contains the HTTP request body. The body is escaped as a string value according to the JSON RFC 4627. + + +## Audit event attributes of the `transport` event type [_audit_event_attributes_of_the_transport_event_type] + +The events with `event.type` equal to `transport` have one of the following `event.action` attribute values: `authentication_success`, `anonymous_access_denied`, `authentication_failed`, `realm_authentication_failed`, `access_granted`, `access_denied`, `run_as_granted`, `run_as_denied`, or `tampered_request`. These events also have the following extra attributes (in addition to the common ones): + +`action` +: The name of the transport action that was executed. This is like the URL for a REST request. + +`indices` +: The indices names array that the request associated with this event pertains to (when applicable). + +`request.name` +: The name of the request handler that was executed. + + +## Audit event attributes of the `ip_filter` event type [_audit_event_attributes_of_the_ip_filter_event_type] + +The events with `event.type` equal to `ip_filter` have one of the following `event.action` attribute values: `connection_granted` or `connection_denied`. These events also have the following extra attributes (in addition to the common ones): + +`transport_profile` +: The transport profile the request targeted. + +`rule` +: The [IP filtering](../../security/ip-traffic-filtering.md) rule that denied the request. + + +## Audit event attributes of the `security_config_change` event type [security-config-change] + +The events with the `event.type` attribute equal to `security_config_change` have one of the following `event.action` attribute values: `put_user`, `change_password`, `put_role`, `put_role_mapping`, `change_enable_user`, `change_disable_user`, `put_privileges`, `create_apikey`, `delete_user`, `delete_role`, `delete_role_mapping`, `invalidate_apikeys`, `delete_privileges`, `change_apikey`, or `change_apikeys`. + +These events also have **one** of the following extra attributes (in addition to the common ones), which is specific to the `event.type` attribute. The attribute’s value is a nested JSON object: + +`put` +: The object representation of the security config that is being created, or the overwrite of an existing config. It contains the config for a `user`, `role`, `role_mapping`, or for application `privileges`. + +`delete` +: The object representation of the security config that is being deleted. It can be the config for a `user`, `role`, `role_mapping` or for application `privileges`. + +`change` +: The object representation of the security config that is being changed. It can be the `password`, `enable` or `disable`, config object for native or built-in users. If an API key is updated, the config object will be an `apikey`. + +`create` +: The object representation of the new security config that is being created. This is currently only used for API keys auditing. If the API key is created using the [create API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) it only contains an `apikey` config object. If the API key is created using the [grant API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-grant-api-key.html) it also contains a `grant` config object. + +`invalidate` +: The object representation of the security configuration that is being invalidated. The only config that currently supports invalidation is `apikeys`, through the [invalidate API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html). + +The schemas of the security config objects mentioned above are as follows. They are very similar to the request bodies of the corresponding security APIs. + +`user` +: An object like: + + ```js + `{"name": , "enabled": , "roles": , + "full_name": , "email": , "has_password": , + "metadata": }`. + ``` + + The `full_name`, `email` and `metadata` fields are omitted if empty. + + +`role` +: An object like: + + ```js + `{"name": , "role_descriptor": {"cluster": , "global": + {"application":{"manage":{:}}}, "indices": [ {"names": , "privileges": , "field_security": + {"grant": , "except": }, "query": , + "allow_restricted_indices": }], "applications":[{"application": , + "privileges": , "resources": }], "run_as": , + "metadata": }}`. + ``` + + The `global`, `field_security`, `except`, `query`, `allow_restricted_indices` and `metadata` fields are omitted if empty. + + +`role_mapping` +: An object like: + + ```js + `{"name": , "roles": , "role_templates": [{"template": , + "format": }], "rules": , "enabled": , "metadata": }`. + ``` + + The `roles` and `role_templates` fields are omitted if empty. The `rules` object has a recursively nested schema, identical to what is passed in the [API request for mapping roles](../../users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). + + +`privileges` +: An array of objects like: + + ```js + `{"application": , "name": , "actions": , + "metadata": }`. + ``` + + +`password` +: A simple object like: + + ```js + `{"user":{"name": }}` + ``` + + +`enable` +: A simple object like: + + ```js + `{"user":{"name": }}` + ``` + + +`disable` +: A simple object like: + + ```js + `{"user":{"name": }}` + ``` + + +`apikey` +: An object like: + + ```js + `{"id": , "name": , "expiration": , "role_descriptors": [], + "metadata": []}` + ``` + + The `role_descriptors` objects have the same schema as the `role_descriptor` object that is part of the above `role` config object. + + +The object for an API key update will differ in that it will not include a `name`. + +`grant` +: An object like: + + ```js + `{"type": , "user": {"name": , "has_password": }, + "has_access_token": }` + ``` + + +`apikeys` +: An object like: + + ```js + `{"ids": , "name": , "owned_by_authenticated_user": + , "user":{"name": , "realm": }}` + ``` + + The object for a bulk API key update will differ in that it will not include `name`, `owned_by_authenticated_user`, or `user`. Instead, it may include `metadata` and `role_descriptors`, which have the same schemas as the fields in the `apikey` config object above. + + +`service_token` +: An object like: + + ```js + `{"namespace":,"service":,"name":}` + ``` + + + +## Extra audit event attributes for specific events [_extra_audit_event_attributes_for_specific_events] + +There are a few events that have some more attributes in addition to those that have been previously described: + +* `authentication_success`: + + `realm` + : The name of the realm that successfully authenticated the user. If authenticated using an API key, this is the special value of `_es_api_key`. This is a shorthand attribute for the same information that is described by the `user.realm`, `user.run_by.realm` and `authentication.type` attributes. + + `user.name` + : The name of the *effective* user. This is usually the same as the *authenticated* user, but if using the [run as authorization functionality](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) this instead denotes the name of the *impersonated* user. If authenticated using an API key, this is the name of the API key owner. If authenticated using a service account token, this is the service account principal, i.e. `namespace/service_name`. + + `user.realm` + : Name of the realm to which the *effective* user belongs. If authenticated using an API key, this is the name of the realm to which the API key owner belongs. + + `user.run_by.name` + : This attribute is present only if the request is using the [run as authorization functionality](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and denotes the name of the *authenticated* user, which is also known as the *impersonator*. + + `user.run_by.realm` + : Name of the realm to which the *authenticated* (*impersonator*) user belongs. This attribute is provided only if the request uses the [run as authorization functionality](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md). + + `authentication.type` + : Method used to authenticate the user. Possible values are `REALM`, `API_KEY`, `TOKEN`, `ANONYMOUS` or `INTERNAL`. + + `apikey.id` + : API key ID returned by the [create API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) request. This attribute is only provided for authentication using an API key. + + `apikey.name` + : API key name provided in the [create API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) request. This attribute is only provided for authentication using an API key. + + `authentication.token.name` + : Name of the [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md) token. This attribute is only provided for authentication using a service account token. + + `authentication.token.type` + : Type of the [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md) token. This attribute is only provided for authentication using a service account token. + +* `authentication_failed`: + + `user.name` + : The name of the user that failed authentication. If the request authentication token is invalid or unparsable, this information might be missing. + + `authentication.token.name` + : Name of the [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md) token. This attribute is only provided for authentication using a service account token. If the request authentication token is invalid or unparsable, this information might be missing. + + `authentication.token.type` + : Type of the [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md) token. This attribute is only provided for authentication using a service account token. If the request authentication token is invalid or unparsable, this information might be missing. + +* `realm_authentication_failed`: + + `user.name` + : The name of the user that failed authentication. + + `realm` + : The name of the realm that rejected this authentication. **This event is generated for each consulted realm in the chain.** + +* `run_as_denied` and `run_as_granted`: + + `user.roles` + : The role names as an array of the *authenticated* user which is being granted or denied the *impersonation* action. If authenticated as a [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md), this is always an empty array. + + `user.name` + : The name of the *authenticated* user which is being granted or denied the *impersonation* action. + + `user.realm` + : The realm name that the *authenticated* user belongs to. + + `user.run_as.name` + : The name of the user as which the *impersonation* action is granted or denied. + + `user.run_as.realm` + : The realm name of that the *impersonated* user belongs to. + +* `access_granted` and `access_denied`: + + `user.roles` + : The role names of the user as an array. If authenticated using an API key, this contains the role names of the API key owner. If authenticated as a [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md), this is always an empty array. + + `user.name` + : The name of the *effective* user. This is usually the same as the *authenticated* user, but if using the [run as authorization functionality](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) this instead denotes the name of the *impersonated* user. If authenticated using an API key, this is the name of the API key owner. + + `user.realm` + : Name of the realm to which the *effective* user belongs. If authenticated using an API key, this is the name of the realm to which the API key owner belongs. + + `user.run_by.name` + : This attribute is present only if the request is using the [run as authorization functionality](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and denoted the name of the *authenticated* user, which is also known as the *impersonator*. + + `user.run_by.realm` + : This attribute is present only if the request is using the [run as authorization functionality](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) and denotes the name of the realm that the *authenticated* (*impersonator*) user belongs to. + + `authentication.type` + : Method used to authenticate the user. Possible values are `REALM`, `API_KEY`, `TOKEN`, `ANONYMOUS` or `INTERNAL`. + + `apikey.id` + : API key ID returned by the [create API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) request. This attribute is only provided for authentication using an API key. + + `apikey.name` + : API key name provided in the [create API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) request. This attribute is only provided for authentication using an API key. + + `authentication.token.name` + : Name of the [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md) token. This attribute is only provided for authentication using a service account token. + + `authentication.token.type` + : Type of the [service account](../../users-roles/cluster-or-deployment-auth/service-accounts.md) token. This attribute is only provided for authentication using a service account token. diff --git a/deploy-manage/monitor/logging-configuration/elasticsearch-deprecation-logs.md b/deploy-manage/monitor/logging-configuration/elasticsearch-deprecation-logs.md new file mode 100644 index 000000000..d86fe96e1 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/elasticsearch-deprecation-logs.md @@ -0,0 +1,289 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/logging.html +--- + +# Elasticsearch deprecation logs [logging] + +You can use {{es}}'s application logs to monitor your cluster and diagnose issues. If you run {{es}} as a service, the default location of the logs varies based on your platform and installation method: + +:::::::{tab-set} + +::::::{tab-item} Docker +On [Docker](../../deploy/self-managed/install-elasticsearch-with-docker.md), log messages go to the console and are handled by the configured Docker logging driver. To access logs, run `docker logs`. +:::::: + +::::::{tab-item} Debian (APT) +For [Debian installations](../../deploy/self-managed/install-elasticsearch-with-debian-package.md), {{es}} writes logs to `/var/log/elasticsearch`. +:::::: + +::::::{tab-item} RPM +For [RPM installations](../../deploy/self-managed/install-elasticsearch-with-rpm.md), {{es}} writes logs to `/var/log/elasticsearch`. +:::::: + +::::::{tab-item} macOS +For [macOS `.tar.gz`](../../deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md) installations, {{es}} writes logs to `$ES_HOME/logs`. + +Files in `$ES_HOME` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `$ES_HOME`. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::{tab-item} Linux +For [Linux `.tar.gz`](../../deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md) installations, {{es}} writes logs to `$ES_HOME/logs`. + +Files in `$ES_HOME` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `$ES_HOME`. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::{tab-item} Windows .zip +For [Windows `.zip`](../../deploy/self-managed/install-elasticsearch-with-zip-on-windows.md) installations, {{es}} writes logs to `%ES_HOME%\logs`. + +Files in `%ES_HOME%` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `%ES_HOME%``. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::: +If you run {{es}} from the command line, {{es}} prints logs to the standard output (`stdout`). + + +## Logging configuration [logging-configuration] + +::::{important} +Elastic strongly recommends using the Log4j 2 configuration that is shipped by default. +:::: + + +Elasticsearch uses [Log4j 2](https://logging.apache.org/log4j/2.x/) for logging. Log4j 2 can be configured using the log4j2.properties file. Elasticsearch exposes three properties, `${sys:es.logs.base_path}`, `${sys:es.logs.cluster_name}`, and `${sys:es.logs.node_name}` that can be referenced in the configuration file to determine the location of the log files. The property `${sys:es.logs.base_path}` will resolve to the log directory, `${sys:es.logs.cluster_name}` will resolve to the cluster name (used as the prefix of log filenames in the default configuration), and `${sys:es.logs.node_name}` will resolve to the node name (if the node name is explicitly set). + +For example, if your log directory (`path.logs`) is `/var/log/elasticsearch` and your cluster is named `production` then `${sys:es.logs.base_path}` will resolve to `/var/log/elasticsearch` and `${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}.log` will resolve to `/var/log/elasticsearch/production.log`. + +```properties +####### Server JSON ############################ +appender.rolling.type = RollingFile <1> +appender.rolling.name = rolling +appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.json <2> +appender.rolling.layout.type = ECSJsonLayout <3> +appender.rolling.layout.dataset = elasticsearch.server <4> +appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.json.gz <5> +appender.rolling.policies.type = Policies +appender.rolling.policies.time.type = TimeBasedTriggeringPolicy <6> +appender.rolling.policies.time.interval = 1 <7> +appender.rolling.policies.time.modulate = true <8> +appender.rolling.policies.size.type = SizeBasedTriggeringPolicy <9> +appender.rolling.policies.size.size = 256MB <10> +appender.rolling.strategy.type = DefaultRolloverStrategy +appender.rolling.strategy.fileIndex = nomax +appender.rolling.strategy.action.type = Delete <11> +appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} +appender.rolling.strategy.action.condition.type = IfFileName <12> +appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* <13> +appender.rolling.strategy.action.condition.nested_condition.type = IfAccumulatedFileSize <14> +appender.rolling.strategy.action.condition.nested_condition.exceeds = 2GB <15> +################################################ +``` + +1. Configure the `RollingFile` appender +2. Log to `/var/log/elasticsearch/production_server.json` +3. Use JSON layout. +4. `dataset` is a flag populating the `event.dataset` field in a `ECSJsonLayout`. It can be used to distinguish different types of logs more easily when parsing them. +5. Roll logs to `/var/log/elasticsearch/production-yyyy-MM-dd-i.json`; logs will be compressed on each roll and `i` will be incremented +6. Use a time-based roll policy +7. Roll logs on a daily basis +8. Align rolls on the day boundary (as opposed to rolling every twenty-four hours) +9. Using a size-based roll policy +10. Roll logs after 256 MB +11. Use a delete action when rolling logs +12. Only delete logs matching a file pattern +13. The pattern is to only delete the main logs +14. Only delete if we have accumulated too many compressed logs +15. The size condition on the compressed logs is 2 GB + + +```properties +####### Server - old style pattern ########### +appender.rolling_old.type = RollingFile +appender.rolling_old.name = rolling_old +appender.rolling_old.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.log <1> +appender.rolling_old.layout.type = PatternLayout +appender.rolling_old.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %m%n +appender.rolling_old.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.old_log.gz +``` + +1. The configuration for `old style` pattern appenders. These logs will be saved in `*.log` files and if archived will be in `* .log.gz` files. Note that these should be considered deprecated and will be removed in the future. + + +::::{note} +Log4j’s configuration parsing gets confused by any extraneous whitespace; if you copy and paste any Log4j settings on this page, or enter any Log4j configuration in general, be sure to trim any leading and trailing whitespace. +:::: + + +Note than you can replace `.gz` by `.zip` in `appender.rolling.filePattern` to compress the rolled logs using the zip format. If you remove the `.gz` extension then logs will not be compressed as they are rolled. + +If you want to retain log files for a specified period of time, you can use a rollover strategy with a delete action. + +```properties +appender.rolling.strategy.type = DefaultRolloverStrategy <1> +appender.rolling.strategy.action.type = Delete <2> +appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} <3> +appender.rolling.strategy.action.condition.type = IfFileName <4> +appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* <5> +appender.rolling.strategy.action.condition.nested_condition.type = IfLastModified <6> +appender.rolling.strategy.action.condition.nested_condition.age = 7D <7> +``` + +1. Configure the `DefaultRolloverStrategy` +2. Configure the `Delete` action for handling rollovers +3. The base path to the Elasticsearch logs +4. The condition to apply when handling rollovers +5. Delete files from the base path matching the glob `${sys:es.logs.cluster_name}-*`; this is the glob that log files are rolled to; this is needed to only delete the rolled Elasticsearch logs but not also delete the deprecation and slow logs +6. A nested condition to apply to files matching the glob +7. Retain logs for seven days + + +Multiple configuration files can be loaded (in which case they will get merged) as long as they are named `log4j2.properties` and have the Elasticsearch config directory as an ancestor; this is useful for plugins that expose additional loggers. The logger section contains the java packages and their corresponding log level. The appender section contains the destinations for the logs. Extensive information on how to customize logging and all the supported appenders can be found on the [Log4j documentation](https://logging.apache.org/log4j/2.x/manual/configuration.md). + + +## Configuring logging levels [configuring-logging-levels] + +Log4J 2 log messages include a *level* field, which is one of the following (in order of increasing verbosity): + +* `FATAL` +* `ERROR` +* `WARN` +* `INFO` +* `DEBUG` +* `TRACE` + +By default {{es}} includes all messages at levels `INFO`, `WARN`, `ERROR` and `FATAL` in its logs, but filters out messages at levels `DEBUG` and `TRACE`. This is the recommended configuration. Do not filter out messages at `INFO` or higher log levels or else you may not be able to understand your cluster’s behaviour or troubleshoot common problems. Do not enable logging at levels `DEBUG` or `TRACE` unless you are following instructions elsewhere in this manual which call for more detailed logging, or you are an expert user who will be reading the {{es}} source code to determine the meaning of the logs. + +Messages are logged by a hierarchy of loggers which matches the hierarchy of Java packages and classes in the [{{es}} source code](https://github.com/elastic/elasticsearch/). Every logger has a corresponding [dynamic setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) which can be used to control the verbosity of its logs. The setting’s name is the fully-qualified name of the package or class, prefixed with `logger.`. + +You may set each logger’s verbosity to the name of a log level, for instance `DEBUG`, which means that messages from this logger at levels up to the specified one will be included in the logs. You may also use the value `OFF` to suppress all messages from the logger. + +For example, the `org.elasticsearch.discovery` package contains functionality related to the [discovery](../../distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md) process, and you can control the verbosity of its logs with the `logger.org.elasticsearch.discovery` setting. To enable `DEBUG` logging for this package, use the [Cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) as follows: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.discovery": "DEBUG" + } +} +``` + +To reset this package’s log verbosity to its default level, set the logger setting to `null`: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.discovery": null + } +} +``` + +Other ways to change log levels include: + +1. `elasticsearch.yml`: + + ```yaml + logger.org.elasticsearch.discovery: DEBUG + ``` + + This is most appropriate when debugging a problem on a single node. + +2. `log4j2.properties`: + + ```properties + logger.discovery.name = org.elasticsearch.discovery + logger.discovery.level = debug + ``` + + This is most appropriate when you already need to change your Log4j 2 configuration for other reasons. For example, you may want to send logs for a particular logger to another file. However, these use cases are rare. + + +::::{important} +{{es}}'s application logs are intended for humans to read and interpret. Different versions of {{es}} may report information in these logs in different ways, perhaps adding extra detail, removing unnecessary information, formatting the same information in different ways, renaming the logger or adjusting the log level for specific messages. Do not rely on the contents of the application logs remaining precisely the same between versions. +:::: + + +::::{note} +To prevent leaking sensitive information in logs, {{es}} suppresses certain log messages by default even at the highest verbosity levels. To disable this protection on a node, set the Java system property `es.insecure_network_trace_enabled` to `true`. This feature is primarily intended for test systems which do not contain any sensitive information. If you set this property on a system which contains sensitive information, you must protect your logs from unauthorized access. +:::: + + + +## Deprecation logging [deprecation-logging] + +{{es}} also writes deprecation logs to the log directory. These logs record a message when you use deprecated {{es}} functionality. You can use the deprecation logs to update your application before upgrading {{es}} to a new major version. + +By default, {{es}} rolls and compresses deprecation logs at 1GB. The default configuration preserves a maximum of five log files: four rolled logs and an active log. + +{{es}} emits deprecation log messages at the `CRITICAL` level. Those messages are indicating that a used deprecation feature will be removed in a next major version. Deprecation log messages at the `WARN` level indicates that a less critical feature was used, it won’t be removed in next major version, but might be removed in the future. + +To stop writing deprecation log messages, set `logger.deprecation.level` to `OFF` in `log4j2.properties` : + +```properties +logger.deprecation.level = OFF +``` + +Alternatively, you can change the logging level dynamically: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.deprecation": "OFF" + } +} +``` + +Refer to [Configuring logging levels](elasticsearch-log4j-configuration-self-managed.md#configuring-logging-levels). + +You can identify what is triggering deprecated functionality if `X-Opaque-Id` was used as an HTTP header. The user ID is included in the `X-Opaque-ID` field in deprecation JSON logs. + +```js +{ + "type": "deprecation", + "timestamp": "2019-08-30T12:07:07,126+02:00", + "level": "WARN", + "component": "o.e.d.r.a.a.i.RestCreateIndexAction", + "cluster.name": "distribution_run", + "node.name": "node-0", + "message": "[types removal] Using include_type_name in create index requests is deprecated. The parameter will be removed in the next major version.", + "x-opaque-id": "MY_USER_ID", + "cluster.uuid": "Aq-c-PAeQiK3tfBYtig9Bw", + "node.id": "D7fUYfnfTLa2D7y-xw6tZg" +} +``` + +Deprecation logs can be indexed into `.logs-deprecation.elasticsearch-default` data stream `cluster.deprecation_indexing.enabled` setting is set to true. + + +### Deprecation logs throttling [_deprecation_logs_throttling] + +Deprecation logs are deduplicated based on a deprecated feature key and x-opaque-id so that if a feature is repeatedly used, it will not overload the deprecation logs. This applies to both indexed deprecation logs and logs emitted to log files. You can disable the use of `x-opaque-id` in throttling by changing `cluster.deprecation_indexing.x_opaque_id_used.enabled` to false, refer to this class [javadoc](https://snapshots.elastic.co/javadoc/org/elasticsearch/elasticsearch/9.0.0-beta1-SNAPSHOT/org.elasticsearch.server/org/elasticsearch/common/logging/RateLimitingFilter.md) for more details. + + +## JSON log format [json-logging] + +To make parsing Elasticsearch logs easier, logs are now printed in a JSON format. This is configured by a Log4J layout property `appender.rolling.layout.type = ECSJsonLayout`. This layout requires a `dataset` attribute to be set which is used to distinguish logs streams when parsing. + +```properties +appender.rolling.layout.type = ECSJsonLayout +appender.rolling.layout.dataset = elasticsearch.server +``` + +Each line contains a single JSON document with the properties configured in `ECSJsonLayout`. See this class [javadoc](https://snapshots.elastic.co/javadoc/org/elasticsearch/elasticsearch/9.0.0-beta1-SNAPSHOT/org.elasticsearch.server/org/elasticsearch/common/logging/ESJsonLayout.md) for more details. However if a JSON document contains an exception, it will be printed over multiple lines. The first line will contain regular properties and subsequent lines will contain the stacktrace formatted as a JSON array. + +::::{note} +You can still use your own custom layout. To do that replace the line `appender.rolling.layout.type` with a different layout. See sample below: +:::: + + +```properties +appender.rolling.type = RollingFile +appender.rolling.name = rolling +appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.log +appender.rolling.layout.type = PatternLayout +appender.rolling.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %.-10000m%n +appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.log.gz +``` + diff --git a/deploy-manage/monitor/logging-configuration/elasticsearch-log4j-configuration-self-managed.md b/deploy-manage/monitor/logging-configuration/elasticsearch-log4j-configuration-self-managed.md new file mode 100644 index 000000000..5138d9d19 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/elasticsearch-log4j-configuration-self-managed.md @@ -0,0 +1,289 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/logging.html +--- + +# Elasticsearch log4j configuration (self-managed) [logging] + +You can use {{es}}'s application logs to monitor your cluster and diagnose issues. If you run {{es}} as a service, the default location of the logs varies based on your platform and installation method: + +:::::::{tab-set} + +::::::{tab-item} Docker +On [Docker](../../deploy/self-managed/install-elasticsearch-with-docker.md), log messages go to the console and are handled by the configured Docker logging driver. To access logs, run `docker logs`. +:::::: + +::::::{tab-item} Debian (APT) +For [Debian installations](../../deploy/self-managed/install-elasticsearch-with-debian-package.md), {{es}} writes logs to `/var/log/elasticsearch`. +:::::: + +::::::{tab-item} RPM +For [RPM installations](../../deploy/self-managed/install-elasticsearch-with-rpm.md), {{es}} writes logs to `/var/log/elasticsearch`. +:::::: + +::::::{tab-item} macOS +For [macOS `.tar.gz`](../../deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md) installations, {{es}} writes logs to `$ES_HOME/logs`. + +Files in `$ES_HOME` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `$ES_HOME`. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::{tab-item} Linux +For [Linux `.tar.gz`](../../deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md) installations, {{es}} writes logs to `$ES_HOME/logs`. + +Files in `$ES_HOME` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `$ES_HOME`. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::{tab-item} Windows .zip +For [Windows `.zip`](../../deploy/self-managed/install-elasticsearch-with-zip-on-windows.md) installations, {{es}} writes logs to `%ES_HOME%\logs`. + +Files in `%ES_HOME%` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `%ES_HOME%``. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::: +If you run {{es}} from the command line, {{es}} prints logs to the standard output (`stdout`). + + +## Logging configuration [logging-configuration] + +::::{important} +Elastic strongly recommends using the Log4j 2 configuration that is shipped by default. +:::: + + +Elasticsearch uses [Log4j 2](https://logging.apache.org/log4j/2.x/) for logging. Log4j 2 can be configured using the log4j2.properties file. Elasticsearch exposes three properties, `${sys:es.logs.base_path}`, `${sys:es.logs.cluster_name}`, and `${sys:es.logs.node_name}` that can be referenced in the configuration file to determine the location of the log files. The property `${sys:es.logs.base_path}` will resolve to the log directory, `${sys:es.logs.cluster_name}` will resolve to the cluster name (used as the prefix of log filenames in the default configuration), and `${sys:es.logs.node_name}` will resolve to the node name (if the node name is explicitly set). + +For example, if your log directory (`path.logs`) is `/var/log/elasticsearch` and your cluster is named `production` then `${sys:es.logs.base_path}` will resolve to `/var/log/elasticsearch` and `${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}.log` will resolve to `/var/log/elasticsearch/production.log`. + +```properties +####### Server JSON ############################ +appender.rolling.type = RollingFile <1> +appender.rolling.name = rolling +appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.json <2> +appender.rolling.layout.type = ECSJsonLayout <3> +appender.rolling.layout.dataset = elasticsearch.server <4> +appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.json.gz <5> +appender.rolling.policies.type = Policies +appender.rolling.policies.time.type = TimeBasedTriggeringPolicy <6> +appender.rolling.policies.time.interval = 1 <7> +appender.rolling.policies.time.modulate = true <8> +appender.rolling.policies.size.type = SizeBasedTriggeringPolicy <9> +appender.rolling.policies.size.size = 256MB <10> +appender.rolling.strategy.type = DefaultRolloverStrategy +appender.rolling.strategy.fileIndex = nomax +appender.rolling.strategy.action.type = Delete <11> +appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} +appender.rolling.strategy.action.condition.type = IfFileName <12> +appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* <13> +appender.rolling.strategy.action.condition.nested_condition.type = IfAccumulatedFileSize <14> +appender.rolling.strategy.action.condition.nested_condition.exceeds = 2GB <15> +################################################ +``` + +1. Configure the `RollingFile` appender +2. Log to `/var/log/elasticsearch/production_server.json` +3. Use JSON layout. +4. `dataset` is a flag populating the `event.dataset` field in a `ECSJsonLayout`. It can be used to distinguish different types of logs more easily when parsing them. +5. Roll logs to `/var/log/elasticsearch/production-yyyy-MM-dd-i.json`; logs will be compressed on each roll and `i` will be incremented +6. Use a time-based roll policy +7. Roll logs on a daily basis +8. Align rolls on the day boundary (as opposed to rolling every twenty-four hours) +9. Using a size-based roll policy +10. Roll logs after 256 MB +11. Use a delete action when rolling logs +12. Only delete logs matching a file pattern +13. The pattern is to only delete the main logs +14. Only delete if we have accumulated too many compressed logs +15. The size condition on the compressed logs is 2 GB + + +```properties +####### Server - old style pattern ########### +appender.rolling_old.type = RollingFile +appender.rolling_old.name = rolling_old +appender.rolling_old.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.log <1> +appender.rolling_old.layout.type = PatternLayout +appender.rolling_old.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %m%n +appender.rolling_old.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.old_log.gz +``` + +1. The configuration for `old style` pattern appenders. These logs will be saved in `*.log` files and if archived will be in `* .log.gz` files. Note that these should be considered deprecated and will be removed in the future. + + +::::{note} +Log4j’s configuration parsing gets confused by any extraneous whitespace; if you copy and paste any Log4j settings on this page, or enter any Log4j configuration in general, be sure to trim any leading and trailing whitespace. +:::: + + +Note than you can replace `.gz` by `.zip` in `appender.rolling.filePattern` to compress the rolled logs using the zip format. If you remove the `.gz` extension then logs will not be compressed as they are rolled. + +If you want to retain log files for a specified period of time, you can use a rollover strategy with a delete action. + +```properties +appender.rolling.strategy.type = DefaultRolloverStrategy <1> +appender.rolling.strategy.action.type = Delete <2> +appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} <3> +appender.rolling.strategy.action.condition.type = IfFileName <4> +appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* <5> +appender.rolling.strategy.action.condition.nested_condition.type = IfLastModified <6> +appender.rolling.strategy.action.condition.nested_condition.age = 7D <7> +``` + +1. Configure the `DefaultRolloverStrategy` +2. Configure the `Delete` action for handling rollovers +3. The base path to the Elasticsearch logs +4. The condition to apply when handling rollovers +5. Delete files from the base path matching the glob `${sys:es.logs.cluster_name}-*`; this is the glob that log files are rolled to; this is needed to only delete the rolled Elasticsearch logs but not also delete the deprecation and slow logs +6. A nested condition to apply to files matching the glob +7. Retain logs for seven days + + +Multiple configuration files can be loaded (in which case they will get merged) as long as they are named `log4j2.properties` and have the Elasticsearch config directory as an ancestor; this is useful for plugins that expose additional loggers. The logger section contains the java packages and their corresponding log level. The appender section contains the destinations for the logs. Extensive information on how to customize logging and all the supported appenders can be found on the [Log4j documentation](https://logging.apache.org/log4j/2.x/manual/configuration.md). + + +## Configuring logging levels [configuring-logging-levels] + +Log4J 2 log messages include a *level* field, which is one of the following (in order of increasing verbosity): + +* `FATAL` +* `ERROR` +* `WARN` +* `INFO` +* `DEBUG` +* `TRACE` + +By default {{es}} includes all messages at levels `INFO`, `WARN`, `ERROR` and `FATAL` in its logs, but filters out messages at levels `DEBUG` and `TRACE`. This is the recommended configuration. Do not filter out messages at `INFO` or higher log levels or else you may not be able to understand your cluster’s behaviour or troubleshoot common problems. Do not enable logging at levels `DEBUG` or `TRACE` unless you are following instructions elsewhere in this manual which call for more detailed logging, or you are an expert user who will be reading the {{es}} source code to determine the meaning of the logs. + +Messages are logged by a hierarchy of loggers which matches the hierarchy of Java packages and classes in the [{{es}} source code](https://github.com/elastic/elasticsearch/). Every logger has a corresponding [dynamic setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) which can be used to control the verbosity of its logs. The setting’s name is the fully-qualified name of the package or class, prefixed with `logger.`. + +You may set each logger’s verbosity to the name of a log level, for instance `DEBUG`, which means that messages from this logger at levels up to the specified one will be included in the logs. You may also use the value `OFF` to suppress all messages from the logger. + +For example, the `org.elasticsearch.discovery` package contains functionality related to the [discovery](../../distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md) process, and you can control the verbosity of its logs with the `logger.org.elasticsearch.discovery` setting. To enable `DEBUG` logging for this package, use the [Cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) as follows: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.discovery": "DEBUG" + } +} +``` + +To reset this package’s log verbosity to its default level, set the logger setting to `null`: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.discovery": null + } +} +``` + +Other ways to change log levels include: + +1. `elasticsearch.yml`: + + ```yaml + logger.org.elasticsearch.discovery: DEBUG + ``` + + This is most appropriate when debugging a problem on a single node. + +2. `log4j2.properties`: + + ```properties + logger.discovery.name = org.elasticsearch.discovery + logger.discovery.level = debug + ``` + + This is most appropriate when you already need to change your Log4j 2 configuration for other reasons. For example, you may want to send logs for a particular logger to another file. However, these use cases are rare. + + +::::{important} +{{es}}'s application logs are intended for humans to read and interpret. Different versions of {{es}} may report information in these logs in different ways, perhaps adding extra detail, removing unnecessary information, formatting the same information in different ways, renaming the logger or adjusting the log level for specific messages. Do not rely on the contents of the application logs remaining precisely the same between versions. +:::: + + +::::{note} +To prevent leaking sensitive information in logs, {{es}} suppresses certain log messages by default even at the highest verbosity levels. To disable this protection on a node, set the Java system property `es.insecure_network_trace_enabled` to `true`. This feature is primarily intended for test systems which do not contain any sensitive information. If you set this property on a system which contains sensitive information, you must protect your logs from unauthorized access. +:::: + + + +## Deprecation logging [deprecation-logging] + +{{es}} also writes deprecation logs to the log directory. These logs record a message when you use deprecated {{es}} functionality. You can use the deprecation logs to update your application before upgrading {{es}} to a new major version. + +By default, {{es}} rolls and compresses deprecation logs at 1GB. The default configuration preserves a maximum of five log files: four rolled logs and an active log. + +{{es}} emits deprecation log messages at the `CRITICAL` level. Those messages are indicating that a used deprecation feature will be removed in a next major version. Deprecation log messages at the `WARN` level indicates that a less critical feature was used, it won’t be removed in next major version, but might be removed in the future. + +To stop writing deprecation log messages, set `logger.deprecation.level` to `OFF` in `log4j2.properties` : + +```properties +logger.deprecation.level = OFF +``` + +Alternatively, you can change the logging level dynamically: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.deprecation": "OFF" + } +} +``` + +Refer to [Configuring logging levels](#configuring-logging-levels). + +You can identify what is triggering deprecated functionality if `X-Opaque-Id` was used as an HTTP header. The user ID is included in the `X-Opaque-ID` field in deprecation JSON logs. + +```js +{ + "type": "deprecation", + "timestamp": "2019-08-30T12:07:07,126+02:00", + "level": "WARN", + "component": "o.e.d.r.a.a.i.RestCreateIndexAction", + "cluster.name": "distribution_run", + "node.name": "node-0", + "message": "[types removal] Using include_type_name in create index requests is deprecated. The parameter will be removed in the next major version.", + "x-opaque-id": "MY_USER_ID", + "cluster.uuid": "Aq-c-PAeQiK3tfBYtig9Bw", + "node.id": "D7fUYfnfTLa2D7y-xw6tZg" +} +``` + +Deprecation logs can be indexed into `.logs-deprecation.elasticsearch-default` data stream `cluster.deprecation_indexing.enabled` setting is set to true. + + +### Deprecation logs throttling [_deprecation_logs_throttling] + +Deprecation logs are deduplicated based on a deprecated feature key and x-opaque-id so that if a feature is repeatedly used, it will not overload the deprecation logs. This applies to both indexed deprecation logs and logs emitted to log files. You can disable the use of `x-opaque-id` in throttling by changing `cluster.deprecation_indexing.x_opaque_id_used.enabled` to false, refer to this class [javadoc](https://snapshots.elastic.co/javadoc/org/elasticsearch/elasticsearch/9.0.0-beta1-SNAPSHOT/org.elasticsearch.server/org/elasticsearch/common/logging/RateLimitingFilter.md) for more details. + + +## JSON log format [json-logging] + +To make parsing Elasticsearch logs easier, logs are now printed in a JSON format. This is configured by a Log4J layout property `appender.rolling.layout.type = ECSJsonLayout`. This layout requires a `dataset` attribute to be set which is used to distinguish logs streams when parsing. + +```properties +appender.rolling.layout.type = ECSJsonLayout +appender.rolling.layout.dataset = elasticsearch.server +``` + +Each line contains a single JSON document with the properties configured in `ECSJsonLayout`. See this class [javadoc](https://snapshots.elastic.co/javadoc/org/elasticsearch/elasticsearch/9.0.0-beta1-SNAPSHOT/org.elasticsearch.server/org/elasticsearch/common/logging/ESJsonLayout.md) for more details. However if a JSON document contains an exception, it will be printed over multiple lines. The first line will contain regular properties and subsequent lines will contain the stacktrace formatted as a JSON array. + +::::{note} +You can still use your own custom layout. To do that replace the line `appender.rolling.layout.type` with a different layout. See sample below: +:::: + + +```properties +appender.rolling.type = RollingFile +appender.rolling.name = rolling +appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.log +appender.rolling.layout.type = PatternLayout +appender.rolling.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %.-10000m%n +appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.log.gz +``` + diff --git a/deploy-manage/monitor/logging-configuration/enabling-audit-logs-in-orchestrated-deployments.md b/deploy-manage/monitor/logging-configuration/enabling-audit-logs-in-orchestrated-deployments.md new file mode 100644 index 000000000..b64e75d28 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/enabling-audit-logs-in-orchestrated-deployments.md @@ -0,0 +1,20 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-enable-auditing.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_audit_logging.html + - https://www.elastic.co/guide/en/cloud/current/ec-enable-logging-and-monitoring.html#ec-enable-audit-logs +--- + +# Enabling audit logs in orchestrated deployments + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: Merge the content and even consider putting everything under a global section that also covers Elasticsearch self-managed + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-enable-auditing.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s_audit_logging.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-enable-logging-and-monitoring.md \ No newline at end of file diff --git a/deploy-manage/monitor/logging-configuration/enabling-elasticsearch-audit-logs.md b/deploy-manage/monitor/logging-configuration/enabling-elasticsearch-audit-logs.md new file mode 100644 index 000000000..6ca3ed0ec --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/enabling-elasticsearch-audit-logs.md @@ -0,0 +1,30 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/enable-audit-logging.html +--- + +# Enabling elasticsearch audit logs [enable-audit-logging] + +You can log security-related events such as authentication failures and refused connections to monitor your cluster for suspicious activity (including data access authorization and user security configuration changes). + +Audit logging also provides forensic evidence in the event of an attack. + +::::{important} +Audit logs are **disabled** by default. You must explicitly enable audit logging. + +:::: + + +::::{tip} +Audit logs are only available on certain subscription levels. For more information, see {{subscriptions}}. +:::: + + +To enable audit logging: + +1. Set `xpack.security.audit.enabled` to `true` in `elasticsearch.yml`. +2. Restart {{es}}. + +When audit logging is enabled, [security events](elasticsearch-audit-events.md) are persisted to a dedicated `_audit.json` file on the host’s file system, on every cluster node. For more information, see [Logfile audit output](logfile-audit-output.md). + +You can configure additional options to control what events are logged and what information is included in the audit log. For more information, see [Auditing settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html). diff --git a/deploy-manage/monitor/logging-configuration/enabling-kibana-audit-logs.md b/deploy-manage/monitor/logging-configuration/enabling-kibana-audit-logs.md new file mode 100644 index 000000000..3d91280a5 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/enabling-kibana-audit-logs.md @@ -0,0 +1,404 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/xpack-security-audit-logging.html +--- + +# Enabling Kibana audit logs [xpack-security-audit-logging] + +Audit logging is a [subscription feature](https://www.elastic.co/subscriptions) that you can enable to keep track of security-related events, such as authorization success and failures. Logging these events enables you to monitor {{kib}} for suspicious activity and provides evidence in the event of an attack. + +Use the {{kib}} audit logs in conjunction with [{{es}} audit logging](enabling-elasticsearch-audit-logs.md) to get a holistic view of all security related events. {{kib}} defers to the {{es}} security model for authentication, data index authorization, and features that are driven by cluster-wide privileges. For more information on enabling audit logging in {{es}}, refer to [Auditing security events](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing.html). + +::::{note} +Audit logs are **disabled** by default. To enable this functionality, you must set `xpack.security.audit.enabled` to `true` in `kibana.yml`. + +You can optionally configure audit logs location, file/rolling file appenders and ignore filters using [Audit logging settings](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-settings). + +:::: + + +## Audit events [xpack-security-ecs-audit-logging] + +Refer to the table of events that can be logged for auditing purposes. + +Each event is broken down into [category](#field-event-category), [type](#field-event-type), [action](#field-event-action) and [outcome](#field-event-outcome) fields to make it easy to filter, query and aggregate the resulting logs. The [trace.id](#field-trace-id) field can be used to correlate multiple events that originate from the same request. + +Refer to [Audit schema](#xpack-security-ecs-audit-schema) for a table of fields that get logged with audit event. + +::::{note} +To ensure that a record of every operation is persisted even in case of an unexpected error, asynchronous write operations are logged immediately after all authorization checks have passed, but before the response from {{es}} is received. Refer to the corresponding {{es}} logs for potential write errors. + +:::: + + +| | +| --- | +| #### Category: authentication [_category_authentication]


| +| **Action** | **Outcome** | **Description** | +| `user_login` | `success` | User has logged in successfully. | +| `failure` | Failed login attempt (e.g. due to invalid credentials). | +| `user_logout` | `unknown` | User is logging out. | +| `session_cleanup` | `unknown` | Removing invalid or expired session. | +| `access_agreement_acknowledged` | n/a | User has acknowledged the access agreement. | +| #### Category: database [_category_database]

##### Type: creation [_type_creation]



| +| **Action** | **Outcome** | **Description** | +| `saved_object_create` | `unknown` | User is creating a saved object. | +| `failure` | User is not authorized to create a saved object. | +| `saved_object_open_point_in_time` | `unknown` | User is creating a Point In Time to use when querying saved objects. | +| `failure` | User is not authorized to create a Point In Time for the provided saved object types. | +| `connector_create` | `unknown` | User is creating a connector. | +| `failure` | User is not authorized to create a connector. | +| `rule_create` | `unknown` | User is creating a rule. | +| `failure` | User is not authorized to create a rule. | +| `ad_hoc_run_create` | `unknown` | User is creating an ad hoc run. | +| `failure` | User is not authorized to create an ad hoc run. | +| `space_create` | `unknown` | User is creating a space. | +| `failure` | User is not authorized to create a space. | +| `case_create` | `unknown` | User is creating a case. | +| `failure` | User is not authorized to create a case. | +| `case_configuration_create` | `unknown` | User is creating a case configuration. | +| `failure` | User is not authorized to create a case configuration. | +| `case_comment_create` | `unknown` | User is creating a case comment. | +| `failure` | User is not authorized to create a case comment. | +| `case_comment_bulk_create` | `unknown` | User is creating multiple case comments. | +| `failure` | User is not authorized to create multiple case comments. | +| `case_user_action_create_comment` | `success` | User has created a case comment. | +| `case_user_action_create_case` | `success` | User has created a case. | +| `ml_put_ad_job` | `success` | Creating anomaly detection job. | +| `failure` | Failed to create anomaly detection job. | +| `ml_put_ad_datafeed` | `success` | Creating anomaly detection datafeed. | +| `failure` | Failed to create anomaly detection datafeed. | +| `ml_put_calendar` | `success` | Creating calendar. | +| `failure` | Failed to create calendar. | +| `ml_post_calendar_events` | `success` | Adding events to calendar. | +| `failure` | Failed to add events to calendar. | +| `ml_forecast` | `success` | Creating anomaly detection forecast. | +| `failure` | Failed to create anomaly detection forecast. | +| `ml_put_filter` | `success` | Creating filter. | +| `failure` | Failed to create filter. | +| `ml_put_dfa_job` | `success` | Creating data frame analytics job. | +| `failure` | Failed to create data frame analytics job. | +| `ml_put_trained_model` | `success` | Creating trained model. | +| `failure` | Failed to create trained model. | +| `product_documentation_create` | `unknown` | User requested to install the product documentation for use in AI Assistants. | +| `knowledge_base_entry_create` | `success` | User has created knowledge base entry [id=x] | +| `failure` | Failed attempt to create a knowledge base entry | +| `knowledge_base_entry_update` | `success` | User has updated knowledge base entry [id=x] | +| `failure` | Failed attempt to update a knowledge base entry | +| `knowledge_base_entry_delete` | `success` | User has deleted knowledge base entry [id=x] | +| `failure` | Failed attempt to delete a knowledge base entry | +| ##### Type: change [_type_change]


| +| **Action** | **Outcome** | **Description** | +| `saved_object_update` | `unknown` | User is updating a saved object. | +| `failure` | User is not authorized to update a saved object. | +| `saved_object_update_objects_spaces` | `unknown` | User is adding and/or removing a saved object to/from other spaces. | +| `failure` | User is not authorized to add or remove a saved object to or from other spaces. | +| `saved_object_remove_references` | `unknown` | User is removing references to a saved object. | +| `failure` | User is not authorized to remove references to a saved object. | +| `saved_object_collect_multinamespace_references` | `success` | User has accessed references to a multi-space saved object. | +| `failure` | User is not authorized to access references to a multi-space saved object. | +| `connector_update` | `unknown` | User is updating a connector. | +| `failure` | User is not authorized to update a connector. | +| `rule_update` | `unknown` | User is updating a rule. | +| `failure` | User is not authorized to update a rule. | +| `rule_update_api_key` | `unknown` | User is updating the API key of a rule. | +| `failure` | User is not authorized to update the API key of a rule. | +| `rule_enable` | `unknown` | User is enabling a rule. | +| `failure` | User is not authorized to enable a rule. | +| `rule_disable` | `unknown` | User is disabling a rule. | +| `failure` | User is not authorized to disable a rule. | +| `rule_mute` | `unknown` | User is muting a rule. | +| `failure` | User is not authorized to mute a rule. | +| `rule_unmute` | `unknown` | User is unmuting a rule. | +| `failure` | User is not authorized to unmute a rule. | +| `rule_alert_mute` | `unknown` | User is muting an alert. | +| `failure` | User is not authorized to mute an alert. | +| `rule_alert_unmute` | `unknown` | User is unmuting an alert. | +| `failure` | User is not authorized to unmute an alert. | +| `space_update` | `unknown` | User is updating a space. | +| `failure` | User is not authorized to update a space. | +| `alert_update` | `unknown` | User is updating an alert. | +| `failure` | User is not authorized to update an alert. | +| `rule_snooze` | `unknown` | User is snoozing a rule. | +| `failure` | User is not authorized to snooze a rule. | +| `rule_unsnooze` | `unknown` | User is unsnoozing a rule. | +| `failure` | User is not authorized to unsnooze a rule. | +| `case_update` | `unknown` | User is updating a case. | +| `failure` | User is not authorized to update a case. | +| `case_push` | `unknown` | User is pushing a case to an external service. | +| `failure` | User is not authorized to push a case to an external service. | +| `case_configuration_update` | `unknown` | User is updating a case configuration. | +| `failure` | User is not authorized to update a case configuration. | +| `case_comment_update` | `unknown` | User is updating a case comment. | +| `failure` | User is not authorized to update a case comment. | +| `case_user_action_add_case_assignees` | `success` | User has added a case assignee. | +| `case_user_action_update_case_connector` | `success` | User has updated a case connector. | +| `case_user_action_update_case_description` | `success` | User has updated a case description. | +| `case_user_action_update_case_settings` | `success` | User has updated the case settings. | +| `case_user_action_update_case_severity` | `success` | User has updated the case severity. | +| `case_user_action_update_case_status` | `success` | User has updated the case status. | +| `case_user_action_pushed_case` | `success` | User has pushed a case to an external service. | +| `case_user_action_add_case_tags` | `success` | User has added tags to a case. | +| `case_user_action_update_case_title` | `success` | User has updated the case title. | +| `ml_open_ad_job` | `success` | Opening anomaly detection job. | +| `failure` | Failed to open anomaly detection job. | +| `ml_close_ad_job` | `success` | Closing anomaly detection job. | +| `failure` | Failed to close anomaly detection job. | +| `ml_start_ad_datafeed` | `success` | Starting anomaly detection datafeed. | +| `failure` | Failed to start anomaly detection datafeed. | +| `ml_stop_ad_datafeed` | `success` | Stopping anomaly detection datafeed. | +| `failure` | Failed to stop anomaly detection datafeed. | +| `ml_update_ad_job` | `success` | Updating anomaly detection job. | +| `failure` | Failed to update anomaly detection job. | +| `ml_reset_ad_job` | `success` | Resetting anomaly detection job. | +| `failure` | Failed to reset anomaly detection job. | +| `ml_revert_ad_snapshot` | `success` | Reverting anomaly detection snapshot. | +| `failure` | Failed to revert anomaly detection snapshot. | +| `ml_update_ad_datafeed` | `success` | Updating anomaly detection datafeed. | +| `failure` | Failed to update anomaly detection datafeed. | +| `ml_put_calendar_job` | `success` | Adding job to calendar. | +| `failure` | Failed to add job to calendar. | +| `ml_delete_calendar_job` | `success` | Removing job from calendar. | +| `failure` | Failed to remove job from calendar. | +| `ml_update_filter` | `success` | Updating filter. | +| `failure` | Failed to update filter. | +| `ml_start_dfa_job` | `success` | Starting data frame analytics job. | +| `failure` | Failed to start data frame analytics job. | +| `ml_stop_dfa_job` | `success` | Stopping data frame analytics job. | +| `failure` | Failed to stop data frame analytics job. | +| `ml_update_dfa_job` | `success` | Updating data frame analytics job. | +| `failure` | Failed to update data frame analytics job. | +| `ml_start_trained_model_deployment` | `success` | Starting trained model deployment. | +| `failure` | Failed to start trained model deployment. | +| `ml_stop_trained_model_deployment` | `success` | Stopping trained model deployment. | +| `failure` | Failed to stop trained model deployment. | +| `ml_update_trained_model_deployment` | `success` | Updating trained model deployment. | +| `failure` | Failed to update trained model deployment. | +| `product_documentation_update` | `unknown` | User requested to update the product documentation for use in AI Assistants. | +| ##### Type: deletion [_type_deletion]


| +| **Action** | **Outcome** | **Description** | +| `saved_object_delete` | `unknown` | User is deleting a saved object. | +| `failure` | User is not authorized to delete a saved object. | +| `saved_object_close_point_in_time` | `unknown` | User is deleting a Point In Time that was used to query saved objects. | +| `failure` | User is not authorized to delete a Point In Time. | +| `connector_delete` | `unknown` | User is deleting a connector. | +| `failure` | User is not authorized to delete a connector. | +| `rule_delete` | `unknown` | User is deleting a rule. | +| `failure` | User is not authorized to delete a rule. | +| `ad_hoc_run_delete` | `unknown` | User is deleting an ad hoc run. | +| `failure` | User is not authorized to delete an ad hoc run. | +| `space_delete` | `unknown` | User is deleting a space. | +| `failure` | User is not authorized to delete a space. | +| `case_delete` | `unknown` | User is deleting a case. | +| `failure` | User is not authorized to delete a case. | +| `case_comment_delete_all` | `unknown` | User is deleting all comments associated with a case. | +| `failure` | User is not authorized to delete all comments associated with a case. | +| `case_comment_delete` | `unknown` | User is deleting a case comment. | +| `failure` | User is not authorized to delete a case comment. | +| `case_user_action_delete_case_assignees` | `success` | User has removed a case assignee. | +| `case_user_action_delete_comment` | `success` | User has deleted a case comment. | +| `case_user_action_delete_case` | `success` | User has deleted a case. | +| `case_user_action_delete_case_tags` | `success` | User has removed tags from a case. | +| `ml_delete_ad_job` | `success` | Deleting anomaly detection job. | +| `failure` | Failed to delete anomaly detection job. | +| `ml_delete_model_snapshot` | `success` | Deleting model snapshot. | +| `failure` | Failed to delete model snapshot. | +| `ml_delete_ad_datafeed` | `success` | Deleting anomaly detection datafeed. | +| `failure` | Failed to delete anomaly detection datafeed. | +| `ml_delete_calendar` | `success` | Deleting calendar. | +| `failure` | Failed to delete calendar. | +| `ml_delete_calendar_event` | `success` | Deleting calendar event. | +| `failure` | Failed to delete calendar event. | +| `ml_delete_filter` | `success` | Deleting filter. | +| `failure` | Failed to delete filter. | +| `ml_delete_forecast` | `success` | Deleting forecast. | +| `failure` | Failed to delete forecast. | +| `ml_delete_dfa_job` | `success` | Deleting data frame analytics job. | +| `failure` | Failed to delete data frame analytics job. | +| `ml_delete_trained_model` | `success` | Deleting trained model. | +| `failure` | Failed to delete trained model. | +| `product_documentation_delete` | `unknown` | User requested to delete the product documentation for use in AI Assistants. | +| ##### Type: access [_type_access]


| +| **Action** | **Outcome** | **Description** | +| `saved_object_get` | `success` | User has accessed a saved object. | +| `failure` | User is not authorized to access a saved object. | +| `saved_object_resolve` | `success` | User has accessed a saved object. | +| `failure` | User is not authorized to access a saved object. | +| `saved_object_find` | `success` | User has accessed a saved object as part of a search operation. | +| `failure` | User is not authorized to search for saved objects. | +| `connector_get` | `success` | User has accessed a connector. | +| `failure` | User is not authorized to access a connector. | +| `connector_find` | `success` | User has accessed a connector as part of a search operation. | +| `failure` | User is not authorized to search for connectors. | +| `rule_get` | `success` | User has accessed a rule. | +| `failure` | User is not authorized to access a rule. | +| `rule_get_execution_log` | `success` | User has accessed execution log for a rule. | +| `failure` | User is not authorized to access execution log for a rule. | +| `rule_find` | `success` | User has accessed a rule as part of a search operation. | +| `failure` | User is not authorized to search for rules. | +| `rule_schedule_backfill` | `success` | User has accessed a rule as part of a backfill schedule operation. | +| `failure` | User is not authorized to access rule for backfill scheduling. | +| `ad_hoc_run_get` | `success` | User has accessed an ad hoc run. | +| `failure` | User is not authorized to access ad hoc run. | +| `ad_hoc_run_find` | `success` | User has accessed an ad hoc run as part of a search operation. | +| `failure` | User is not authorized to search for ad hoc runs. | +| `space_get` | `success` | User has accessed a space. | +| `failure` | User is not authorized to access a space. | +| `space_find` | `success` | User has accessed a space as part of a search operation. | +| `failure` | User is not authorized to search for spaces. | +| `alert_get` | `success` | User has accessed an alert. | +| `failure` | User is not authorized to access an alert. | +| `alert_find` | `success` | User has accessed an alert as part of a search operation. | +| `failure` | User is not authorized to access alerts. | +| `case_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_bulk_get` | `success` | User has accessed multiple cases. | +| `failure` | User is not authorized to access multiple cases. | +| `case_resolve` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_find` | `success` | User has accessed a case as part of a search operation. | +| `failure` | User is not authorized to search for cases. | +| `case_ids_by_alert_id_get` | `success` | User has accessed cases. | +| `failure` | User is not authorized to access cases. | +| `case_get_metrics` | `success` | User has accessed metrics for a case. | +| `failure` | User is not authorized to access metrics for a case. | +| `cases_get_metrics` | `success` | User has accessed metrics for cases. | +| `failure` | User is not authorized to access metrics for cases. | +| `case_configuration_find` | `success` | User has accessed a case configuration as part of a search operation. | +| `failure` | User is not authorized to search for case configurations. | +| `case_comment_get_metrics` | `success` | User has accessed metrics for case comments. | +| `failure` | User is not authorized to access metrics for case comments. | +| `case_comment_alerts_attach_to_case` | `success` | User has accessed case alerts. | +| `failure` | User is not authorized to access case alerts. | +| `case_comment_get` | `success` | User has accessed a case comment. | +| `failure` | User is not authorized to access a case comment. | +| `case_comment_bulk_get` | `success` | User has accessed multiple case comments. | +| `failure` | User is not authorized to access multiple case comments. | +| `case_comment_get_all` | `success` | User has accessed case comments. | +| `failure` | User is not authorized to access case comments. | +| `case_comment_find` | `success` | User has accessed a case comment as part of a search operation. | +| `failure` | User is not authorized to search for case comments. | +| `case_categories_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_tags_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_reporters_get` | `success` | User has accessed a case. | +| `failure` | User is not authorized to access a case. | +| `case_find_statuses` | `success` | User has accessed a case as part of a search operation. | +| `failure` | User is not authorized to search for cases. | +| `case_user_actions_get` | `success` | User has accessed the user activity of a case. | +| `failure` | User is not authorized to access the user activity of a case. | +| `case_user_actions_find` | `success` | User has accessed the user activity of a case as part of a search operation. | +| `failure` | User is not authorized to access the user activity of a case. | +| `case_user_action_get_metrics` | `success` | User has accessed metrics for the user activity of a case. | +| `failure` | User is not authorized to access metrics for the user activity of a case. | +| `case_user_action_get_users` | `success` | User has accessed the users associated with a case. | +| `failure` | User is not authorized to access the users associated with a case. | +| `case_connectors_get` | `success` | User has accessed the connectors of a case. | +| `failure` | User is not authorized to access the connectors of a case. | +| `ml_infer_trained_model` | `success` | Inferring using trained model. | +| `failure` | Failed to infer using trained model. | +| #### Category: web [_category_web]


| +| **Action** | **Outcome** | **Description** | +| `http_request` | `unknown` | User is making an HTTP request. | + + +## Audit schema [xpack-security-ecs-audit-schema] + +Audit logs are written in JSON using [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/1.6/index.html) specification. + +| | +| --- | +| #### Base Fields [_base_fields]


| +| **Field** | **Description** | +| `@timestamp` | Time when the event was generated.
Example: `2016-05-23T08:05:34.853Z` | +| `message` | Human readable description of the event. | +| #### Event Fields [_event_fields]


| +| **Field** | **Description** | +| $$$field-event-action$$$ `event.action` | The action captured by the event.
Refer to [Audit events](#xpack-security-ecs-audit-logging) for a table of possible actions. | +| $$$field-event-category$$$ `event.category` | High level category associated with the event.
This field is closely related to `event.type`, which is used as a subcategory.
Possible values:`database`,`web`,`authentication` | +| $$$field-event-type$$$ `event.type` | Subcategory associated with the event.
This field can be used along with the `event.category` field to enable filtering events down to a level appropriate for single visualization.
Possible values:`creation`,`access`,`change`,`deletion` | +| $$$field-event-outcome$$$ `event.outcome` | Denotes whether the event represents a success or failure:

* Any actions that the user is not authorized to perform are logged with outcome: `failure`
* Authorized read operations are only logged after successfully fetching the data from {{es}} with outcome: `success`
* Authorized create, update, or delete operations are logged before attempting the operation in {{es}} with outcome: `unknown`

Possible values: `success`, `failure`, `unknown`
| +| #### User Fields [_user_fields]


| +| **Field** | **Description** | +| `user.id` | Unique identifier of the user across sessions (See [user profiles](../../users-roles/cluster-or-deployment-auth/user-profiles.md)). | +| `user.name` | Login name of the user.
Example: `jdoe` | +| `user.roles[]` | Set of user roles at the time of the event.
Example: `[kibana_admin, reporting_user]` | +| #### Kibana Fields [_kibana_fields]


| +| **Field** | **Description** | +| `kibana.space_id` | ID of the space associated with the event.
Example: `default` | +| `kibana.session_id` | ID of the user session associated with the event.
Each login attempt results in a unique session id. | +| `kibana.saved_object.type` | Type of saved object associated with the event.
Example: `dashboard` | +| `kibana.saved_object.id` | ID of the saved object associated with the event. | +| `kibana.authentication_provider` | Name of the authentication provider associated with the event.
Example: `my-saml-provider` | +| `kibana.authentication_type` | Type of the authentication provider associated with the event.
Example: `saml` | +| `kibana.authentication_realm` | Name of the Elasticsearch realm that has authenticated the user.
Example: `native` | +| `kibana.lookup_realm` | Name of the Elasticsearch realm where the user details were retrieved from.
Example: `native` | +| `kibana.add_to_spaces[]` | Set of space IDs that a saved object is being shared to as part of the event.
Example: `[default, marketing]` | +| `kibana.delete_from_spaces[]` | Set of space IDs that a saved object is being removed from as part of the event.
Example: `[marketing]` | +| #### Error Fields [_error_fields]


| +| **Field** | **Description** | +| `error.code` | Error code describing the error. | +| `error.message` | Error message. | +| #### HTTP and URL Fields [_http_and_url_fields]


| +| **Field** | **Description** | +| `client.ip` | Client IP address. | +| `http.request.method` | HTTP request method.
Example: `get`, `post`, `put`, `delete` | +| `http.request.headers.x-forwarded-for` | `X-Forwarded-For` request header used to identify the originating client IP address when connecting through proxy servers.
Example: `161.66.20.177, 236.198.214.101` | +| `url.domain` | Domain of the URL.
Example: `www.elastic.co` | +| `url.path` | Path of the request.
Example: `/search` | +| `url.port` | Port of the request.
Example: `443` | +| `url.query` | The query field describes the query string of the request.
Example: `q=elasticsearch` | +| `url.scheme` | Scheme of the request.
Example: `https` | +| #### Tracing Fields [_tracing_fields]


| +| **Field** | **Description** | +| $$$field-trace-id$$$ `trace.id` | Unique identifier allowing events of the same transaction from {{kib}} and {{es}} to be correlated. | + + +## Correlating audit events [xpack-security-ecs-audit-correlation] + +Audit events can be correlated in two ways: + +1. Multiple {{kib}} audit events that resulted from the same request can be correlated together. +2. If [{{es}} audit logging](enabling-elasticsearch-audit-logs.md) is enabled, {{kib}} audit events from one request can be correlated with backend calls that create {{es}} audit events. + +::::{note} +The examples below are simplified, many fields have been omitted and values have been shortened for clarity. +:::: + + +### Example 1: correlating multiple {{kib}} audit events [_example_1_correlating_multiple_kib_audit_events] + +When "thom" creates a new alerting rule, five audit events are written: + +```json +{"event":{"action":"http_request","category":["web"],"outcome":"unknown"},"http":{"request":{"method":"post"}},"url":{"domain":"localhost","path":"/api/alerting/rule","port":5601,"scheme":"https"},"user":{"name":"thom","roles":["superuser"]},"kibana":{"space_id":"default","session_id":"3dHCZRB..."},"@timestamp":"2022-01-25T13:05:34.449-05:00","message":"User is requesting [/api/alerting/rule] endpoint","trace":{"id":"e300e06..."}} +{"event":{"action":"space_get","category":["database"],"type":["access"],"outcome":"success"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"space","id":"default"}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.454-05:00","message":"User has accessed space [id=default]","trace":{"id":"e300e06..."}} +{"event":{"action":"connector_get","category":["database"],"type":["access"],"outcome":"success"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"action","id":"5e3b1ae..."}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.948-05:00","message":"User has accessed connector [id=5e3b1ae...]","trace":{"id":"e300e06..."}} +{"event":{"action":"connector_get","category":["database"],"type":["access"],"outcome":"success"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"action","id":"5e3b1ae..."}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.956-05:00","message":"User has accessed connector [id=5e3b1ae...]","trace":{"id":"e300e06..."}} +{"event":{"action":"rule_create","category":["database"],"type":["creation"],"outcome":"unknown"},"kibana":{"space_id":"default","session_id":"3dHCZRB...","saved_object":{"type":"alert","id":"64517c3..."}},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T13:05:34.956-05:00","message":"User is creating rule [id=64517c3...]","trace":{"id":"e300e06..."}} +``` + +All of these audit events can be correlated together by the same `trace.id` value `"e300e06..."`. The first event is the HTTP API call, the next audit events are checks to validate the space and the connectors, and the last audit event is the actual rule creation. + + +### Example 2: correlating a {{kib}} audit event with {{es}} audit events [_example_2_correlating_a_kib_audit_event_with_es_audit_events] + +When "thom" logs in, a "user_login" {{kib}} audit event is written: + +```json +{"event":{"action":"user_login","category":["authentication"],"outcome":"success"},"kibana":{"session_id":"ab93zdA..."},"user":{"name":"thom","roles":["superuser"]},"@timestamp":"2022-01-25T09:40:39.267-05:00","message":"User [thom] has logged in using basic provider [name=basic]","trace":{"id":"818cbf3..."}} +``` + +The `trace.id` value `"818cbf3..."` in the {{kib}} audit event can be correlated with the `opaque_id` value in these six {{es}} audit events: + +```json +{"type":"audit", "timestamp":"2022-01-25T09:40:38,604-0500", "event.action":"access_granted", "user.name":"thom", "user.roles":["superuser"], "request.id":"YCx8wxs...", "action":"cluster:admin/xpack/security/user/authenticate", "request.name":"AuthenticateRequest", "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/index", "request.name":"IndexRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/bulk", "request.name":"BulkRequest", "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/bulk[s]", "request.name":"BulkShardRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/index:op_type/create", "request.name":"BulkItemRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +{"type":"audit", "timestamp":"2022-01-25T09:40:38,613-0500", "event.action":"access_granted", "user.name":"kibana_system", "user.roles":["kibana_system"], "request.id":"Ksx73Ad...", "action":"indices:data/write/bulk[s][p]", "request.name":"BulkShardRequest", "indices":[".kibana_security_session_1"], "opaque_id":"818cbf3..."} +``` + +The {{es}} audit events show that "thom" authenticated, then subsequently "kibana_system" created a session for that user. diff --git a/deploy-manage/monitor/logging-configuration/kibana-logging.md b/deploy-manage/monitor/logging-configuration/kibana-logging.md new file mode 100644 index 000000000..deca01a3a --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/kibana-logging.md @@ -0,0 +1,394 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/logging-configuration.html +--- + +# Kibana logging [logging-configuration] + +The {{kib}} logging system has three main components: *loggers*, *appenders* and *layouts*. These components allow us to log messages according to message type and level, to control how these messages are formatted and where the final logs will be displayed or stored. + +* [Loggers, Appenders and Layouts](#loggers-appenders-layout) +* [Log level](#log-level) +* [Layouts](#logging-layouts) +* [Logger hierarchy](#logger-hierarchy) + + +## Loggers, Appenders and Layouts [loggers-appenders-layout] + +*Loggers* define what logging settings should be applied to a particular logger. + +*[Appenders](#logging-appenders)* define where log messages are displayed (eg. stdout or console) and stored (eg. file on the disk). + +*[Layouts](#logging-layouts)* define how log messages are formatted and what type of information they include. + + +## Log level [log-level] + +Currently we support the following log levels: *off*, *fatal*, *error*, *warn*, *info*, *debug*, *trace*, *all*. + +Levels are ordered, so *off* > *fatal* > *error* > *warn* > *info* > *debug* > *trace* > *all*. + +A log record will be logged by the logger if its level is higher than or equal to the level of its logger. For example: If the output of an API call is configured to log at the `info` level and the parameters passed to the API call are set to `debug`, with a global logging configuration in `kibana.yml` set to `debug`, both the output *and* parameters are logged. If the log level is set to `info`, the debug logs are ignored, meaning that you’ll only get a record for the API output and *not* for the parameters. + +Logging set at a plugin level is always respected, regardless of the `root` logger level. In other words, if root logger is set to fatal and pluginA logging is set to `debug`, debug logs are only shown for pluginA, with other logs only reporting on `fatal`. + +The *all* and *off* levels can only be used in configuration and are handy shortcuts that allow you to log every log record or disable logging entirely for a specific logger. These levels can also be specified using [cli arguments](_cli_configuration.md#logging-cli-migration). + + +## Layouts [logging-layouts] + +Every appender should know exactly how to format log messages before they are written to the console or file on the disk. This behavior is controlled by the layouts and configured through `appender.layout` configuration property for every custom appender. Currently we don’t define any default layout for the custom appenders, so one should always make the choice explicitly. + +There are two types of layout supported at the moment: [`pattern`](#pattern-layout) and [`json`](#json-layout). + + +### Pattern layout [pattern-layout] + +With `pattern` layout it’s possible to define a string pattern with special placeholders `%conversion_pattern` that will be replaced with data from the actual log message. By default the following pattern is used: `[%date][%level][%logger] %message`. + +::::{note} +The `pattern` layout uses a sub-set of [log4j 2 pattern syntax](https://logging.apache.org/log4j/2.x/manual/layouts.md#PatternLayout) and **doesn’t implement** all `log4j 2` capabilities. +:::: + + +The conversions that are provided out of the box are: + +**level** Outputs the [level](#log-level) of the logging event. Example of `%level` output: `TRACE`, `DEBUG`, `INFO`. + +**logger** Outputs the name of the logger that published the logging event. Example of `%logger` output: `server`, `server.http`, `server.http.kibana`. + +**message** Outputs the application supplied message associated with the logging event. + +**meta*** Outputs the entries of `meta` object data in ***json** format, if one is present in the event. Example of `%meta` output: + +```bash +// Meta{from: 'v7', to: 'v8'} +'{"from":"v7","to":"v8"}' +// Meta empty object +'{}' +// no Meta provided +'' +``` + +$$$date-format$$$ +**date** Outputs the date of the logging event. The date conversion specifier may be followed by a set of braces containing a name of predefined date format and canonical timezone name. Timezone name is expected to be one from [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Timezone defaults to the host timezone when not explicitly specified. Example of `%date` output: + +$$$date-conversion-pattern-examples$$$ + +| Conversion pattern | Example | +| --- | --- | +| `%date` | `2012-02-01T14:30:22.011Z` uses `ISO8601` format by default | +| `%date{{ISO8601}}` | `2012-02-01T14:30:22.011Z` | +| `%date{{ISO8601_TZ}}` | `2012-02-01T09:30:22.011-05:00` `ISO8601` with timezone | +| `%date{{ISO8601_TZ}}{America/Los_Angeles}` | `2012-02-01T06:30:22.011-08:00` | +| `%date{{ABSOLUTE}}` | `09:30:22.011` | +| `%date{{ABSOLUTE}}{America/Los_Angeles}` | `06:30:22.011` | +| `%date{{UNIX}}` | `1328106622` | +| `%date{{UNIX_MILLIS}}` | `1328106622011` | + +**pid** Outputs the process ID. + +The pattern layout also offers a `highlight` option that allows you to highlight some parts of the log message with different colors. Highlighting is quite handy if log messages are forwarded to a terminal with color support. + + +### JSON layout [json-layout] + +With `json` layout log messages will be formatted as JSON strings in [ECS format](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html) that includes a timestamp, log level, logger, message text and any other metadata that may be associated with the log message itself. + + +## Logger hierarchy [logger-hierarchy] + +Every logger has a unique name that follows a hierarchical naming rule. The logger is considered to be an ancestor of another logger if its name followed by a `.` is a prefix of the descendant logger. For example, a logger named `a.b` is an ancestor of logger `a.b.c`. All top-level loggers are descendants of a special `root` logger at the top of the logger hierarchy. The `root` logger always exists, is fully configured and logs to `info` level by default. The `root` logger must also be configured if any other logging configuration is specified in your `kibana.yml`. + +You can configure *[log level](#log-level)* and *appenders* for a specific logger. If a logger only has a *log level* configured, then the *appenders* configuration applied to the logger is inherited from the ancestor logger, up to the `root` logger. + +::::{note} +In the current implementation we *don’t support* so called *appender additivity* when log messages are forwarded to *every* distinct appender within the ancestor chain including `root`. That means that log messages are only forwarded to appenders that are configured for a particular logger. If a logger doesn’t have any appenders configured, the configuration of that particular logger will be inherited from its closest ancestor. +:::: + + + +#### Dedicated loggers [dedicated-loggers] + +**Root** + +The `root` logger has a dedicated configuration node since this logger is special and should always exist. By default `root` is configured with `info` level and `default` appender that is also always available. This is the configuration that all custom loggers will use unless they’re re-configured explicitly. + +For example to see *all* log messages that fall back on the `root` logger configuration, just add one line to the configuration: + +```yaml +logging.root.level: all +``` + +Or disable logging entirely with `off`: + +```yaml +logging.root.level: off +``` + +**Metrics Logs** + +The `metrics.ops` logger is configured with `debug` level and will automatically output sample system and process information at a regular interval. The metrics that are logged are a subset of the data collected and are formatted in the log message as follows: + +| Ops formatted log property | Location in metrics service | Log units | +| --- | --- | --- | +| memory | process.memory.heap.used_in_bytes | [depends on the value](http://numeraljs.com/#format), typically MB or GB | +| uptime | process.uptime_in_millis | HH:mm:ss | +| load | os.load | [ "load for the last 1 min" "load for the last 5 min" "load for the last 15 min"] | +| delay | process.event_loop_delay | ms | + +The log interval is the same as the interval at which system and process information is refreshed and is configurable under `ops.interval`: + +```yaml +ops.interval: 5000 +``` + +The minimum interval is 100ms and defaults to 5000ms. + +$$$request-response-logger$$$ +**Request and Response Logs** + +The `http.server.response` logger is configured with `debug` level and will automatically output data about http requests and responses occurring on the {{kib}} server. The message contains some high-level information, and the corresponding log meta contains the following: + +| Meta property | Description | Format | +| --- | --- | --- | +| client.ip | IP address of the requesting client | ip | +| http.request.method | http verb for the request (uppercase) | string | +| http.request.mime_type | (optional) mime as specified in the headers | string | +| http.request.referrer | (optional) referrer | string | +| http.request.headers | request headers | object | +| http.response.body.bytes | (optional) Calculated response payload size in bytes | number | +| http.response.status_code | status code returned | number | +| http.response.headers | response headers | object | +| http.response.responseTime | (optional) Calculated response time in ms | number | +| url.path | request path | string | +| url.query | (optional) request query string | string | +| user_agent.original | raw user-agent string provided in request headers | string | + + +## Appenders [logging-appenders] + + +### Rolling File Appender [rolling-file-appender] + +Similar to Log4j’s `RollingFileAppender`, this appender will log into a file, and rotate it following a rolling strategy when the configured policy triggers. + + +##### Triggering Policies [_triggering_policies] + +The triggering policy determines when a rollover should occur. + +There are currently two policies supported: `size-limit` and `time-interval`. + +$$$size-limit-triggering-policy$$$ +**Size-limit triggering policy** + +This policy will rotate the file when it reaches a predetermined size. + +```yaml +logging: + appenders: + rolling-file: + type: rolling-file + fileName: /var/logs/kibana.log + policy: + type: size-limit + size: 50mb + strategy: + //... + layout: + type: pattern +``` + +The options are: + +* `size` + +The maximum size the log file should reach before a rollover should be performed. The default value is `100mb` + +$$$time-interval-triggering-policy$$$ +**Time-interval triggering policy** + +This policy will rotate the file every given interval of time. + +```yaml +logging: + appenders: + rolling-file: + type: rolling-file + fileName: /var/logs/kibana.log + policy: + type: time-interval + interval: 10s + modulate: true + strategy: + //... + layout: + type: pattern +``` + +The options are: + +* `interval` + +How often a rollover should occur. The default value is `24h` + +* `modulate` + +Whether the interval should be adjusted to cause the next rollover to occur on the interval boundary. + +For example, if modulate is true and the interval is `4h`, if the current hour is 3 am then the first rollover will occur at 4 am and then next ones will occur at 8 am, noon, 4pm, etc. The default value is `true`. + + +#### Rolling strategies [_rolling_strategies] + +The rolling strategy determines how the rollover should occur: both the naming of the rolled files, and their retention policy. + +There is currently one strategy supported: `numeric`. + +**Numeric rolling strategy** + +This strategy will suffix the file with a given pattern when rolling, and will retains a fixed amount of rolled files. + +```yaml +logging: + appenders: + rolling-file: + type: rolling-file + fileName: /var/logs/kibana.log + policy: + // ... + strategy: + type: numeric + pattern: '-%i' + max: 2 + layout: + type: pattern +``` + +For example, with this configuration: + +* During the first rollover kibana.log is renamed to kibana-1.log. A new kibana.log file is created and starts being written to. +* During the second rollover kibana-1.log is renamed to kibana-2.log and kibana.log is renamed to kibana-1.log. A new kibana.log file is created and starts being written to. +* During the third and subsequent rollovers, kibana-2.log is deleted, kibana-1.log is renamed to kibana-2.log and kibana.log is renamed to kibana-1.log. A new kibana.log file is created and starts being written to. + +The options are: + +* `pattern` + +The suffix to append to the file path when rolling. Must include `%i`, as this is the value that will be converted to the file index. + +For example, with `fileName: /var/logs/kibana.log` and `pattern: '-%i'`, the rolling files created will be `/var/logs/kibana-1.log`, `/var/logs/kibana-2.log`, and so on. The default value is `-%i` + +* `max` + +The maximum number of files to keep. Once this number is reached, oldest files will be deleted. The default value is `7` + + +### Rewrite appender [rewrite-appender] + +::::{warning} +This appender is currently considered experimental and is not intended for public consumption. The API is subject to change at any time. +:::: + + +Similar to log4j’s `RewriteAppender`, this appender serves as a sort of middleware, modifying the provided log events before passing them along to another appender. + +```yaml +logging: + appenders: + my-rewrite-appender: + type: rewrite + appenders: [console, file] # name of "destination" appender(s) + policy: + # ... +``` + +The most common use case for the `RewriteAppender` is when you want to filter or censor sensitive data that may be contained in a log entry. In fact, with a default configuration, {{kib}} will automatically redact any `authorization`, `cookie`, or `set-cookie` headers when logging http requests & responses. + +To configure additional rewrite rules, you’ll need to specify a [`RewritePolicy`](#rewrite-policies). + + +##### Rewrite policies [rewrite-policies] + +Rewrite policies exist to indicate which parts of a log record can be modified within the rewrite appender. + +**Meta** + +The `meta` rewrite policy can read and modify any data contained in the `LogMeta` before passing it along to a destination appender. + +Meta policies must specify one of three modes, which indicate which action to perform on the configured properties: - `update` updates an existing property at the provided `path`. - `remove` removes an existing property at the provided `path`. + +The `properties` are listed as a `path` and `value` pair, where `path` is the dot-delimited path to the target property in the `LogMeta` object, and `value` is the value to add or update in that target property. When using the `remove` mode, a `value` is not necessary. + +Here’s an example of how you would replace any `cookie` header values with `[REDACTED]`: + +```yaml +logging: + appenders: + my-rewrite-appender: + type: rewrite + appenders: [console] + policy: + type: meta # indicates that we want to rewrite the LogMeta + mode: update # will update an existing property only + properties: + - path: "http.request.headers.cookie" # path to property + value: "[REDACTED]" # value to replace at path +``` + +Rewrite appenders can even be passed to other rewrite appenders to apply multiple filter policies/modes, as long as it doesn’t create a circular reference. Each rewrite appender is applied sequentially (one after the other). + +```yaml +logging: + appenders: + remove-request-headers: + type: rewrite + appenders: [censor-response-headers] # redirect to the next rewrite appender + policy: + type: meta + mode: remove + properties: + - path: "http.request.headers" # remove all request headers + censor-response-headers: + type: rewrite + appenders: [console] # output to console + policy: + type: meta + mode: update + properties: + - path: "http.response.headers.set-cookie" + value: "[REDACTED]" +``` + + +##### Complete Example For Rewrite Appender [_complete_example_for_rewrite_appender] + +```yaml +logging: + appenders: + custom_console: + type: console + layout: + type: pattern + highlight: true + pattern: "[%date][%level][%logger] %message %meta" + file: + type: file + fileName: ./kibana.log + layout: + type: json + censor: + type: rewrite + appenders: [custom_console, file] + policy: + type: meta + mode: update + properties: + - path: "http.request.headers.cookie" + value: "[REDACTED]" + loggers: + - name: http.server.response + appenders: [censor] # pass these logs to our rewrite appender + level: debug +``` diff --git a/deploy-manage/monitor/logging-configuration/log-settings-examples.md b/deploy-manage/monitor/logging-configuration/log-settings-examples.md new file mode 100644 index 000000000..aa7dfc035 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/log-settings-examples.md @@ -0,0 +1,148 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/log-settings-examples.html +--- + +# Examples [log-settings-examples] + +Here are some configuration examples for the most common logging use cases: + + +## Log to a file [log-to-file-example] + +Log the default log format to a file instead of to stdout (the default). + +```yaml +logging: + appenders: + file: + type: file + fileName: /var/log/kibana.log + layout: + type: pattern + root: + appenders: [file] +``` + + +## Log in JSON format [log-in-json-ECS-example] + +Log the default log format to JSON layout instead of pattern (the default). With `json` layout, log messages will be formatted as JSON strings in [ECS format](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html) that includes a timestamp, log level, logger, message text and any other metadata that may be associated with the log message itself. + +```yaml +logging: + appenders: + json-layout: + type: console + layout: + type: json + root: + appenders: [json-layout] +``` + + +## Log with meta to stdout [log-with-meta-to-stdout] + +Include `%meta` in your pattern layout: + +```yaml +logging: + appenders: + console-meta: + type: console + layout: + type: pattern + pattern: "[%date] [%level] [%logger] [%meta] %message" + root: + appenders: [console-meta] +``` + + +## Log {{es}} queries [log-elasticsearch-queries] + +```yaml +logging: + appenders: + console_appender: + type: console + layout: + type: pattern + highlight: true + root: + appenders: [console_appender] + level: warn + loggers: + - name: elasticsearch.query + level: debug +``` + + +## Change overall log level [change-overall-log-level] + +```yaml +logging: + root: + level: debug +``` + + +## Customize specific log records [customize-specific-log-records] + +Here is a detailed configuration example that can be used to configure *loggers*, *appenders* and *layouts*: + +```yaml +logging: + appenders: + console: + type: console + layout: + type: pattern + highlight: true + file: + type: file + fileName: /var/log/kibana.log + custom: + type: console + layout: + type: pattern + pattern: "[%date][%level] %message" + json-file-appender: + type: file + fileName: /var/log/kibana-json.log + layout: + type: json + + root: + appenders: [console, file] + level: error + + loggers: + - name: plugins + appenders: [custom] + level: warn + - name: plugins.myPlugin + level: info + - name: server + level: fatal + - name: optimize + appenders: [console] + - name: telemetry + appenders: [json-file-appender] + level: all + - name: metrics.ops + appenders: [console] + level: debug +``` + +Here is what we get with the config above: + +| Context name | Appenders | Level | +| --- | --- | --- | +| root | console, file | error | +| plugins | custom | warn | +| plugins.myPlugin | custom | info | +| server | console, file | fatal | +| optimize | console | error | +| telemetry | json-file-appender | all | +| metrics.ops | console | debug | + diff --git a/deploy-manage/monitor/logging-configuration/logfile-audit-events-ignore-policies.md b/deploy-manage/monitor/logging-configuration/logfile-audit-events-ignore-policies.md new file mode 100644 index 000000000..19ab65fc3 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/logfile-audit-events-ignore-policies.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/audit-log-ignore-policy.html +--- + +# Logfile audit events ignore policies [audit-log-ignore-policy] + +The comprehensive audit trail is necessary to ensure accountability. It offers tremendous value during incident response and can even be required for demonstrating compliance. + +The drawback of an audited system is represented by the inevitable performance penalty incurred. In all truth, the audit trail spends *I/O ops* that are not available anymore for the user’s queries. Sometimes the verbosity of the audit trail may become a problem that the event type restrictions, [defined by `include` and `exclude`](logfile-audit-output.md#audit-log-settings), will not alleviate. + +**Audit events ignore policies** are a finer way to tune the verbosity of the audit trail. These policies define rules that match audit events which will be *ignored* (read as: not printed). Rules match on the values of attributes of audit events and complement the `include` or `exclude` method. Imagine the corpus of audit events and the policies chopping off unwanted events. With a sole exception, all audit events are subject to the ignore policies. The exception are events of type `security_config_change`, which cannot be filtered out, unless excluded altogether. + +::::{important} +When utilizing audit events ignore policies you are acknowledging potential accountability gaps that could render illegitimate actions undetectable. Please take time to review these policies whenever your system architecture changes. +:::: + + +A policy is a named set of filter rules. Each filter rule applies to a single event attribute, one of the `users`, `realms`, `actions`, `roles` or `indices` attributes. The filter rule defines a list of [Lucene regexp](https://www.elastic.co/guide/en/elasticsearch/reference/current/regexp-syntax.html), **any** of which has to match the value of the audit event attribute for the rule to match. A policy matches an event if **all** the rules comprising it match the event. An audit event is ignored, therefore not printed, if it matches **any** policy. All other non-matching events are printed as usual. + +All policies are defined under the `xpack.security.audit.logfile.events.ignore_filters` settings namespace. For example, the following policy named *example1* matches events from the *kibana_system* or *admin_user* principals that operate over indices of the wildcard form *app-logs**: + +```yaml +xpack.security.audit.logfile.events.ignore_filters: + example1: + users: ["kibana_system", "admin_user"] + indices: ["app-logs*"] +``` + +An audit event generated by the *kibana_system* user and operating over multiple indices , some of which do not match the indices wildcard, will not match. As expected, operations generated by all other users (even operating only on indices that match the *indices* filter) will not match this policy either. + +Audit events of different types may have [different attributes](elasticsearch-audit-events.md#audit-event-attributes). If an event does not contain an attribute for which some policy defines filters, the event will not match the policy. For example, the following policy will never match `authentication_success` or `authentication_failed` events, irrespective of the user’s roles, because these event schemas do not contain the `role` attribute: + +```yaml +xpack.security.audit.logfile.events.ignore_filters: + example2: + roles: ["admin", "ops_admin_*"] +``` + +Likewise, any events of users with multiple roles, some of which do not match the regexps will not match this policy. + +For completeness, although practical use cases should be sparse, a filter can match a missing attribute of an event, using the empty string ("") or the empty list ([]). For example, the following policy will match events that do not have the `indices` attribute (`anonymous_access_denied`, `authentication_success` and other types) as well as events over the *next* index. + +```yaml +xpack.security.audit.logfile.events.ignore_filters: + example3: + indices: ["next", ""] +``` + diff --git a/deploy-manage/monitor/logging-configuration/logfile-audit-output.md b/deploy-manage/monitor/logging-configuration/logfile-audit-output.md new file mode 100644 index 000000000..68f98eff1 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/logfile-audit-output.md @@ -0,0 +1,37 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/audit-log-output.html +--- + +# Logfile audit output [audit-log-output] + +The `logfile` audit output is the only output for auditing. It writes data to the `_audit.json` file in the logs directory. + +::::{note} +If you overwrite the `log4j2.properties` and do not specify appenders for any of the audit trails, audit events are forwarded to the root appender, which by default points to the `elasticsearch.log` file. +:::: + + + +## Log entry format [audit-log-entry-format] + +The audit events are formatted as JSON documents, and each event is printed on a separate line in the `_audit.json` file. The entries themselves do not contain the end-of-line delimiter. The audit event JSON format is somewhat particular, as **most** fields follow a dotted name syntax, are ordered, and contain non-null string values. This format creates a structured columnar aspect, similar to a CSV, that can be more easily inspected visually (compared to an equivalent nested JSON document). + +There are however a few attributes that are exceptions to the above format. The `put`, `delete`, `change`, `create` and `invalidate` attributes, which are only present for events with the `event.type: "security_config_change"` attribute, contain the **nested JSON** representation of the security change taking effect. The contents of the security config change are hence not displayed as top-level dot-named fields in the audit event document. That’s because the fields are specific to the particular kind of security change and do not show up in any other audit events. The benefits of a columnar format are therefore much more limited; the space-saving benefits of the nested structure is the favoured trade-off in this case. + +When the `request.body` attribute is present (see [Auditing search queries](auditing-search-queries.md)), it contains a string value containing the full HTTP request body, escaped as per the JSON RFC 4677. + +There is a list of [audit event types](elasticsearch-audit-events.md) specifying the set of fields, as well as examples, for each entry type. + + +## Logfile output settings [audit-log-settings] + +The events and some other information about what gets logged can be controlled using settings in the `elasticsearch.yml` file. See [Audited Event Settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#event-audit-settings) and [Local Node Info Settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#node-audit-settings). + +::::{important} +Be advised that **sensitive data may be audited in plain text** when including the request body in audit events, even though all the security APIs, such as those that change the user’s password, have the credentials filtered out when audited. +:::: + + +You can also configure how the logfile is written in the `log4j2.properties` file located in `ES_PATH_CONF` (or check out the relevant portion of the [log4j2.properties in the sources](https://github.com/elastic/elasticsearch/blob/master/x-pack/plugin/core/src/main/config/log4j2.properties)). By default, audit information is appended to the `_audit.json` file located in the standard Elasticsearch `logs` directory (typically located at `$ES_HOME/logs`). The file is also rotated and archived daily or upon reaching the 1GB file size limit. + diff --git a/deploy-manage/monitor/logging-configuration/security-event-audit-logging.md b/deploy-manage/monitor/logging-configuration/security-event-audit-logging.md new file mode 100644 index 000000000..9685480bc --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/security-event-audit-logging.md @@ -0,0 +1,7 @@ +# Security event audit logging + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: Landing page about audit logs in Kibana and Elasticsearch, explaining how they can be enabled and configured, and also linking to the page about correlating information. We can create a doc to explain how to enable audit logging in both Elasticsearch and Kibana, and considering also ECE and orchestrated deployments. Kibana audit events list should be moved to reference content. \ No newline at end of file diff --git a/deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md b/deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md new file mode 100644 index 000000000..e25780af6 --- /dev/null +++ b/deploy-manage/monitor/logging-configuration/update-elasticsearch-logging-levels.md @@ -0,0 +1,289 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/logging.html +--- + +# Update Elasticsearch logging levels [logging] + +You can use {{es}}'s application logs to monitor your cluster and diagnose issues. If you run {{es}} as a service, the default location of the logs varies based on your platform and installation method: + +:::::::{tab-set} + +::::::{tab-item} Docker +On [Docker](../../deploy/self-managed/install-elasticsearch-with-docker.md), log messages go to the console and are handled by the configured Docker logging driver. To access logs, run `docker logs`. +:::::: + +::::::{tab-item} Debian (APT) +For [Debian installations](../../deploy/self-managed/install-elasticsearch-with-debian-package.md), {{es}} writes logs to `/var/log/elasticsearch`. +:::::: + +::::::{tab-item} RPM +For [RPM installations](../../deploy/self-managed/install-elasticsearch-with-rpm.md), {{es}} writes logs to `/var/log/elasticsearch`. +:::::: + +::::::{tab-item} macOS +For [macOS `.tar.gz`](../../deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md) installations, {{es}} writes logs to `$ES_HOME/logs`. + +Files in `$ES_HOME` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `$ES_HOME`. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::{tab-item} Linux +For [Linux `.tar.gz`](../../deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md) installations, {{es}} writes logs to `$ES_HOME/logs`. + +Files in `$ES_HOME` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `$ES_HOME`. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::{tab-item} Windows .zip +For [Windows `.zip`](../../deploy/self-managed/install-elasticsearch-with-zip-on-windows.md) installations, {{es}} writes logs to `%ES_HOME%\logs`. + +Files in `%ES_HOME%` risk deletion during an upgrade. In production, we strongly recommend you set `path.logs` to a location outside of `%ES_HOME%``. See [Path settings](../../deploy/self-managed/important-settings-configuration.md#path-settings). +:::::: + +::::::: +If you run {{es}} from the command line, {{es}} prints logs to the standard output (`stdout`). + + +## Logging configuration [logging-configuration] + +::::{important} +Elastic strongly recommends using the Log4j 2 configuration that is shipped by default. +:::: + + +Elasticsearch uses [Log4j 2](https://logging.apache.org/log4j/2.x/) for logging. Log4j 2 can be configured using the log4j2.properties file. Elasticsearch exposes three properties, `${sys:es.logs.base_path}`, `${sys:es.logs.cluster_name}`, and `${sys:es.logs.node_name}` that can be referenced in the configuration file to determine the location of the log files. The property `${sys:es.logs.base_path}` will resolve to the log directory, `${sys:es.logs.cluster_name}` will resolve to the cluster name (used as the prefix of log filenames in the default configuration), and `${sys:es.logs.node_name}` will resolve to the node name (if the node name is explicitly set). + +For example, if your log directory (`path.logs`) is `/var/log/elasticsearch` and your cluster is named `production` then `${sys:es.logs.base_path}` will resolve to `/var/log/elasticsearch` and `${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}.log` will resolve to `/var/log/elasticsearch/production.log`. + +```properties +####### Server JSON ############################ +appender.rolling.type = RollingFile <1> +appender.rolling.name = rolling +appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.json <2> +appender.rolling.layout.type = ECSJsonLayout <3> +appender.rolling.layout.dataset = elasticsearch.server <4> +appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.json.gz <5> +appender.rolling.policies.type = Policies +appender.rolling.policies.time.type = TimeBasedTriggeringPolicy <6> +appender.rolling.policies.time.interval = 1 <7> +appender.rolling.policies.time.modulate = true <8> +appender.rolling.policies.size.type = SizeBasedTriggeringPolicy <9> +appender.rolling.policies.size.size = 256MB <10> +appender.rolling.strategy.type = DefaultRolloverStrategy +appender.rolling.strategy.fileIndex = nomax +appender.rolling.strategy.action.type = Delete <11> +appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} +appender.rolling.strategy.action.condition.type = IfFileName <12> +appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* <13> +appender.rolling.strategy.action.condition.nested_condition.type = IfAccumulatedFileSize <14> +appender.rolling.strategy.action.condition.nested_condition.exceeds = 2GB <15> +################################################ +``` + +1. Configure the `RollingFile` appender +2. Log to `/var/log/elasticsearch/production_server.json` +3. Use JSON layout. +4. `dataset` is a flag populating the `event.dataset` field in a `ECSJsonLayout`. It can be used to distinguish different types of logs more easily when parsing them. +5. Roll logs to `/var/log/elasticsearch/production-yyyy-MM-dd-i.json`; logs will be compressed on each roll and `i` will be incremented +6. Use a time-based roll policy +7. Roll logs on a daily basis +8. Align rolls on the day boundary (as opposed to rolling every twenty-four hours) +9. Using a size-based roll policy +10. Roll logs after 256 MB +11. Use a delete action when rolling logs +12. Only delete logs matching a file pattern +13. The pattern is to only delete the main logs +14. Only delete if we have accumulated too many compressed logs +15. The size condition on the compressed logs is 2 GB + + +```properties +####### Server - old style pattern ########### +appender.rolling_old.type = RollingFile +appender.rolling_old.name = rolling_old +appender.rolling_old.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.log <1> +appender.rolling_old.layout.type = PatternLayout +appender.rolling_old.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %m%n +appender.rolling_old.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.old_log.gz +``` + +1. The configuration for `old style` pattern appenders. These logs will be saved in `*.log` files and if archived will be in `* .log.gz` files. Note that these should be considered deprecated and will be removed in the future. + + +::::{note} +Log4j’s configuration parsing gets confused by any extraneous whitespace; if you copy and paste any Log4j settings on this page, or enter any Log4j configuration in general, be sure to trim any leading and trailing whitespace. +:::: + + +Note than you can replace `.gz` by `.zip` in `appender.rolling.filePattern` to compress the rolled logs using the zip format. If you remove the `.gz` extension then logs will not be compressed as they are rolled. + +If you want to retain log files for a specified period of time, you can use a rollover strategy with a delete action. + +```properties +appender.rolling.strategy.type = DefaultRolloverStrategy <1> +appender.rolling.strategy.action.type = Delete <2> +appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} <3> +appender.rolling.strategy.action.condition.type = IfFileName <4> +appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* <5> +appender.rolling.strategy.action.condition.nested_condition.type = IfLastModified <6> +appender.rolling.strategy.action.condition.nested_condition.age = 7D <7> +``` + +1. Configure the `DefaultRolloverStrategy` +2. Configure the `Delete` action for handling rollovers +3. The base path to the Elasticsearch logs +4. The condition to apply when handling rollovers +5. Delete files from the base path matching the glob `${sys:es.logs.cluster_name}-*`; this is the glob that log files are rolled to; this is needed to only delete the rolled Elasticsearch logs but not also delete the deprecation and slow logs +6. A nested condition to apply to files matching the glob +7. Retain logs for seven days + + +Multiple configuration files can be loaded (in which case they will get merged) as long as they are named `log4j2.properties` and have the Elasticsearch config directory as an ancestor; this is useful for plugins that expose additional loggers. The logger section contains the java packages and their corresponding log level. The appender section contains the destinations for the logs. Extensive information on how to customize logging and all the supported appenders can be found on the [Log4j documentation](https://logging.apache.org/log4j/2.x/manual/configuration.md). + + +## Configuring logging levels [configuring-logging-levels] + +Log4J 2 log messages include a *level* field, which is one of the following (in order of increasing verbosity): + +* `FATAL` +* `ERROR` +* `WARN` +* `INFO` +* `DEBUG` +* `TRACE` + +By default {{es}} includes all messages at levels `INFO`, `WARN`, `ERROR` and `FATAL` in its logs, but filters out messages at levels `DEBUG` and `TRACE`. This is the recommended configuration. Do not filter out messages at `INFO` or higher log levels or else you may not be able to understand your cluster’s behaviour or troubleshoot common problems. Do not enable logging at levels `DEBUG` or `TRACE` unless you are following instructions elsewhere in this manual which call for more detailed logging, or you are an expert user who will be reading the {{es}} source code to determine the meaning of the logs. + +Messages are logged by a hierarchy of loggers which matches the hierarchy of Java packages and classes in the [{{es}} source code](https://github.com/elastic/elasticsearch/). Every logger has a corresponding [dynamic setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) which can be used to control the verbosity of its logs. The setting’s name is the fully-qualified name of the package or class, prefixed with `logger.`. + +You may set each logger’s verbosity to the name of a log level, for instance `DEBUG`, which means that messages from this logger at levels up to the specified one will be included in the logs. You may also use the value `OFF` to suppress all messages from the logger. + +For example, the `org.elasticsearch.discovery` package contains functionality related to the [discovery](../../distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md) process, and you can control the verbosity of its logs with the `logger.org.elasticsearch.discovery` setting. To enable `DEBUG` logging for this package, use the [Cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) as follows: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.discovery": "DEBUG" + } +} +``` + +To reset this package’s log verbosity to its default level, set the logger setting to `null`: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.discovery": null + } +} +``` + +Other ways to change log levels include: + +1. `elasticsearch.yml`: + + ```yaml + logger.org.elasticsearch.discovery: DEBUG + ``` + + This is most appropriate when debugging a problem on a single node. + +2. `log4j2.properties`: + + ```properties + logger.discovery.name = org.elasticsearch.discovery + logger.discovery.level = debug + ``` + + This is most appropriate when you already need to change your Log4j 2 configuration for other reasons. For example, you may want to send logs for a particular logger to another file. However, these use cases are rare. + + +::::{important} +{{es}}'s application logs are intended for humans to read and interpret. Different versions of {{es}} may report information in these logs in different ways, perhaps adding extra detail, removing unnecessary information, formatting the same information in different ways, renaming the logger or adjusting the log level for specific messages. Do not rely on the contents of the application logs remaining precisely the same between versions. +:::: + + +::::{note} +To prevent leaking sensitive information in logs, {{es}} suppresses certain log messages by default even at the highest verbosity levels. To disable this protection on a node, set the Java system property `es.insecure_network_trace_enabled` to `true`. This feature is primarily intended for test systems which do not contain any sensitive information. If you set this property on a system which contains sensitive information, you must protect your logs from unauthorized access. +:::: + + + +## Deprecation logging [deprecation-logging] + +{{es}} also writes deprecation logs to the log directory. These logs record a message when you use deprecated {{es}} functionality. You can use the deprecation logs to update your application before upgrading {{es}} to a new major version. + +By default, {{es}} rolls and compresses deprecation logs at 1GB. The default configuration preserves a maximum of five log files: four rolled logs and an active log. + +{{es}} emits deprecation log messages at the `CRITICAL` level. Those messages are indicating that a used deprecation feature will be removed in a next major version. Deprecation log messages at the `WARN` level indicates that a less critical feature was used, it won’t be removed in next major version, but might be removed in the future. + +To stop writing deprecation log messages, set `logger.deprecation.level` to `OFF` in `log4j2.properties` : + +```properties +logger.deprecation.level = OFF +``` + +Alternatively, you can change the logging level dynamically: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.org.elasticsearch.deprecation": "OFF" + } +} +``` + +Refer to [Configuring logging levels](elasticsearch-log4j-configuration-self-managed.md#configuring-logging-levels). + +You can identify what is triggering deprecated functionality if `X-Opaque-Id` was used as an HTTP header. The user ID is included in the `X-Opaque-ID` field in deprecation JSON logs. + +```js +{ + "type": "deprecation", + "timestamp": "2019-08-30T12:07:07,126+02:00", + "level": "WARN", + "component": "o.e.d.r.a.a.i.RestCreateIndexAction", + "cluster.name": "distribution_run", + "node.name": "node-0", + "message": "[types removal] Using include_type_name in create index requests is deprecated. The parameter will be removed in the next major version.", + "x-opaque-id": "MY_USER_ID", + "cluster.uuid": "Aq-c-PAeQiK3tfBYtig9Bw", + "node.id": "D7fUYfnfTLa2D7y-xw6tZg" +} +``` + +Deprecation logs can be indexed into `.logs-deprecation.elasticsearch-default` data stream `cluster.deprecation_indexing.enabled` setting is set to true. + + +### Deprecation logs throttling [_deprecation_logs_throttling] + +Deprecation logs are deduplicated based on a deprecated feature key and x-opaque-id so that if a feature is repeatedly used, it will not overload the deprecation logs. This applies to both indexed deprecation logs and logs emitted to log files. You can disable the use of `x-opaque-id` in throttling by changing `cluster.deprecation_indexing.x_opaque_id_used.enabled` to false, refer to this class [javadoc](https://snapshots.elastic.co/javadoc/org/elasticsearch/elasticsearch/9.0.0-beta1-SNAPSHOT/org.elasticsearch.server/org/elasticsearch/common/logging/RateLimitingFilter.md) for more details. + + +## JSON log format [json-logging] + +To make parsing Elasticsearch logs easier, logs are now printed in a JSON format. This is configured by a Log4J layout property `appender.rolling.layout.type = ECSJsonLayout`. This layout requires a `dataset` attribute to be set which is used to distinguish logs streams when parsing. + +```properties +appender.rolling.layout.type = ECSJsonLayout +appender.rolling.layout.dataset = elasticsearch.server +``` + +Each line contains a single JSON document with the properties configured in `ECSJsonLayout`. See this class [javadoc](https://snapshots.elastic.co/javadoc/org/elasticsearch/elasticsearch/9.0.0-beta1-SNAPSHOT/org.elasticsearch.server/org/elasticsearch/common/logging/ESJsonLayout.md) for more details. However if a JSON document contains an exception, it will be printed over multiple lines. The first line will contain regular properties and subsequent lines will contain the stacktrace formatted as a JSON array. + +::::{note} +You can still use your own custom layout. To do that replace the line `appender.rolling.layout.type` with a different layout. See sample below: +:::: + + +```properties +appender.rolling.type = RollingFile +appender.rolling.name = rolling +appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}_server.log +appender.rolling.layout.type = PatternLayout +appender.rolling.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %.-10000m%n +appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.log.gz +``` + diff --git a/deploy-manage/monitor/monitoring-data.md b/deploy-manage/monitor/monitoring-data.md new file mode 100644 index 000000000..8413ab1f7 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data.md @@ -0,0 +1,7 @@ +# Managing monitoring data + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: we can review the name of this section... \ No newline at end of file diff --git a/deploy-manage/monitor/monitoring-data/access-performance-metrics-on-elastic-cloud.md b/deploy-manage/monitor/monitoring-data/access-performance-metrics-on-elastic-cloud.md new file mode 100644 index 000000000..e62052455 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/access-performance-metrics-on-elastic-cloud.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-saas-metrics-accessing.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-saas-metrics-accessing.html +--- + +# Access performance metrics on Elastic Cloud + +% What needs to be done: Lift-and-shift + +% Scope notes: only for elastic cloud SaaS and Heroku. We can get rid of the Heroku doc + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-saas-metrics-accessing.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-saas-metrics-accessing.md \ No newline at end of file diff --git a/deploy-manage/monitor/monitoring-data/beats-page.md b/deploy-manage/monitor/monitoring-data/beats-page.md new file mode 100644 index 000000000..0db60e043 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/beats-page.md @@ -0,0 +1,29 @@ +--- +navigation_title: "Beats Metrics" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/beats-page.html +--- + + + +# Beats Metrics [beats-page] + + +If you are monitoring Beats, the **Stack Monitoring** page in {{kib}} contains a panel for Beats in the cluster overview. + +:::{image} ../../../images/kibana-monitoring-beats.png +:alt: Monitoring Beats +:class: screenshot +::: + +To view an overview of the Beats data in the cluster, click **Overview**. The overview page has a section for activity in the last day, which is a real-time sample of data. The summary bar and charts follow the typical paradigm of data in the Monitoring UI, which is bound to the span of the time filter. This overview page can therefore show up-to-date or historical information. + +To view a listing of the individual Beat instances in the cluster, click **Beats**. The table listing shows each Beat instance that reports data to the monitoring cluster. All columns are sortable. Clicking a Beat name takes you to the detail page. For example: + +:::{image} ../../../images/kibana-monitoring-beats-detail.png +:alt: Monitoring details for Filebeat +:class: screenshot +::: + +The detail page contains a summary bar and charts. There are more charts on this page than the overview page and they are specific to a single Beat instance. + diff --git a/deploy-manage/monitor/monitoring-data/config-monitoring-data-streams-elastic-agent.md b/deploy-manage/monitor/monitoring-data/config-monitoring-data-streams-elastic-agent.md new file mode 100644 index 000000000..ed96335eb --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/config-monitoring-data-streams-elastic-agent.md @@ -0,0 +1,25 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/config-monitoring-data-streams-elastic-agent.html +--- + +# Configuring data streams created by Elastic Agent [config-monitoring-data-streams-elastic-agent] + +When [monitoring using {{agent}}](../stack-monitoring/collecting-monitoring-data-with-elastic-agent.md), data is stored in a set of data streams named `metrics-{{product}}.stack_monitoring.{{dataset}}-{namespace}`. For example: `metrics-elasticsearch.stack_monitoring.shard-default`. + +The settings and mappings for these data streams are determined by an index template named `metrics-{{product}}.stack_monitoring.{{dataset}}`. For example: `metrics-elasticsearch.stack_monitoring.shard`. + +To change the settings of each data stream, edit the `metrics-{{product}}.stack_monitoring.{{dataset}}@custom` component template that already exists. You can do this in {{kib}}: + +* Navigate to **Stack Management** > **Index Management** > **Component Templates**. +* Search for the component template. +* Select the **Edit** action. + +You can also use the {{es}} API: + +* Retrieve the component template using the [get component template API](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-component-templates.html). +* Edit the component template. +* Store the updated component template using the [update component template API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-component-template.html). + +After changing the component template, the updated settings are only applied to the data stream’s new backing indices. [Roll over the data stream](../../../manage-data/data-store/index-types/use-data-stream.md#manually-roll-over-a-data-stream) to immediately apply the updated settings to the data stream’s write index. + diff --git a/deploy-manage/monitor/monitoring-data/config-monitoring-data-streams-metricbeat-8.md b/deploy-manage/monitor/monitoring-data/config-monitoring-data-streams-metricbeat-8.md new file mode 100644 index 000000000..4f6262800 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/config-monitoring-data-streams-metricbeat-8.md @@ -0,0 +1,40 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/config-monitoring-data-streams-metricbeat-8.html +--- + +# Configuring data streams created by Metricbeat 8 [config-monitoring-data-streams-metricbeat-8] + +When [monitoring using {{metricbeat}} 8](../stack-monitoring/collecting-monitoring-data-with-metricbeat.md), data is stored in a set of data streams called `.monitoring-{{product}}-8-mb`. For example: `.monitoring-es-8-mb`. + +The settings and mappings for these data streams are determined by an index template named `.monitoring-{{product}}-mb`. For example: `.monitoring-es-mb`. You can alter the settings of each data stream by cloning this index template and editing it. + +::::{warning} +You need to repeat this procedure when upgrading the {{stack}} to get the latest updates to the default monitoring index templates. +:::: + + +You can clone index templates in {{kib}}: + +* Navigate to **Stack Management** > **Index Management** > **Index Templates**. +* From the **View** dropdown, select **System templates**. +* Search for the index template. +* Select the **Clone** action. +* Change the name, for example into `custom_monitoring`. +* Set the priority to `500`, to ensure it overrides the default index template. +* Specify the settings you want to change in the `settings` section. +* Save the cloned template. + +You can also use the {{es}} API: + +* Retrieve the index template using the [get index template API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-get-template.html). +* Edit the index template: set the template `priority` to `500`, and specify the settings you want to change in the `settings` section. +* Store the updated index template under a different name, for example `custom_monitoring`, using the [create index template API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-template.html). + +::::{note} +{{metricbeat}} 8 uses [composable templates](../../../manage-data/data-store/templates.md), rather than legacy templates. +:::: + + +After changing the index template, the updated settings are only applied to the data stream’s new backing indices. [Roll over the data stream](../../../manage-data/data-store/index-types/use-data-stream.md#manually-roll-over-a-data-stream) to immediately apply the updated settings to the data stream’s write index. + diff --git a/deploy-manage/monitor/monitoring-data/config-monitoring-indices-metricbeat-7-internal-collection.md b/deploy-manage/monitor/monitoring-data/config-monitoring-indices-metricbeat-7-internal-collection.md new file mode 100644 index 000000000..c380d1807 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/config-monitoring-indices-metricbeat-7-internal-collection.md @@ -0,0 +1,38 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/config-monitoring-indices-metricbeat-7-internal-collection.html +--- + +# Configuring indices created by Metricbeat 7 or internal collection [config-monitoring-indices-metricbeat-7-internal-collection] + +When monitoring [using {{metricbeat}} 7](../stack-monitoring/collecting-monitoring-data-with-metricbeat.md) or [internal collection](https://www.elastic.co/guide/en/beats/filebeat/current/monitoring-internal-collection.html), data is stored in a set of indices called either: + +* `.monitoring-{{product}}-7-mb-{{date}}`, when using {{metricbeat}} 7. +* `.monitoring-{{product}}-7-{{date}}`, when using internal collection. + +The settings and mappings for these indices are determined by [legacy index templates](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-templates-v1.html) named `.monitoring-{{product}}`. You can retrieve these templates in {{kib}} by navigating to **Stack Management** > **Index Management** > **Index Templates**, or by using the {{es}} `_template` API: + +```console +GET /_template/.monitoring-* +``` + +To change the settings of the indices, add a custom index template. You can do that in {{kib}}, or using the {{es}} API: + +* Set `index_patterns` to match the `.monitoring-{{product}}-7-*` indices. +* Set the template `order` to `1`. This ensures your template is applied after the default template, which has an order of 0. +* Specify the `number_of_shards` and/or `number_of_replicas` in the `settings` section. + +```console +PUT /_template/custom_monitoring +{ + "index_patterns": [".monitoring-beats-7-*", ".monitoring-es-7-*", ".monitoring-kibana-7-*", ".monitoring-logstash-7-*"], + "order": 1, + "settings": { + "number_of_shards": 5, + "number_of_replicas": 2 + } +} +``` + +After changing the index template, the updated settings are only applied to new indices. + diff --git a/deploy-manage/monitor/monitoring-data/configure-stack-monitoring-alerts.md b/deploy-manage/monitor/monitoring-data/configure-stack-monitoring-alerts.md new file mode 100644 index 000000000..30fa91112 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/configure-stack-monitoring-alerts.md @@ -0,0 +1,39 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-cluster-health-notifications.html +--- + +# Configure Stack monitoring alerts [ec-cluster-health-notifications] + +You can configure Stack monitoring alerts to be sent to you by email when health related events occur in your deployments. To set up email notifications: + +1. [Enable logging and monitoring](../stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) on deployments for which you want to receive notifications. You need to enable only metrics data being shipped for the notifications to work. +2. In Kibana, configure the email connector to [send email from Elastic Cloud](https://www.elastic.co/guide/en/kibana/current/email-action-type.html#elasticcloud). If you want to use the preconfigured `Elastic-Cloud-SMTP` connector in Elastic Cloud, then you can skip this step. +3. From the Kibana main menu, go to **Stack Monitoring**. On this page you can find a summary of monitoring metrics for your deployment as well as any alerts. +4. Select **Enter setup mode**. +5. On any card showing available alerts, select the **alerts** indicator. Use the menu to select the type of alert for which you’d like to be notified. There are many alert types, including: + + * CPU usage threshold + * Disk usage threshold + * JVM memory threshold + * Missing monitoring data + * Thread pool rejections (search/write) + * CCR read exceptions + * Large shard size + * Cluster alerting, including: + + * Elasticsearch cluster health status + * Elasticsearch, Kibana, or Logstash version mismatches + * Elasticsearch nodes changed + + All of these alerts are described in detail in [Kibana alerts](kibana-alerts.md). Check the documentation matching your Kibana version to find which alerts are available in that release. + + + ::::{note} + For the `Elasticsearch nodes changed` alert, if you have only one master node in your cluster, during the master node vacate no notification will be sent. Kibana needs to communicate with the master node in order to send a notification. One way to avoid this is by shipping your deployment metrics to a dedicated monitoring cluster, which you can configure when you enable logging and monitoring in Step 2. + + :::: + +6. In the **Edit rule** pane, set how often to check for the condition and how often to send notifications. +7. In the **Actions** section, select **Email** as a connector type and select the email connector that you configured in Step 3 (or the preconfigured `Elastic-Cloud-SMTP` connector). +8. Configure the email contents and select **Save**. Make sure that the email address you specify is the one that you allowed in Step 1. diff --git a/deploy-manage/monitor/monitoring-data/configuring-data-streamsindices-for-monitoring.md b/deploy-manage/monitor/monitoring-data/configuring-data-streamsindices-for-monitoring.md new file mode 100644 index 000000000..6a3bd103a --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/configuring-data-streamsindices-for-monitoring.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/config-monitoring-indices.html +--- + +# Configuring data streams/indices for monitoring [config-monitoring-indices] + +Monitoring data is stored in data streams or indices in {{es}}. The default data stream or index settings may not work for your situation. For example, you might want to change index lifecycle management (ILM) settings, add custom mappings, or change the number of shards and replicas. The steps to change these settings depend on the monitoring method: + +* [Configuring data streams created by {{agent}}](config-monitoring-data-streams-elastic-agent.md) +* [Configuring data streams created by {{metricbeat}} 8](config-monitoring-data-streams-metricbeat-8.md) (the default for version 8 {{ess}} deployments on {{ecloud}}) +* [Configuring indices created by {{metricbeat}} 7 or internal collection](config-monitoring-indices-metricbeat-7-internal-collection.md) + +::::{important} +Changing mappings or settings can cause your monitoring dashboards to stop working correctly. +:::: + + + + + diff --git a/deploy-manage/monitor/monitoring-data/ec-memory-pressure.md b/deploy-manage/monitor/monitoring-data/ec-memory-pressure.md new file mode 100644 index 000000000..4a3b62fbf --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/ec-memory-pressure.md @@ -0,0 +1,35 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-memory-pressure.html +--- + +# JVM memory pressure indicator [ec-memory-pressure] + +In addition to the more detailed [cluster performance metrics](../stack-monitoring.md), the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) also includes a JVM memory pressure indicator for each node in your cluster. This indicator can help you to determine when you need to upgrade to a larger cluster. + +The percentage number used in the JVM memory pressure indicator is actually the fill rate of the old generation pool. For a detailed explanation of why this metric is used, check [Understanding Memory Pressure](https://www.elastic.co/blog/found-understanding-memory-pressure-indicator/). + +:::{image} ../../../images/cloud-memory-pressure-indicator.png +:alt: Memory pressure indicator +::: + + +## JVM memory pressure levels [ec-memory-pressure-levels] + +When the JVM memory pressure reaches 75%, the indicator turns red. At this level, garbage collection becomes more frequent as the memory usage increases, potentially impacting the performance of your cluster. As long as the cluster performance suits your needs, JVM memory pressure above 75% is not a problem in itself, but there is not much spare memory capacity. Review the [common causes of high JVM memory usage](#ec-memory-pressure-causes) to determine your best course of action. + +When the JVM memory pressure indicator rises above 95%, {{es}}'s [real memory circuit breaker](https://www.elastic.co/guide/en/elasticsearch/reference/current/circuit-breaker.html#parent-circuit-breaker) triggers to prevent your instance from running out of memory. This situation can reduce the stability of your cluster and the integrity of your data. Unless you expect the load to drop soon, we recommend that you resize to a larger cluster before you reach this level of memory pressure. Even if you’re planning to optimize your memory usage, it is best to resize the cluster first. Resizing the cluster to increase capacity can give you more time to apply other changes, and also provides the cluster with more resource for when those changes are applied. + + +## Common causes of high JVM memory usage [ec-memory-pressure-causes] + +The two most common reasons for a high JVM memory pressure reading are: + +**1. Having too many shards per node** + +If JVM memory pressure above 75% is a frequent occurrence, the cause is often having too many shards per node relative to the amount of available memory. You can lower the JVM memory pressure by reducing the number of shards or upgrading to a larger cluster. For guidelines, check [How to size your shards](https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html). + +**2. Running expensive queries** + +If JVM memory pressure above 75% happens only occasionally, this is often due to expensive queries. Queries that have a very large request size, that involve aggregations with a large volume of buckets, or that involve sorting on a non-optimized field, can all cause temporary spikes in JVM memory usage. To resolve this problem, consider optimizing your queries or upgrading to a larger cluster. + diff --git a/deploy-manage/monitor/monitoring-data/ec-saas-metrics-accessing.md b/deploy-manage/monitor/monitoring-data/ec-saas-metrics-accessing.md new file mode 100644 index 000000000..26d58bb8b --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/ec-saas-metrics-accessing.md @@ -0,0 +1,132 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-saas-metrics-accessing.html +--- + +# Access performance metrics [ec-saas-metrics-accessing] + +Cluster performance metrics are available directly in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). The graphs on this page include a subset of Elasticsearch Service-specific performance metrics. + +For advanced views or production monitoring, [enable logging and monitoring](../stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md). The monitoring application provides more advanced views for Elasticsearch and JVM metrics, and includes a configurable retention period. + +To access cluster performance metrics: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. For example, you might want to select **Is unhealthy** and **Has master problems** to get a short list of deployments that need attention. + +3. From your deployment menu, go to the **Performance** page. + +The following metrics are available: + + +### CPU usage [ec_cpu_usage] + +:::{image} ../../../images/cloud-metrics-cpu-usage.png +:alt: Graph showing CPU usage +::: + +Shows the maximum usage of the CPU resources assigned to your Elasticsearch cluster, as a percentage. CPU resources are relative to the size of your cluster, so that a cluster with 32GB of RAM gets assigned twice as many CPU resources as a cluster with 16GB of RAM. All clusters are guaranteed their share of CPU resources, as Elasticsearch Service infrastructure does not overcommit any resources. CPU credits permit boosting the performance of smaller clusters temporarily, so that CPU usage can exceed 100%. + +::::{tip} +This chart reports the maximum CPU values over the sampling period. [Logs and Metrics](../stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md) ingested into [Stack Monitoring](visualizing-monitoring-data.md)'s "CPU Usage" instead reflects the average CPU over the sampling period. Therefore, you should not expect the two graphs to look exactly the same. When investigating [CPU-related performance issues](../../../troubleshoot/monitoring/performance.md), you should default to [Stack Monitoring](visualizing-monitoring-data.md). +:::: + + + +### CPU credits [ec_cpu_credits] + +:::{image} ../../../images/cloud-metrics-cpu-credits.png +:alt: Graph showing available CPU credits +::: + +Shows your remaining CPU credits, measured in seconds of CPU time. CPU credits enable the boosting of CPU resources assigned to your cluster to improve performance temporarily when it is needed most. For more details check [How to use vCPU to boost your instance](ec-vcpu-boost-instance.md). + + +### Number of requests [ec_number_of_requests] + +:::{image} ../../../images/cloud-metrics-number-of-requests.png +:alt: Graph showing the number of requests +::: + +Shows the number of requests that your cluster receives per second, separated into search requests and requests to index documents. This metric provides a good indicator of the volume of work that your cluster typically handles over time which, together with other performance metrics, helps you determine if your cluster is sized correctly. Also lets you check if there is a sudden increase in the volume of user requests that might explain an increase in response times. + + +### Search response times [ec_search_response_times] + +:::{image} ../../../images/cloud-metrics-search-response-times.png +:alt: Graph showing search response times +::: + +Indicates the amount of time that it takes for your Elasticsearch cluster to complete a search query, in milliseconds. Response times won’t tell you about the cause of a performance issue, but they are often a first indicator that something is amiss with the performance of your Elasticsearch cluster. + + +### Index response times [ec_index_response_times] + +:::{image} ../../../images/cloud-metrics-index-response-times.png +:alt: Graph showing index response times +::: + +Indicates the amount of time that it takes for your Elasticsearch cluster to complete an indexing operation, in milliseconds. Response times won’t tell you about the cause of a performance issue, but they are often a first indicator that something is amiss with the performance of your Elasticsearch cluster. + + +### Memory pressure per node [ec_memory_pressure_per_node] + +:::{image} ../../../images/cloud-metrics-memory-pressure-per-node.png +:alt: Graph showing memory pressure per node +::: + +Indicates the total memory used by the JVM heap over time. We’ve configured {{es}}'s garbage collector to keep memory usage below 75% for heaps of 8GB or larger. For heaps smaller than 8GB, the threshold is 85%. If memory pressure consistently remains above this threshold, you might need to resize your cluster or reduce memory consumption. Check [how high memory pressure can cause performance issues](../../../troubleshoot/monitoring/high-memory-pressure.md). + + +### GC overhead per node [ec_gc_overhead_per_node] + +:::{image} ../../../images/cloud-metrics-gc-overhead-per-node.png +:alt: Graph showing the garbage collection overhead per node +::: + +Indicates the overhead involved in JVM garbage collection to reclaim memory. + + +## Tips for working with performance metrics [ec_tips_for_working_with_performance_metrics] + +Performance correlates directly with resources assigned to your cluster, and many of these metrics will show some sort of correlation with each other when you are trying to determine the cause of a performance issue. Take a look at some of the scenarios included in this section to learn how you can determine the cause of performance issues. + +It is not uncommon for performance issues on Elasticsearch Service to be caused by an undersized cluster that cannot cope with the workload it is being asked to handle. If your cluster performance metrics often shows high CPU usage or excessive memory pressure, consider increasing the size of your cluster soon to improve performance. This is especially true for clusters that regularly reach 100% of CPU usage or that suffer out-of-memory failures; it is better to resize your cluster early when it is not yet maxed out than to have to resize a cluster that is already overwhelmed. [Changing the configuration of your cluster](../../deploy/elastic-cloud/configure.md) may add some overhead if data needs to be migrated to the new nodes, which can increase the load on a cluster further and delay configuration changes. + +To help diagnose high CPU usage you can also use the Elasticsearch [nodes hot threads API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-hot-threads.html), which identifies the threads on each node that have the highest CPU usage or that have been executing for a longer than normal period of time. + +::::{tip} +Got an overwhelmed cluster that needs to be upsized? [Try enabling maintenance mode first](../../maintenance/ece/start-stop-routing-requests.md). It will likely help with configuration changes. +:::: + + +Work with the metrics shown in **Cluster Performance Metrics** section to help you find the information you need: + +* Hover on any part of a graph to get additional information. For example, hovering on a section of a graph that shows response times reveals the percentile that responses fall into at that point in time: + + :::{image} ../../../images/cloud-metrics-hover.png + :alt: Hover over the metric graph + ::: + +* Zoom in on a graph by drawing a rectangle to select a specific time window. As you zoom in one metric, other performance metrics change to show data for the same time window. + + :::{image} ../../../images/cloud-metrics-zoom.png + :alt: Zoom the metric graph + ::: + +* Pan around with ![Pan in a metric graph](../../../images/cloud-metrics-pan.png "") to make sure that you can get the right parts of a metric graph as you zoom in. +* Reset the metric graph axes with ![Reset the metric graph](../../../images/cloud-metrics-reset.png ""), which returns the graphs to their original scale. + +Cluster performance metrics are shown per node and are color-coded to indicate which running Elasticsearch instance they belong to. + + +## Cluster restarts after out-of-memory failures [ec_cluster_restarts_after_out_of_memory_failures] + +For clusters that suffer out-of-memory failures, it can be difficult to determine whether the clusters are in a completely healthy state afterwards. For this reason, Elasticsearch Service automatically reboots clusters that suffer out-of-memory failures. + +You will receive an email notification to let you know that a restart occurred. For repeated alerts, the emails are aggregated so that you do not receive an excessive number of notifications. Either [resizing your cluster to reduce memory pressure](../../deploy/elastic-cloud/ec-customize-deployment-components.md#ec-cluster-size) or reducing the workload that a cluster is being asked to handle can help avoid these cluster restarts. + + + diff --git a/deploy-manage/monitor/monitoring-data/ec-vcpu-boost-instance.md b/deploy-manage/monitor/monitoring-data/ec-vcpu-boost-instance.md new file mode 100644 index 000000000..162e660e6 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/ec-vcpu-boost-instance.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-vcpu-boost-instance.html +--- + +# vCPU boosting and credits [ec-vcpu-boost-instance] + +Elastic Cloud allows smaller instance sizes to get temporarily boosted vCPU when under heavy load. vCPU boosting is governed by vCPU credits that instances can earn over time when vCPU usage is less than the assigned amount. + + +## How does vCPU boosting work? [ec_how_does_vcpu_boosting_work] + +Based on the instance size, the vCPU resources assigned to your instance can be boosted to improve performance temporarily, by using vCPU credits. If credits are available, Elastic Cloud will automatically boost your instance when under heavy load. Boosting is available depending on the instance size: + +* Instance sizes up to and including 12 GB of RAM get boosted. The boosted vCPU value is `16 * vCPU ratio`, the vCPU ratios are dependent on the [hardware profile](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations) selected. If an instance is eligible for boosting, the Elastic Cloud console will display **Up to 2.5 vCPU**, depending on the hardware profile selected. The baseline, or unboosted, vCPU value is calculated as: `RAM size * vCPU ratio`. +* Instance sizes bigger than 12 GB of RAM do not get boosted. The vCPU value is displayed in the Elastic Cloud console and calculated as follows: `RAM size * vCPU ratio`. + + +## What are vCPU credits? [ec_what_are_vcpu_credits] + +[vCPU](https://www.elastic.co/guide/en/elastic-stack-glossary/current/terms.html#glossary-vcpu) credits enable a smaller instance to perform as if it were assigned the vCPU resources of a larger instance, but only for a limited time. vCPU credits are available only on smaller instances up to and including 8 GB of RAM. + +vCPU credits persist through cluster restarts, but they are tied to your existing instance nodes. Operations that create new instance nodes will lose existing vCPU credits. This happens when you resize your instance, or if Elastic performs system maintenance on your nodes. + + +## How to earn vCPU credits? [ec_how_to_earn_vcpu_credits] + +When you initially create an instance, you receive a credit of 60 seconds worth of vCPU time. You can accumulate additional credits when your vCPU usage is less than what your instance is assigned. At most, you can accumulate one hour worth of additional vCPU time per GB of RAM for your instance. + +For example: An instance with 4 GB of RAM, can at most accumulate four hours worth of additional vCPU time and can consume all of these vCPU credits within four hours when loaded heavily with requests. + +If you observe declining performance on a smaller instance over time, you might have depleted your vCPU credits. In this case, increase the size of your cluster to handle the workload with consistent performance. + +For more information, check [Elasticsearch Service default provider instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-reference-hardware.html#ec-getting-started-configurations). + + +## Where to check vCPU credits status? [ec_where_to_check_vcpu_credits_status] + +You can check the **Monitoring > Performance > CPU Credits** section of the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), and find the related metrics: + +:::{image} ../../../images/cloud-metrics-credits.png +:alt: CPU usage versus CPU credits over time +::: + + +## What to do if my vCPU credits get depleted constantly? [ec_what_to_do_if_my_vcpu_credits_get_depleted_constantly] + +If you need your cluster to be able to sustain a certain level of performance, you cannot rely on CPU boosting to handle the workload except temporarily. To ensure that performance can be sustained, consider increasing the size of your cluster. Read [this page](../../../troubleshoot/monitoring/performance.md) for more guidance. + diff --git a/deploy-manage/monitor/monitoring-data/ech-memory-pressure.md b/deploy-manage/monitor/monitoring-data/ech-memory-pressure.md new file mode 100644 index 000000000..93636ef70 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/ech-memory-pressure.md @@ -0,0 +1,35 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-memory-pressure.html +--- + +# JVM memory pressure indicator [ech-memory-pressure] + +In addition to the more detailed [cluster performance metrics](../stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md), the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body) also includes a JVM memory pressure indicator for each node in your cluster. This indicator can help you to determine when you need to upgrade to a larger cluster. + +The percentage number used in the JVM memory pressure indicator is actually the fill rate of the old generation pool. For a detailed explanation of why this metric is used, check [Understanding Memory Pressure](https://www.elastic.co/blog/found-understanding-memory-pressure-indicator/). + +:::{image} ../../../images/cloud-heroku-memory-pressure-indicator.png +:alt: Memory pressure indicator +::: + + +## JVM memory pressure levels [ech-memory-pressure-levels] + +When the JVM memory pressure reaches 75%, the indicator turns red. At this level, garbage collection becomes more frequent as the memory usage increases, potentially impacting the performance of your cluster. As long as the cluster performance suits your needs, JVM memory pressure above 75% is not a problem in itself, but there is not much spare memory capacity. Review the [common causes of high JVM memory usage](#ech-memory-pressure-causes) to determine your best course of action. + +When the JVM memory pressure indicator rises above 95%, {{es}}'s [real memory circuit breaker](https://www.elastic.co/guide/en/elasticsearch/reference/current/circuit-breaker.html#parent-circuit-breaker) triggers to prevent your instance from running out of memory. This situation can reduce the stability of your cluster and the integrity of your data. Unless you expect the load to drop soon, we recommend that you resize to a larger cluster before you reach this level of memory pressure. Even if you’re planning to optimize your memory usage, it is best to resize the cluster first. Resizing the cluster to increase capacity can give you more time to apply other changes, and also provides the cluster with more resource for when those changes are applied. + + +## Common causes of high JVM memory usage [ech-memory-pressure-causes] + +The two most common reasons for a high JVM memory pressure reading are: + +**1. Having too many shards per node** + +If JVM memory pressure above 75% is a frequent occurrence, the cause is often having too many shards per node relative to the amount of available memory. You can lower the JVM memory pressure by reducing the number of shards or upgrading to a larger cluster. For guidelines, check [How to size your shards](https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html). + +**2. Running expensive queries** + +If JVM memory pressure above 75% happens only occasionally, this is often due to expensive queries. Queries that have a very large request size, that involve aggregations with a large volume of buckets, or that involve sorting on a non-optimized field, can all cause temporary spikes in JVM memory usage. To resolve this problem, consider optimizing your queries or upgrading to a larger cluster. + diff --git a/deploy-manage/monitor/monitoring-data/ech-saas-metrics-accessing.md b/deploy-manage/monitor/monitoring-data/ech-saas-metrics-accessing.md new file mode 100644 index 000000000..ad331febd --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/ech-saas-metrics-accessing.md @@ -0,0 +1,127 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-saas-metrics-accessing.html +--- + +# Access performance metrics [ech-saas-metrics-accessing] + +Cluster performance metrics are available directly in the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). The graphs on this page include a subset of Elasticsearch Add-On for Heroku-specific performance metrics. + +For advanced views or production monitoring, [enable logging and monitoring](../stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md). The monitoring application provides more advanced views for Elasticsearch and JVM metrics, and includes a configurable retention period. + +To access cluster performance metrics: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. On the deployments page, select your deployment. + + Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. For example, you might want to select **Is unhealthy** and **Has master problems** to get a short list of deployments that need attention. + +3. From your deployment menu, go to the **Performance** page. + +The following metrics are available: + + +### CPU usage [echcpu_usage] + +:::{image} ../../../images/cloud-heroku-metrics-cpu-usage.png +:alt: Graph showing CPU usage +::: + +Shows the maximum usage of the CPU resources assigned to your Elasticsearch cluster, as a percentage. CPU resources are relative to the size of your cluster, so that a cluster with 32GB of RAM gets assigned twice as many CPU resources as a cluster with 16GB of RAM. All clusters are guaranteed their share of CPU resources, as Elasticsearch Add-On for Heroku infrastructure does not overcommit any resources. CPU credits permit boosting the performance of smaller clusters temporarily, so that CPU usage can exceed 100%. + + +### CPU credits [echcpu_credits] + +:::{image} ../../../images/cloud-heroku-metrics-cpu-credits.png +:alt: Graph showing available CPU credits +::: + +Shows your remaining CPU credits, measured in seconds of CPU time. CPU credits enable the boosting of CPU resources assigned to your cluster to improve performance temporarily when it is needed most. For more details check [How to use vCPU to boost your instance](ech-vcpu-boost-instance.md). + + +### Number of requests [echnumber_of_requests] + +:::{image} ../../../images/cloud-heroku-metrics-number-of-requests.png +:alt: Graph showing the number of requests +::: + +Shows the number of requests that your cluster receives per second, separated into search requests and requests to index documents. This metric provides a good indicator of the volume of work that your cluster typically handles over time which, together with other performance metrics, helps you determine if your cluster is sized correctly. Also lets you check if there is a sudden increase in the volume of user requests that might explain an increase in response times. + + +### Search response times [echsearch_response_times] + +:::{image} ../../../images/cloud-heroku-metrics-search-response-times.png +:alt: Graph showing search response times +::: + +Indicates the amount of time that it takes for your Elasticsearch cluster to complete a search query, in milliseconds. Response times won’t tell you about the cause of a performance issue, but they are often a first indicator that something is amiss with the performance of your Elasticsearch cluster. + + +### Index response times [echindex_response_times] + +:::{image} ../../../images/cloud-heroku-metrics-index-response-times.png +:alt: Graph showing index response times +::: + +Indicates the amount of time that it takes for your Elasticsearch cluster to complete an indexing operation, in milliseconds. Response times won’t tell you about the cause of a performance issue, but they are often a first indicator that something is amiss with the performance of your Elasticsearch cluster. + + +### Memory pressure per node [echmemory_pressure_per_node] + +:::{image} ../../../images/cloud-heroku-metrics-memory-pressure-per-node.png +:alt: Graph showing memory pressure per node +::: + +Indicates the total memory used by the JVM heap over time. We’ve configured {{es}}'s garbage collector to keep memory usage below 75% for heaps of 8GB or larger. For heaps smaller than 8GB, the threshold is 85%. If memory pressure consistently remains above this threshold, you might need to resize your cluster or reduce memory consumption. Check [how high memory pressure can cause performance issues](../../../troubleshoot/monitoring/high-memory-pressure.md). + + +### GC overhead per node [echgc_overhead_per_node] + +:::{image} ../../../images/cloud-heroku-metrics-gc-overhead-per-node.png +:alt: Graph showing the garbage collection overhead per node +::: + +Indicates the overhead involved in JVM garbage collection to reclaim memory. + + +## Tips for working with performance metrics [echtips_for_working_with_performance_metrics] + +Performance correlates directly with resources assigned to your cluster, and many of these metrics will show some sort of correlation with each other when you are trying to determine the cause of a performance issue. Take a look at some of the scenarios included in this section to learn how you can determine the cause of performance issues. + +It is not uncommon for performance issues on Elasticsearch Add-On for Heroku to be caused by an undersized cluster that cannot cope with the workload it is being asked to handle. If your cluster performance metrics often shows high CPU usage or excessive memory pressure, consider increasing the size of your cluster soon to improve performance. This is especially true for clusters that regularly reach 100% of CPU usage or that suffer out-of-memory failures; it is better to resize your cluster early when it is not yet maxed out than to have to resize a cluster that is already overwhelmed. [Changing the configuration of your cluster](../../deploy/elastic-cloud/cloud-hosted.md) may add some overhead if data needs to be migrated to the new nodes, which can increase the load on a cluster further and delay configuration changes. + +To help diagnose high CPU usage you can also use the Elasticsearch [nodes hot threads API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-hot-threads.html), which identifies the threads on each node that have the highest CPU usage or that have been executing for a longer than normal period of time. + +::::{tip} +Got an overwhelmed cluster that needs to be upsized? [Try enabling maintenance mode first](https://www.elastic.co/guide/en/cloud-heroku/current/ech-upgrading-v5.html#ech-maintenance-mode-routing). It will likely help with configuration changes. +:::: + + +Work with the metrics shown in **Cluster Performance Metrics** section to help you find the information you need: + +* Hover on any part of a graph to get additional information. For example, hovering on a section of a graph that shows response times reveals the percentile that responses fall into at that point in time: + + :::{image} ../../../images/cloud-heroku-metrics-hover.png + :alt: Hover over the metric graph + ::: + +* Zoom in on a graph by drawing a rectangle to select a specific time window. As you zoom in one metric, other performance metrics change to show data for the same time window. + + :::{image} ../../../images/cloud-heroku-metrics-zoom.png + :alt: Zoom the metric graph + ::: + +* Pan around with ![Pan in a metric graph](../../../images/cloud-heroku-metrics-pan.png "") to make sure that you can get the right parts of a metric graph as you zoom in. +* Reset the metric graph axes with ![Reset the metric graph](../../../images/cloud-heroku-metrics-reset.png ""), which returns the graphs to their original scale. + +Cluster performance metrics are shown per node and are color-coded to indicate which running Elasticsearch instance they belong to. + + +## Cluster restarts after out-of-memory failures [echcluster_restarts_after_out_of_memory_failures] + +For clusters that suffer out-of-memory failures, it can be difficult to determine whether the clusters are in a completely healthy state afterwards. For this reason, Elasticsearch Add-On for Heroku automatically reboots clusters that suffer out-of-memory failures. + +You will receive an email notification to let you know that a restart occurred. For repeated alerts, the emails are aggregated so that you do not receive an excessive number of notifications. Either [resizing your cluster to reduce memory pressure](../../deploy/elastic-cloud/ech-customize-deployment-components.md#ech-cluster-size) or reducing the workload that a cluster is being asked to handle can help avoid these cluster restarts. + + + diff --git a/deploy-manage/monitor/monitoring-data/ech-vcpu-boost-instance.md b/deploy-manage/monitor/monitoring-data/ech-vcpu-boost-instance.md new file mode 100644 index 000000000..895ec40af --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/ech-vcpu-boost-instance.md @@ -0,0 +1,49 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-vcpu-boost-instance.html +--- + +# vCPU boosting and credits [ech-vcpu-boost-instance] + +Elastic Cloud allows smaller instance sizes to get temporarily boosted vCPU when under heavy load. vCPU boosting is governed by vCPU credits that instances can earn over time when vCPU usage is less than the assigned amount. + + +## How does vCPU boosting work? [echhow_does_vcpu_boosting_work] + +Based on the instance size, the vCPU resources assigned to your instance can be boosted to improve performance temporarily, by using vCPU credits. If credits are available, Elastic Cloud will automatically boost your instance when under heavy load. Boosting is available depending on the instance size: + +* Instance sizes up to and including 12 GB of RAM get boosted. The boosted vCPU value is `16 * vCPU ratio`, the vCPU ratios are dependent on the [hardware profile](../../deploy/elastic-cloud/ech-reference-hardware.md#ech-getting-started-configurations) selected. If an instance is eligible for boosting, the Elastic Cloud console will display **Up to 2.5 vCPU**, depending on the hardware profile selected. The baseline, or unboosted, vCPU value is calculated as: `RAM size * vCPU ratio`. +* Instance sizes bigger than 12 GB of RAM do not get boosted. The vCPU value is displayed in the Elastic Cloud console and calculated as follows: `RAM size * vCPU ratio`. + + +## What are vCPU credits? [echwhat_are_vcpu_credits] + +[vCPU](https://www.elastic.co/guide/en/elastic-stack-glossary/current/terms.html#glossary-vcpu) credits enable a smaller instance to perform as if it were assigned the vCPU resources of a larger instance, but only for a limited time. vCPU credits are available only on smaller instances up to and including 8 GB of RAM. + +vCPU credits persist through cluster restarts, but they are tied to your existing instance nodes. Operations that create new instance nodes will lose existing vCPU credits. This happens when you resize your instance, or if Elastic performs system maintenance on your nodes. + + +## How to earn vCPU credits? [echhow_to_earn_vcpu_credits] + +When you initially create an instance, you receive a credit of 60 seconds worth of vCPU time. You can accumulate additional credits when your vCPU usage is less than what your instance is assigned. At most, you can accumulate one hour worth of additional vCPU time per GB of RAM for your instance. + +For example: An instance with 4 GB of RAM, can at most accumulate four hours worth of additional vCPU time and can consume all of these vCPU credits within four hours when loaded heavily with requests. + +If you observe declining performance on a smaller instance over time, you might have depleted your vCPU credits. In this case, increase the size of your cluster to handle the workload with consistent performance. + +For more information, check [Elasticsearch Service default provider instance configurations](../../deploy/elastic-cloud/ech-reference-hardware.md#ech-getting-started-configurations). + + +## Where to check vCPU credits status? [echwhere_to_check_vcpu_credits_status] + +You can check the **Monitoring > Performance > CPU Credits** section of the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body), and find the related metrics: + +:::{image} ../../../images/cloud-heroku-metrics-credits.png +:alt: CPU usage versus CPU credits over time +::: + + +## What to do if my vCPU credits get depleted constantly? [echwhat_to_do_if_my_vcpu_credits_get_depleted_constantly] + +If you need your cluster to be able to sustain a certain level of performance, you cannot rely on CPU boosting to handle the workload except temporarily. To ensure that performance can be sustained, consider increasing the size of your cluster. Read [this page](../../../troubleshoot/monitoring/performance.md) for more guidance. + diff --git a/deploy-manage/monitor/monitoring-data/elasticsearch-metrics.md b/deploy-manage/monitor/monitoring-data/elasticsearch-metrics.md new file mode 100644 index 000000000..29d869a8e --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/elasticsearch-metrics.md @@ -0,0 +1,118 @@ +--- +navigation_title: "{{es}} Metrics" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/elasticsearch-metrics.html +--- + + + +# Elasticsearch Metrics [elasticsearch-metrics] + + +You can drill down into the status of your {{es}} cluster in {{kib}} by clicking the [Overview](#cluster-overview-page), [Nodes](#nodes-page), [Indices](#indices-overview-page) and [Logs](#logs-monitor-page) links on the **Stack Monitoring** page. + +:::{image} ../../../images/kibana-monitoring-elasticsearch.png +:alt: Monitoring clusters +:class: screenshot +::: + +For more information, refer to [Monitor a cluster](../../monitor.md). + + +## Cluster Overview [cluster-overview-page] + +To view the key metrics that indicate the overall health of an {{es}} cluster, click **Overview** in the {{es}} section. Anything that needs your attention is highlighted in yellow or red. + +::::{tip} +Conditions that require your attention are listed at the top of the Clusters page. You can also set up watches to alert you when the status of your cluster changes. To learn how, see [Watching the status of an {{es}} cluster](../../../explore-analyze/alerts/watcher/watch-cluster-status.md). +:::: + + +The panel at the top shows the current cluster statistics, the charts show the search and indexing performance over time, and the table at the bottom shows information about any shards that are being recovered. If you use {{filebeat}} to collect log data from this cluster, you can also see its recent logs. + +:::{image} ../../../images/kibana-monitoring-overview.png +:alt: Elasticsearch Cluster Overview +:class: screenshot +::: + +::::{tip} +Not sure what a chart is showing? Click the info button for a description of the metrics. +:::: + + +From there, you can dive into detailed metrics for particular nodes and indices. + + +## Nodes [nodes-page] + +To view node metrics, click **Nodes**. The Nodes section shows the status of each node in your cluster. + + +### Node Overview [nodes-page-overview] + +Click the name of a node to view its node statistics over time. These represent high-level statistics collected from {{es}} that provide a good overview of health. If you use {{filebeat}} to collect log data from this node, you can also see its recent logs. + + +### Node Advanced [nodes-page-advanced] + +To view advanced node metrics, click the **Advanced** tab for a node. The **Advanced** tab shows additional metrics, such as memory and garbage collection statistics reported by the selected {{es}} node. + +You can use the advanced node view to diagnose issues that generally involve more advanced knowledge of {{es}}, such as poor garbage collection performance. + + +## Indices [indices-overview-page] + +To view index metrics, click **Indices**. The Indices section shows the same overall index and search metrics as the Overview and a table of your indices. + + +### Index Overview [indices-page-overview] + +From the Indices listing, you can view data for a particular index. To drill down into the data for a particular index, click its name in the Indices table. + + +### Index Advanced [indices-page-advanced] + +To view advanced index metrics, click the **Advanced** tab for an index. The **Advanced** tab shows additional metrics, such as memory statistics reported about the {{es}} index. If the index has more than one shard, then its shards might live on more than one node. + +The Advanced index view can be used to diagnose issues that generally involve more advanced knowledge of {{es}}, such as wasteful index memory usage. + + +## Jobs [jobs-page] + +To view {{ml}} job metrics, click **Jobs**. For each job in your cluster, it shows information such as its status, the number of records processed, the size of the model, the number of forecasts, and the node that runs the job. + + +## CCR [ccr-overview-page] + +To view {{ccr}} metrics, click **CCR**. For each follower index on the cluster, it shows the following information: + +* **Index**: The name of the follower index. +* **Follows**: The name of the leader index. +* **Alerts**: Any read exceptions that have been triggered for the index or its shards. +* **Sync Lag (ops)**: How many operations the follower index is lagging behind the leader index. + + This is calculated by finding the difference between the minimum and maximum operation sequence number on the leader (`leader_max_seq_no`) and the difference between the minimum and maximum global sequence number checkpoint on the follower (`follower_global_checkpoint`) for each shard over the selected time period. The difference in `follower_global_checkpoint` is subtracted from the difference in `leader_max_seq_no` for each shard, and the highest result across all shards is displayed. + +* **Last fetch time**: The time elapsed since the last successful fetch from the leader index. Represents the longest time elapsed across all of the shards in the follower index. +* **Ops synced**: The number of operations indexed (replicated) into the follower index from the leader index in the selected time period. + + This metric is a sum of the number of operations indexed across all shards over the selected time period. + +* **Error**: Any exceptions returned for the most recent document in the selected time period. + +If you select a follower index, you can view the same information for each shard. For more information on the properties used to calculate these metrics, refer to the [get follower stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-stats.html) documentation. + +If you select a shard, you can see graphs for the fetch and operation delays. You can also see advanced information, which contains additional stats from the [get follower stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-stats.html). + +Learn more about [{{ccr-cap}}](../../tools/cross-cluster-replication.md). + + +## Logs [logs-monitor-page] + +If you use {{filebeat}} to collect log data from your cluster, you can see its recent logs in the **Stack Monitoring** application. The **Clusters** page lists the number of informational, debug, and warning messages in the server and deprecation logs. + +If you click **Logs**, you can see the most recent logs for the cluster. + +::::{tip} +By default, up to 10 log entries are shown. You can show up to 50 log entries by changing the [`monitoring.ui.elasticsearch.logFetchCount` setting](https://www.elastic.co/guide/en/kibana/current/monitoring-settings-kb.html#monitoring-ui-settings). If you changed the default name of filebeat indices, you also need to update `monitoring.ui.logs.index` accordingly. +:::: diff --git a/deploy-manage/monitor/monitoring-data/kibana-alerts.md b/deploy-manage/monitor/monitoring-data/kibana-alerts.md new file mode 100644 index 000000000..fcd729e92 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/kibana-alerts.md @@ -0,0 +1,97 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/kibana-alerts.html +--- + +# Kibana alerts [kibana-alerts] + +The {{stack}} {monitor-features} provide [Alerting rules](../../../explore-analyze/alerts/kibana.md) out-of-the box to notify you of potential issues in the {{stack}}. These rules are preconfigured based on the best practices recommended by Elastic. However, you can tailor them to meet your specific needs. + +:::{image} ../../../images/kibana-monitoring-kibana-alerting-notification.png +:alt: {{kib}} alerting notifications in {stack-monitor-app} +:class: screenshot +::: + +When you open **{{stack-monitor-app}}** for the first time, you will be asked to acknowledge the creation of these default rules. They are initially configured to detect and notify on various conditions across your monitored clusters. You can view notifications for: **Cluster health**, **Resource utilization**, and **Errors and exceptions** for {{es}} in real time. + +::::{note} +The default {{watcher}} based "cluster alerts" for {{stack-monitor-app}} have been recreated as rules in {{kib}} {alert-features}. For this reason, the existing {{watcher}} email action `monitoring.cluster_alerts.email_notifications.email_address` no longer works. The default action for all {{stack-monitor-app}} rules is to write to {{kib}} logs and display a notification in the UI. +:::: + + +To review and modify existing **{{stack-monitor-app}}** rules, click **Enter setup mode** on the **Cluster overview** page. Alternatively, to manage all rules, including create and delete functionality go to **{{stack-manage-app}} > {{rules-ui}}**. + + +## CPU usage threshold [kibana-alerts-cpu-threshold] + +This rule checks for {{es}} nodes that run a consistently high CPU load. By default, the condition is set at 85% or more averaged over the last 5 minutes. The default rule checks on a schedule time of 1 minute with a re-notify interval of 1 day. + + +## Disk usage threshold [kibana-alerts-disk-usage-threshold] + +This rule checks for {{es}} nodes that are nearly at disk capacity. By default, the condition is set at 80% or more averaged over the last 5 minutes. The default rule checks on a schedule time of 1 minute with a re-notify interval of 1 day. + + +## JVM memory threshold [kibana-alerts-jvm-memory-threshold] + +This rule checks for {{es}} nodes that use a high amount of JVM memory. By default, the condition is set at 85% or more averaged over the last 5 minutes. The default rule checks on a schedule time of 1 minute with a re-notify interval of 1 day. + + +## Missing monitoring data [kibana-alerts-missing-monitoring-data] + +This rule checks for {{es}} nodes that stop sending monitoring data. By default, the condition is set to missing for 15 minutes looking back 1 day. The default rule checks on a schedule time of 1 minute with a re-notify interval of 6 hours. + + +## Thread pool rejections (search/write) [kibana-alerts-thread-pool-rejections] + +This rule checks for {{es}} nodes that experience thread pool rejections. By default, the condition is set at 300 or more over the last 5 minutes. The default rule checks on a schedule time of 1 minute with a re-notify interval of 1 day. Thresholds can be set independently for `search` and `write` type rejections. + + +## CCR read exceptions [kibana-alerts-ccr-read-exceptions] + +This rule checks for read exceptions on any of the replicated {{es}} clusters. The condition is met if 1 or more read exceptions are detected in the last hour. The default rule checks on a schedule time of 1 minute with a re-notify interval of 6 hours. + + +## Large shard size [kibana-alerts-large-shard-size] + +This rule checks for a large average shard size (across associated primaries) on any of the specified data views in an {{es}} cluster. The condition is met if an index’s average shard size is 55gb or higher in the last 5 minutes. The default rule matches the pattern of `-.*` by running checks on a schedule time of 1 minute with a re-notify interval of 12 hours. + + +## Cluster alerting [kibana-alerts-cluster-alerts] + +These rules check the current status of your {{stack}}. You can drill down into the metrics to view more information about your cluster and specific nodes, instances, and indices. + +An action is triggered if any of the following conditions are met within the last minute: + +* {{es}} cluster health status is yellow (missing at least one replica) or red (missing at least one primary). +* {{es}} version mismatch. You have {{es}} nodes with different versions in the same cluster. +* {{kib}} version mismatch. You have {{kib}} instances with different versions running against the same {{es}} cluster. +* Logstash version mismatch. You have Logstash nodes with different versions reporting stats to the same monitoring cluster. +* {{es}} nodes changed. You have {{es}} nodes that were recently added or removed. +* {{es}} license expiration. The cluster’s license is about to expire. + + If you do not preserve the data directory when upgrading a {{kib}} or Logstash node, the instance is assigned a new persistent UUID and shows up as a new instance. + +* Subscription license expiration. When the expiration date approaches, you will get notifications with a severity level relative to how soon the expiration date is: + + * 60 days: Informational alert + * 30 days: Low-level alert + * 15 days: Medium-level alert + * 7 days: Severe-level alert + + The 60-day and 30-day thresholds are skipped for Trial licenses, which are only valid for 30 days. + + + +## Alerts and rules [_alerts_and_rules] + + +### Create default rules [_create_default_rules] + +This option can be used to create default rules in this Kibana space. This is useful for scenarios when you didn’t choose to create these default rules initially or anytime later if the rules were accidentally deleted. + +::::{note} +Some action types are subscription features, while others are free. For a comparison of the Elastic subscription levels, see the alerting section of the [Subscriptions page](https://www.elastic.co/subscriptions). +:::: + + diff --git a/deploy-manage/monitor/monitoring-data/kibana-page.md b/deploy-manage/monitor/monitoring-data/kibana-page.md new file mode 100644 index 000000000..4cc9cdb26 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/kibana-page.md @@ -0,0 +1,23 @@ +--- +navigation_title: "{{kib}} Metrics" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/kibana-page.html +--- + + + +# Kibana Metrics [kibana-page] + + +To view the key metrics that indicate the overall health of {{kib}} itself, click **Overview** in the {{kib}} section of the **Stack Monitoring** page. + +:::{image} ../../../images/kibana-monitoring-kibana-overview.png +:alt: Kibana Overview +:class: screenshot +::: + +1. To view {{kib}} instance metrics, click **Instances**. + + The Instances section shows the status of each {{kib}} instance. + +2. Click the name of an instance to view its instance statistics over time. diff --git a/deploy-manage/monitor/monitoring-data/logstash-page.md b/deploy-manage/monitor/monitoring-data/logstash-page.md new file mode 100644 index 000000000..4a896750b --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/logstash-page.md @@ -0,0 +1,22 @@ +--- +navigation_title: "Logstash Metrics" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/logstash-page.html +--- + + + +# Logstash Metrics [logstash-page] + + +If you are monitoring Logstash nodes, click **Overview** in the Logstash section of the **Stack Monitoring** page in {{kib}}. You can view the overall health of the Logstash nodes. + +:::{image} ../../../images/kibana-monitoring-logstash-overview.png +:alt: Logstash Overview +:class: screenshot +::: + +1. To view Logstash node metrics, click **Nodes**. The Nodes section shows the status of each Logstash node. +2. Click the name of a node to view its statistics over time. + +For more information, refer to [Monitoring Logstash](https://www.elastic.co/guide/en/logstash/current/configuring-logstash.html). diff --git a/deploy-manage/monitor/monitoring-data/monitor-troubleshooting.md b/deploy-manage/monitor/monitoring-data/monitor-troubleshooting.md new file mode 100644 index 000000000..010b0611a --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/monitor-troubleshooting.md @@ -0,0 +1,51 @@ +--- +navigation_title: "Troubleshooting" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/monitor-troubleshooting.html +--- + + + +# Troubleshooting [monitor-troubleshooting] + + +Use the information in this section to troubleshoot common problems and find answers for frequently asked questions related to the {{kib}} {monitor-features}. + + +## Cannot view the cluster because the license information is invalid [_cannot_view_the_cluster_because_the_license_information_is_invalid] + +**Symptoms:** + +The following error appears in a banner at the top of the screen in {{kib}} on the **Stack Monitoring > Clusters** page: `You can't view the "" cluster because the license information is invalid.` + +**Resolution:** + +You cannot monitor a version 6.3 or later cluster from {{kib}} version 6.2 or earlier. To resolve this issue, upgrade {{kib}} to 6.3 or later. See [Upgrading the {{stack}}](../../upgrade/deployment-or-cluster.md). + + +## {{filebeat}} index is corrupt [_filebeat_index_is_corrupt] + +**Symptoms:** + +The **Stack Monitoring** application displays a Monitoring Request error indicating that an illegal argument exception has occurred because fielddata is disabled on text fields by default. + +**Resolution** + +1. Stop all your {{filebeat}} instances. +2. Delete indices beginning with `filebeat-$VERSION`, where `VERSION` corresponds to the version of {{filebeat}} running. +3. Restart all your {{filebeat}} instances. + + +## No monitoring data is visible in {{kib}} [_no_monitoring_data_is_visible_in_kib] + +**Symptoms:** + +The **Stack Monitoring** page in {{kib}} is empty. + +**Resolution:** + +1. Confirm that {{kib}} is seeking monitoring data from the appropriate {{es}} URL. By default, data is retrieved from the cluster specified in the `elasticsearch.hosts` setting in the `kibana.yml` file. If you want to retrieve it from a different monitoring cluster, set `monitoring.ui.elasticsearch.hosts`. See [Monitoring settings](https://www.elastic.co/guide/en/kibana/current/monitoring-settings-kb.html). +2. Confirm that there is monitoring data available at that URL. It is stored in indices such as `.monitoring-kibana-*` and `.monitoring-es-*` or `metrics-kibana.stack_monitoring.*`, depending on which method is used to collect monitoring data. At a minimum, you must have monitoring data for the {{es}} production cluster. Once that data exists, {{kib}} can display monitoring data for other products in the cluster. +3. Set the time filter to “Last 1 hour”. When monitoring data appears in your cluster, the page automatically refreshes with the monitoring summary. +4. If using {{agent}}, ensure that all integration assets have been installed in the monitoring cluster. + diff --git a/deploy-manage/monitor/monitoring-data/visualizing-monitoring-data.md b/deploy-manage/monitor/monitoring-data/visualizing-monitoring-data.md new file mode 100644 index 000000000..5cac99ea2 --- /dev/null +++ b/deploy-manage/monitor/monitoring-data/visualizing-monitoring-data.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/xpack-monitoring.html +--- + +# Visualizing monitoring data [xpack-monitoring] + +The {{kib}} {monitor-features} serve two separate purposes: + +1. To visualize monitoring data from across the {{stack}}. You can view health and performance data for {{es}}, {{ls}}, {{ents}}, APM, and Beats in real time, as well as analyze past performance. +2. To monitor {{kib}} itself and route that data to the monitoring cluster. + +If you enable monitoring across the {{stack}}, each monitored component is considered unique based on its persistent UUID, which is written to the [`path.data`](../../deploy/self-managed/configure.md) directory when the node or instance starts. + +For more information, see [Configure monitoring](../stack-monitoring/kibana-monitoring-self-managed.md) and [Monitor a cluster](../../monitor.md). + +Want to monitor your fleet of {{agent}}s, too? Use {{fleet}} instead of the Stack Monitoring UI. To learn more, refer to [Monitor {{agent}}s](https://www.elastic.co/guide/en/fleet/current/monitor-elastic-agent.html). + diff --git a/deploy-manage/monitor/monitoring-overview.md b/deploy-manage/monitor/monitoring-overview.md new file mode 100644 index 000000000..dd77e09a5 --- /dev/null +++ b/deploy-manage/monitor/monitoring-overview.md @@ -0,0 +1,7 @@ +# Monitoring overview + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: Write an overview about monitoring (maybe this is similar than the landing page). \ No newline at end of file diff --git a/deploy-manage/monitor/orchestrators.md b/deploy-manage/monitor/orchestrators.md new file mode 100644 index 000000000..9f6e51709 --- /dev/null +++ b/deploy-manage/monitor/orchestrators.md @@ -0,0 +1,7 @@ +# Monitoring Orchestrators + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: Landing page to monitoring orchestrators (not deployments) \ No newline at end of file diff --git a/deploy-manage/monitor/orchestrators/ece-monitoring-ece-access.md b/deploy-manage/monitor/orchestrators/ece-monitoring-ece-access.md new file mode 100644 index 000000000..3e06693b6 --- /dev/null +++ b/deploy-manage/monitor/orchestrators/ece-monitoring-ece-access.md @@ -0,0 +1,54 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-monitoring-ece-access.html +--- + +# Access logs and metrics [ece-monitoring-ece-access] + +To access logs and metrics for your deployment: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. On the **Elasticsearch** page, the following logs and metrics are available: + + Elasticsearch logs + : Detailed logs related to cluster state + + Elasticsearch metrics + : Detailed metrics for CPU and memory usage, running processes, networking and file system performance, and more + + Proxy logs + : Search and indexing requests that proxies have sent to the Elasticsearch cluster + + If a Kibana instance exists for the deployment, the following Kibana logs and metrics are also available from the **Kibana** page: + + Kibana logs + : Detailed logs related to instance state + + Kibana metrics + : Detailed metrics for CPU and memory usage, running processes, networking and file system performance, and more + + Proxy logs + : Requests that proxies have sent to the Kibana instance + + +::::{tip} +If you have a license from 2018 or earlier, you might receive a warning that your cluster license is about to expire. Don’t panic, it isn’t really. Elastic Cloud Enterprise manages the cluster licenses so that you don’t have to. In rare cases, such as when a cluster is overloaded, it can take longer for Elastic Cloud Enterprise to reapply the cluster license. If you have a license from 2019 and later, you’ll receive a warning only when your full platform license is about to expire, which you’ll need to renew. +:::: + + +1. Select one of the links and log in with the `elastic` user. If you do not know the password, you can [reset it first](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + + ::::{tip} + The password you specify must be for the `elastic` user on the `logging-and-metrics` cluster, where the logging and metrics indices are collected. If you need to reset the password for the user, make sure you reset for the `logging-and-metrics` cluster. + :::: + + + After you select one of the links, Kibana opens and shows you a view of the monitoring metrics for the logs or metrics that you selected. + + +If you are looking for an {{es}} or {{kib}} diagnostic to share with Elastic support, go to the **Operations** page for the deployment and download the diagnostic bundle to attach to your ticket. If logs or an ECE diagnostic are requested by Elastic support, please [run the ECE diagnostics tool](../../../troubleshoot/deployments/cloud-enterprise/run-ece-diagnostics-tool.md). + diff --git a/deploy-manage/monitor/orchestrators/ece-monitoring-ece-set-retention.md b/deploy-manage/monitor/orchestrators/ece-monitoring-ece-set-retention.md new file mode 100644 index 000000000..7105de040 --- /dev/null +++ b/deploy-manage/monitor/orchestrators/ece-monitoring-ece-set-retention.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-monitoring-ece-set-retention.html +--- + +# Set the retention period for logging and metrics indices [ece-monitoring-ece-set-retention] + +Elastic Cloud Enterprise sets up default index lifecycle management (ILM) policies on the logging and metrics indices it collects. By default, metrics indices are kept for one day and logging indices are kept for seven days. This retention period can be adjusted. + +You might need to adjust the retention period for one of the following reasons: + +* If your business requires you to retain logs and metrics for longer than the default period. +* If the volume of logs and metrics collected is high enough to require reducing the amount of storage space consumed. + +To customize the retention period, set up a custom lifecycle policy for logs and metrics indices: + +1. [Create a new index lifecycle management (ILM) policy](../../../manage-data/lifecycle/index-lifecycle-management/configure-lifecycle-policy.md) in the logging and metrics cluster. +2. Create a new, legacy-style, index template that matches the data view (formerly *index pattern*) that you wish to customize lifecycle for. +3. Specify a lifecycle policy in the index template settings. +4. Choose a higher `order` for the template so the specified lifecycle policy will be used instead of the default. + diff --git a/deploy-manage/monitor/orchestrators/ece-platform-monitoring.md b/deploy-manage/monitor/orchestrators/ece-platform-monitoring.md new file mode 100644 index 000000000..a73d3e077 --- /dev/null +++ b/deploy-manage/monitor/orchestrators/ece-platform-monitoring.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-monitoring-ece.html +--- + +# ECE platform monitoring [ece-monitoring-ece] + +Elastic Cloud Enterprise by default collects monitoring data for your installation using Filebeat and Metricbeat. This data gets sent as monitoring indices to a dedicated `logging-and-metrics` deployment that is created whenever you install Elastic Cloud Enterprise on your first host. Data is collected on every host that is part of your Elastic Cloud Enterprise installation and includes: + +* Logs for all core services that are a part of Elastic Cloud Enterprise and monitoring metrics for core Elastic Cloud Enterprise services, system processes on the host, and any third-party software +* Logs and monitoring metrics for Elasticsearch clusters and for Kibana instances + +These monitoring indices are collected in addition to the [monitoring you might have enabled for specific clusters](../stack-monitoring/enable-stack-monitoring-on-ece-deployments.md), which also provides monitoring metrics that you can access in Kibana (note that the `logging-and-metrics` deployment is used for monitoring data from system deployments only; for non-system deployments, monitoring data must be sent to a deployment other than `logging-and-metrics`). + +In this section: + +* [Access logs and metrics](ece-monitoring-ece-access.md) - Where to find the logs and metrics that are collected. +* [Capture heap dumps](../../../troubleshoot/deployments/cloud-enterprise/heap-dumps.md) - Troubleshoot instances that run out of memory. +* [Capture thread dumps](../../../troubleshoot/deployments/cloud-enterprise/thread-dumps.md) - Troubleshoot instances that are having thread or CPU issues. +* [Set the Retention Period for Logging and Metrics Indices](ece-monitoring-ece-set-retention.md) - Set the retention period for the indices that Elastic Cloud Enterprise collects. + +::::{important} +The `logging-and-metrics` deployment is for use by your ECE installation only. You must not use this deployment to index monitoring data from your own Elasticsearch clusters or use it to index data from Beats and Logstash. Always create a separate, dedicated monitoring deployment for your own use. +:::: + + diff --git a/deploy-manage/monitor/orchestrators/ece-proxy-log-fields.md b/deploy-manage/monitor/orchestrators/ece-proxy-log-fields.md new file mode 100644 index 000000000..5fde6bc67 --- /dev/null +++ b/deploy-manage/monitor/orchestrators/ece-proxy-log-fields.md @@ -0,0 +1,47 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-proxy-log-fields.html +--- + +# Proxy Log Fields [ece-proxy-log-fields] + +::::{note} +These fields *are* subject to change, though the vast majority of them are generic for HTTP requests and should be relatively stable. +:::: + + +| | | +| --- | --- | +| Field | Description | +| `proxy_ip` | the IP on the connection, i.e. a proxy IP if the request has been proxied | +| `request_end` | the time the request was returned in ms since unix epoch | +| `status_code` | the HTTP status returned to the client | +| `handling_instance` | the product instance name the request was forwarded to | +| `handling_server` | the allocator IP address the request was forwarded to | +| `request_length` | the length of the request body, a value of `-1` means streaming/continuing | +| `request_path` | the request path from the url | +| `instance_capacity` | the total capacity of the handling instance | +| `response_time` | the total time taken for the request in milliseconds `ms`. `response_time` includes `backend_response_time`. | +| `backend_response_time` | the total time spent processing the upstream request with the backend instance (Elasticsearch, Kibana, and so on), including the initial connection, time the component is processing the request, and time streaming the response back to the calling client. The proxy latency is `backend_response_time` - `response_time`. `backend_response_time` minus `backend_response_body_time` indicates the time spent making the initial connection to the backend instance as well as the time for the backend instance to actually process the request. `backend_response_time` includes `backend_response_body_time`. | +| `backend_response_body_time` | the total time spent streaming the response from the backend instance to the calling client. | +| `auth_user` | the authenticated user for the request (only supported for basic authentication) | +| `capacity` | the total capacity of the handling cluster | +| `request_host` | the `Host` header from the request | +| `client_ip` | the client IP for the request (may differ from proxy ip if `X-Forwarded-For` or proxy protocol is configured) | +| `availability_zones` | the number of availablity zones supported by the target cluster | +| `response_length` | the number of bytes written in the response body | +| `connection_id` | a unique ID represented a single client connecition, multiple requests may use a single connection | +| `status_reason` | an optional reason to explain the response code - e.g. `BLOCKED_BY_TRAFFIC_FILTER` | +| `request_start` | the time the request was received in milliseconds `ms` since unix epoch | +| `request_port` | the port used for the request | +| `request_scheme` | the scheme (HTTP/HTTPS) used for the request | +| `message` | an optoinal message associated with a proxy error | +| `action` | the type of elasticsearch request (e.g. search/bulk etc) | +| `handling_cluster` | the cluster the request was forwarded to | +| `request_id` | a unique ID for each request (returned on the response as `X-Cloud-Request-Id` - can be used to correlate client requests with proxy logs) | +| `tls_version` | a code indicating the TLS version used for the request - `1.0 769`,`1.1 770`,`1.2 771`,`1.3 772` | +| `instance_count` | the number of instances in the target cluster | +| `cluster_type` | the type of cluster the request was routed to (e.g. elasticsearch, kibana, apm etc) | +| `request_method` | the HTTP method for the request | +| `backend_connection_id` | a unique ID for the upstream request to the product, the proxy maintains connection pools so this should be re-used | + diff --git a/deploy-manage/monitor/orchestrators/eck-metrics-configuration.md b/deploy-manage/monitor/orchestrators/eck-metrics-configuration.md new file mode 100644 index 000000000..223a4743c --- /dev/null +++ b/deploy-manage/monitor/orchestrators/eck-metrics-configuration.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-configure-operator-metrics.html +--- + +# ECK metrics configuration [k8s-configure-operator-metrics] + +The ECK operator provides a metrics endpoint that can be used to monitor the operator’s performance and health. By default, the metrics endpoint is not enabled and is not secured. The following sections describe how to enable it, secure it and the associated Prometheus requirements: + +* [Enabling the metrics endpoint](k8s-enabling-metrics-endpoint.md) +* [Securing the metrics endpoint](k8s-securing-metrics-endpoint.md) +* [Prometheus requirements](k8s-prometheus-requirements.md) + +::::{note} +The ECK operator metrics endpoint will be secured by default beginning in version 3.0.0. +:::: + + + + + diff --git a/deploy-manage/monitor/orchestrators/k8s-enabling-metrics-endpoint.md b/deploy-manage/monitor/orchestrators/k8s-enabling-metrics-endpoint.md new file mode 100644 index 000000000..e11e4b23f --- /dev/null +++ b/deploy-manage/monitor/orchestrators/k8s-enabling-metrics-endpoint.md @@ -0,0 +1,105 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-enabling-the-metrics-endpoint.html +--- + +# Enabling the metrics endpoint [k8s-enabling-the-metrics-endpoint] + +The metrics endpoint is not enabled by default. To enable the metrics endpoint, follow the instructions in the next sections depending on whether you installed ECK through the Helm chart or the manifests. + +## Using the operator Helm chart [k8s_using_the_operator_helm_chart] + +If you installed ECK through the Helm chart commands listed in [Install ECK using the Helm chart](../../deploy/cloud-on-k8s/install-using-helm-chart.md), you can now set `config.metrics.port` to a value greater than 0 in your values file and the metrics endpoint will be enabled. + + +## Using the operator manifests [k8s_using_the_operator_manifests] + +If you installed ECK using the manifests using the commands listed in [*Deploy ECK in your Kubernetes cluster*](../../deploy/cloud-on-k8s/install-using-yaml-manifest-quickstart.md) some additional changes will be required to enable the metrics endpoint. + +Enable the metrics endpoint in the `ConfigMap`. + +```shell +cat < + name: tls-certificate + readOnly: true + volumes: + - name: conf + configMap: + name: elastic-operator + - name: cert + secret: + defaultMode: 420 + secretName: elastic-webhook-server-cert + - name: tls-certificate + secret: + defaultMode: 420 + secretName: eck-metrics-tls-certificate +EOF +``` + +1. If mounting the TLS secret to a different directory the `metrics-cert-dir` setting in the operator configuration has to be adjusted accordingly. + + +Potentially patch the `ServiceMonitor`. This will only need to be done if you are adjusting the `insecureSkipVerify` field to `false`. + +```shell +kubectl patch servicemonitor -n elastic-system elastic-operator --patch-file=/dev/stdin <<-EOF +spec: + endpoints: + - port: https + path: /metrics + scheme: https + interval: 30s + tlsConfig: + insecureSkipVerify: false + caFile: /etc/prometheus/secrets/{secret-name}/ca.crt <1> + serverName: elastic-operator-metrics.elastic-system.svc + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token +EOF +``` + +1. See the [Prometheus requirements section](k8s-prometheus-requirements.md) for more information on creating the CA secret. + + + + diff --git a/deploy-manage/monitor/stack-monitoring.md b/deploy-manage/monitor/stack-monitoring.md new file mode 100644 index 000000000..17f524092 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring.md @@ -0,0 +1,34 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-overview.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/how-monitoring-works.html + - https://www.elastic.co/guide/en/cloud/current/ec-monitoring.html +--- + +# Stack Monitoring + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: Merge both docs into 1 as an overview. Ensure its valid for all deployment types. Consider bringing part of the info from the elastic cloud monitoring introduction. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/monitoring-overview.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/how-monitoring-works.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-monitoring.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-es-cluster-health$$$ + +$$$ec-es-cluster-performance$$$ + +$$$ec-es-health-dedicated$$$ + +$$$ec-es-health-preconfigured$$$ + +$$$ec-es-health-warnings$$$ + +$$$ec-health-best-practices$$$ \ No newline at end of file diff --git a/deploy-manage/monitor/stack-monitoring/collecting-log-data-with-filebeat.md b/deploy-manage/monitor/stack-monitoring/collecting-log-data-with-filebeat.md new file mode 100644 index 000000000..cf06e7425 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/collecting-log-data-with-filebeat.md @@ -0,0 +1,120 @@ +--- +navigation_title: "Collecting log data with {{filebeat}}" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-filebeat.html +--- + + + +# Collecting log data with Filebeat [configuring-filebeat] + + +You can use {{filebeat}} to monitor the {{es}} log files, collect log events, and ship them to the monitoring cluster. Your recent logs are visible on the **Monitoring** page in {{kib}}. + +::::{important} +If you’re using {{agent}}, do not deploy {{filebeat}} for log collection. Instead, configure the {{es}} integration to collect logs. +:::: + + +1. Verify that {{es}} is running and that the monitoring cluster is ready to receive data from {{filebeat}}. + + ::::{tip} + In production environments, we strongly recommend using a separate cluster (referred to as the *monitoring cluster*) to store the data. Using a separate monitoring cluster prevents production cluster outages from impacting your ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. See [*Monitoring in a production environment*](elasticsearch-monitoring-self-managed.md). + :::: + +2. Identify which logs you want to monitor. + + The {{filebeat}} {es} module can handle [audit logs](../logging-configuration/logfile-audit-output.md), [deprecation logs](../logging-configuration/elasticsearch-log4j-configuration-self-managed.md#deprecation-logging), [gc logs](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#gc-logging), [server logs](../logging-configuration/elasticsearch-log4j-configuration-self-managed.md), and [slow logs](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-slowlog.html). For more information about the location of your {{es}} logs, see the [path.logs](../../deploy/self-managed/important-settings-configuration.md#path-settings) setting. + + ::::{important} + If there are both structured (`*.json`) and unstructured (plain text) versions of the logs, you must use the structured logs. Otherwise, they might not appear in the appropriate context in {{kib}}. + :::: + +3. [Install {{filebeat}}](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-installation-configuration.html) on the {{es}} nodes that contain logs that you want to monitor. +4. Identify where to send the log data. + + For example, specify {{es}} output information for your monitoring cluster in the {{filebeat}} configuration file (`filebeat.yml`): + + ```yaml + output.elasticsearch: + # Array of hosts to connect to. + hosts: ["http://es-mon-1:9200", "http://es-mon-2:9200"] <1> + + # Optional protocol and basic auth credentials. + #protocol: "https" + #username: "elastic" + #password: "changeme" + ``` + + 1. In this example, the data is stored on a monitoring cluster with nodes `es-mon-1` and `es-mon-2`. + + + If you configured the monitoring cluster to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://es-mon-1:9200`. + + ::::{important} + The {{es}} {monitor-features} use ingest pipelines, therefore the cluster that stores the monitoring data must have at least one [ingest node](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md). + :::: + + + If {{es}} {security-features} are enabled on the monitoring cluster, you must provide a valid user ID and password so that {{filebeat}} can send metrics successfully. + + For more information about these configuration options, see [Configure the {{es}} output](https://www.elastic.co/guide/en/beats/filebeat/current/elasticsearch-output.html). + +5. Optional: Identify where to visualize the data. + + {{filebeat}} provides example {{kib}} dashboards, visualizations and searches. To load the dashboards into the appropriate {{kib}} instance, specify the `setup.kibana` information in the {{filebeat}} configuration file (`filebeat.yml`) on each node: + + ```yaml + setup.kibana: + host: "localhost:5601" + #username: "my_kibana_user" + #password: "YOUR_PASSWORD" + ``` + + ::::{tip} + In production environments, we strongly recommend using a dedicated {{kib}} instance for your monitoring cluster. + :::: + + + If {{security-features}} are enabled, you must provide a valid user ID and password so that {{filebeat}} can connect to {{kib}}: + + 1. Create a user on the monitoring cluster that has the [`kibana_admin` built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md) or equivalent privileges. + 2. Add the `username` and `password` settings to the {{es}} output information in the {{filebeat}} configuration file. The example shows a hard-coded password, but you should store sensitive values in the [secrets keystore](https://www.elastic.co/guide/en/beats/filebeat/current/keystore.html). + + See [Configure the {{kib}} endpoint](https://www.elastic.co/guide/en/beats/filebeat/current/setup-kibana-endpoint.html). + +6. Enable the {{es}} module and set up the initial {{filebeat}} environment on each node. + + For example: + + ```sh + filebeat modules enable elasticsearch + filebeat setup -e + ``` + + For more information, see [{{es}} module](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-module-elasticsearch.html). + +7. Configure the {{es}} module in {{filebeat}} on each node. + + If the logs that you want to monitor aren’t in the default location, set the appropriate path variables in the `modules.d/elasticsearch.yml` file. See [Configure the {{es}} module](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-module-elasticsearch.html#configuring-elasticsearch-module). + + ::::{important} + If there are JSON logs, configure the `var.paths` settings to point to them instead of the plain text logs. + :::: + +8. [Start {{filebeat}}](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-starting.html) on each node. + + ::::{note} + Depending on how you’ve installed {{filebeat}}, you might see errors related to file ownership or permissions when you try to run {{filebeat}} modules. See [Config file ownership and permissions](https://www.elastic.co/guide/en/beats/libbeat/current/config-file-permissions.html). + :::: + +9. Check whether the appropriate indices exist on the monitoring cluster. + + For example, use the [cat indices](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-indices.html) command to verify that there are new `filebeat-*` indices. + + ::::{tip} + If you want to use the **Monitoring** UI in {{kib}}, there must also be `.monitoring-*` indices. Those indices are generated when you collect metrics about {{stack}} products. For example, see [Collecting monitoring data with {{metricbeat}}](collecting-monitoring-data-with-metricbeat.md). + :::: + +10. [View the monitoring data in {{kib}}](monitoring-data.md). + diff --git a/deploy-manage/monitor/stack-monitoring/collecting-monitoring-data-with-elastic-agent.md b/deploy-manage/monitor/stack-monitoring/collecting-monitoring-data-with-elastic-agent.md new file mode 100644 index 000000000..2db0f2e4e --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/collecting-monitoring-data-with-elastic-agent.md @@ -0,0 +1,52 @@ +--- +navigation_title: "Collecting monitoring data with {{agent}}" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-elastic-agent.html +--- + + + +# Collecting monitoring data with Elastic Agent [configuring-elastic-agent] + + +In 8.5 and later, you can use {{agent}} to collect data about {{es}} and ship it to the monitoring cluster, rather than [using {{metricbeat}}](collecting-monitoring-data-with-metricbeat.md) or routing it through exporters as described in [Legacy collection methods](legacy-collection-methods.md). + + +## Prerequisites [_prerequisites_11] + +* (Optional) Create a monitoring cluster as described in [*Monitoring in a production environment*](elasticsearch-monitoring-self-managed.md). +* Create a user on the production cluster that has the `remote_monitoring_collector` [built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). + + +## Add {{es}} monitoring data [_add_es_monitoring_data] + +To collect {{es}} monitoring data, add an {{es}} integration to an {{agent}} and deploy it to the host where {{es}} is running. + +1. Go to the {{kib}} home page and click **Add integrations**. +2. In the query bar, search for and select the **{{es}}** integration for {{agent}}. +3. Read the overview to make sure you understand integration requirements and other considerations. +4. Click **Add Elasticsearch**. + + ::::{tip} + If you’re installing an integration for the first time, you may be prompted to install {{agent}}. Click **Add integration only (skip agent installation)**. + :::: + +5. Configure the integration name and optionally add a description. Make sure you configure all required settings: + + 1. Under **Collect Elasticsearch logs**, modify the log paths to match your {{es}} environment. + 2. Under **Collect Elasticsearch metrics**, make sure the hosts setting points to your {{es}} host URLs. By default, the integration collects {{es}} monitoring metrics from `localhost:9200`. If that host and port number are not correct, update the `hosts` setting. If you configured {{es}} to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://localhost:9200`. + 3. Expand **Advanced options**. If the Elastic {{security-features}} are enabled, enter the username and password of a user that has the `remote_monitoring_collector` role. + 4. Specify the scope: + + * Specify `cluster` if each entry in the hosts list indicates a single endpoint for a distinct {{es}} cluster (for example, a load-balancing proxy fronting the cluster that directs requests to the master-ineligible nodes in the cluster). + * Otherwise, accept the default scope, `node`. If this scope is set, you will need to install {{agent}} on each {{es}} node to collect all metrics. {{agent}} will collect most of the metrics from the elected master of the cluster, so you must scale up all your master-eligible nodes to account for this extra load. Do not use this `node` if you have dedicated master nodes. + +6. Choose where to add the integration policy. Click **New hosts** to add it to new agent policy or **Existing hosts** to add it to an existing agent policy. +7. Click **Save and continue**. This step takes a minute or two to complete. When it’s done, you’ll have an agent policy that contains an integration for collecting monitoring data from {{es}}. +8. If an {{agent}} is already assigned to the policy and deployed to the host where {{es}} is running, you’re done. Otherwise, you need to deploy an {{agent}}. To deploy an {{agent}}: + + 1. Go to **{{fleet}} → Agents**, then click **Add agent**. + 2. Follow the steps in the **Add agent** flyout to download, install, and enroll the {{agent}}. Make sure you choose the agent policy you created earlier. + +9. Wait a minute or two until incoming data is confirmed. +10. [View the monitoring data in {{kib}}](monitoring-data.md). diff --git a/deploy-manage/monitor/stack-monitoring/collecting-monitoring-data-with-metricbeat.md b/deploy-manage/monitor/stack-monitoring/collecting-monitoring-data-with-metricbeat.md new file mode 100644 index 000000000..16f2113b4 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/collecting-monitoring-data-with-metricbeat.md @@ -0,0 +1,107 @@ +--- +navigation_title: "Collecting monitoring data with {{metricbeat}}" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-metricbeat.html +--- + + + +# Collecting monitoring data with Metricbeat [configuring-metricbeat] + + +In 6.5 and later, you can use {{metricbeat}} to collect data about {{es}} and ship it to the monitoring cluster, rather than routing it through exporters as described in [Legacy collection methods](legacy-collection-methods.md). + +Want to use {{agent}} instead? Refer to [Collecting monitoring data with {{agent}}](collecting-monitoring-data-with-elastic-agent.md). + +:::{image} ../../../images/elasticsearch-reference-metricbeat.png +:alt: Example monitoring architecture +::: + +1. [Install {{metricbeat}}](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-installation-configuration.html). Ideally install a single {{metricbeat}} instance configured with `scope: cluster` and configure `hosts` to point to an endpoint (e.g. a load-balancing proxy) which directs requests to the master-ineligible nodes in the cluster. If this is not possible then install one {{metricbeat}} instance for each {{es}} node in the production cluster and use the default `scope: node`. When {{metricbeat}} is monitoring {{es}} with `scope: node` then you must install a {{metricbeat}} instance for each {{es}} node. If you don’t, some metrics will not be collected. {{metricbeat}} with `scope: node` collects most of the metrics from the elected master of the cluster, so you must scale up all your master-eligible nodes to account for this extra load and you should not use this mode if you have dedicated master nodes. +2. Enable the {{es}} module in {{metricbeat}} on each {{es}} node. + + For example, to enable the default configuration for the {{stack-monitor-features}} in the `modules.d` directory, run the following command: + + ```sh + metricbeat modules enable elasticsearch-xpack + ``` + + For more information, refer to [{{es}} module](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-module-elasticsearch.html). + +3. Configure the {{es}} module in {{metricbeat}} on each {{es}} node. + + The `modules.d/elasticsearch-xpack.yml` file contains the following settings: + + ```yaml + - module: elasticsearch + xpack.enabled: true + period: 10s + hosts: ["http://localhost:9200"] <1> + #scope: node <2> + #username: "user" + #password: "secret" + #ssl.enabled: true + #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] + #ssl.certificate: "/etc/pki/client/cert.pem" + #ssl.key: "/etc/pki/client/cert.key" + #ssl.verification_mode: "full" + ``` + + 1. By default, the module collects {{es}} monitoring metrics from `http://localhost:9200`. If that host and port number are not correct, you must update the `hosts` setting. If you configured {{es}} to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://localhost:9200`. + 2. By default, `scope` is set to `node` and each entry in the `hosts` list indicates a distinct node in an {{es}} cluster. If you set `scope` to `cluster` then each entry in the `hosts` list indicates a single endpoint for a distinct {{es}} cluster (for example, a load-balancing proxy fronting the cluster). You should use `scope: cluster` if the cluster has dedicated master nodes, and configure the endpoint in the `hosts` list not to direct requests to the dedicated master nodes. + + + If Elastic {{security-features}} are enabled, you must also provide a user ID and password so that {{metricbeat}} can collect metrics successfully: + + 1. Create a user on the production cluster that has the [`remote_monitoring_collector` built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). Alternatively, use the [`remote_monitoring_user` built-in user](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + 2. Add the `username` and `password` settings to the {{es}} module configuration file. + 3. If TLS is enabled on the HTTP layer of your {{es}} cluster, you must either use https as the URL scheme in the `hosts` setting or add the `ssl.enabled: true` setting. Depending on the TLS configuration of your {{es}} cluster, you might also need to specify [additional ssl.*](https://www.elastic.co/guide/en/beats/metricbeat/current/configuration-ssl.html) settings. + +4. Optional: Disable the system module in {{metricbeat}}. + + By default, the [system module](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-module-system.html) is enabled. The information it collects, however, is not shown on the **Monitoring** page in {{kib}}. Unless you want to use that information for other purposes, run the following command: + + ```sh + metricbeat modules disable system + ``` + +5. Identify where to send the monitoring data. + + ::::{tip} + In production environments, we strongly recommend using a separate cluster (referred to as the *monitoring cluster*) to store the data. Using a separate monitoring cluster prevents production cluster outages from impacting your ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. + :::: + + + For example, specify the {{es}} output information in the {{metricbeat}} configuration file (`metricbeat.yml`): + + ```yaml + output.elasticsearch: + # Array of hosts to connect to. + hosts: ["http://es-mon-1:9200", "http://es-mon-2:9200"] <1> + + # Optional protocol and basic auth credentials. + #protocol: "https" + #username: "elastic" + #password: "changeme" + ``` + + 1. In this example, the data is stored on a monitoring cluster with nodes `es-mon-1` and `es-mon-2`. + + + If you configured the monitoring cluster to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://es-mon-1:9200`. + + ::::{important} + The {{es}} {monitor-features} use ingest pipelines, therefore the cluster that stores the monitoring data must have at least one [ingest node](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md). + :::: + + + If {{es}} {security-features} are enabled on the monitoring cluster, you must provide a valid user ID and password so that {{metricbeat}} can send metrics successfully: + + 1. Create a user on the monitoring cluster that has the [`remote_monitoring_agent` built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). Alternatively, use the [`remote_monitoring_user` built-in user](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + 2. Add the `username` and `password` settings to the {{es}} output information in the {{metricbeat}} configuration file. + + For more information about these configuration options, see [Configure the {{es}} output](https://www.elastic.co/guide/en/beats/metricbeat/current/elasticsearch-output.html). + +6. [Start {{metricbeat}}](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-starting.html) on each node. +7. [View the monitoring data in {{kib}}](monitoring-data.md). + diff --git a/deploy-manage/monitor/stack-monitoring/ece-restrictions-monitoring.md b/deploy-manage/monitor/stack-monitoring/ece-restrictions-monitoring.md new file mode 100644 index 000000000..a11e1d8de --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/ece-restrictions-monitoring.md @@ -0,0 +1,12 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restrictions-monitoring.html +--- + +# Restrictions and limitations [ece-restrictions-monitoring] + +* To avoid compatibility issues, ensure your monitoring cluster and production cluster run on the same {{stack}} version. Monitoring clusters that use 8.x do work with production clusters that use the latest release of 7.x, but this setup should only occur when upgrading clusters to the same version. +* $$$cross-region-monitor$$$ Monitoring across regions is not supported. If you need to move your existing monitoring to the same region, you can do a reindex or create a new deployment and select the snapshot from the old deployment. +* The logs shipped to a monitoring cluster use an ILM managed data stream (elastic-cloud-logs-). If you need to delete indices due to space, do not delete the current is_write_enabled: true index. +* When sending metrics to a dedicated monitoring deployment, the graph for IO Operations Rate(/s) is blank. This is due to the fact that this graph actually contains metrics from of all of the virtualized resources from the provider. + diff --git a/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md b/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md new file mode 100644 index 000000000..59d38d2ea --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-production.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/secure-monitoring.html +--- + +# Elasticsearch monitoring self-managed + +% What needs to be done: Refine + +% Scope notes: Consider refine vs lift-and-shift. The title needs to be updated at least. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/monitoring-production.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/secure-monitoring.md \ No newline at end of file diff --git a/deploy-manage/monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md b/deploy-manage/monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md new file mode 100644 index 000000000..d6c6f0be2 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md @@ -0,0 +1,248 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-enable-logging-and-monitoring.html +--- + +# Enable stack monitoring on ECE deployments [ece-enable-logging-and-monitoring] + +The deployment logging and monitoring feature lets you monitor your deployment in [Kibana](../../../get-started/the-stack.md) by shipping logs and metrics to a monitoring deployment. You can: + +* View your deployment’s health and performance in real time and analyze past cluster, index, and node metrics. +* View your deployment’s logs to debug issues, discover slow queries, surface deprecations, and analyze access to your deployment. + +Monitoring consists of two components: + +* A monitoring and logging agent that is installed on each node in your deployment. The agents collect and index metrics to {{es}}, either on the same deployment or by sending logs and metrics to an external monitoring deployment. Elastic Cloud Enterprise manages the installation and configuration of the monitoring agent for you, and you should not modify any of the settings. +* The stack monitoring application in Kibana that visualizes the monitoring metrics through a dashboard and the logs application that allows you to search and analyze deployment logs. + +The steps in this section cover only the enablement of the monitoring and logging features in Elastic Cloud Enterprise. For more information on how to use the monitoring features, refer to [Monitor a cluster](../../monitor.md). + + +### Before you begin [ece-logging-and-monitoring-limitations] + +Some limitations apply when you use monitoring on Elastic Cloud Enterprise. To learn more, check the monitoring [restrictions and limitations](ece-restrictions-monitoring.md). + + +### Monitoring for production use [ece-logging-and-monitoring-production] + +For production use, you should send your deployment logs and metrics to a dedicated monitoring deployment. Monitoring indexes logs and metrics into {{es}} and these indexes consume storage, memory, and CPU cycles like any other index. By using a separate monitoring deployment, you avoid affecting your other production deployments and can view the logs and metrics even when a production deployment is unavailable. + +How many monitoring deployments you use depends on your requirements: + +* You can ship logs and metrics for many deployments to a single monitoring deployment, if your business requirements permit it. +* Although monitoring will work with a deployment running a single node, you need a minimum of three monitoring nodes to make monitoring highly available. +* You might need to create dedicated monitoring deployments for isolation purposes in some cases. For example: + + * If you have many deployments and some of them are much larger than others, creating separate monitoring deployments prevents a large deployment from potentially affecting monitoring performance for smaller deployments. + * If you need to silo {{es}} data for different business departments. Deployments that have been configured to ship logs and metrics to a target monitoring deployment have access to indexing data and can manage monitoring index templates, which is addressed by creating separate monitoring deployments. + + +Logs and metrics that get sent to a dedicated monitoring {{es}} deployment [may not be cleaned up automatically](#ece-logging-and-monitoring-retention) and might require some additional steps to remove excess data periodically. + + +### Retention of monitoring daily indices [ece-logging-and-monitoring-retention] + + +#### Stack versions 8.0 and above [ece-logging-and-monitoring-retention-8] + +When you enable monitoring in Elastic Cloud Enterprise, your monitoring indices are retained for a certain period by default. After the retention period has passed, the monitoring indices are deleted automatically. The retention period is configured in the `.monitoring-8-ilm-policy` index lifecycle policy. To view or edit the policy open {{kib}} **Stack management > Data > Index Lifecycle Policies**. + + +### Sending monitoring data to itself (self monitoring) [ece-logging-and-monitoring-retention-self-monitoring] + +$$$ece-logging-and-monitoring-retention-7$$$ +When you enable self-monitoring in Elastic Cloud Enterprise, your monitoring indices are retained for a certain period by default. After the retention period has passed, the monitoring indices are deleted automatically. Monitoring data is retained for three days by default or as specified by the [`xpack.monitoring.history.duration` user setting](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-change-user-settings-examples.html#xpack-monitoring-history-duration). + +To retain monitoring indices as is without deleting them automatically, you must disable the [cleaner service](local-exporter.md#local-exporter-cleaner) by adding a disabled local exporter in your cluster settings. + +For example + +```sh +PUT /_cluster/settings +{ + "persistent": { + "xpack.monitoring.exporters.__no-default-local__": { + "type": "local", + "enabled": false + } + } +} +``` + + +### Sending monitoring data to a dedicated monitoring deployment [ece-logging-and-monitoring-retention-dedicated-monitoring] + +When [monitoring for production use](#ece-logging-and-monitoring-production), where you configure your deployments **to send monitoring data to a dedicated monitoring deployment** for indexing, this retention period does not apply. Monitoring indices on a dedicated monitoring deployment are retained until you remove them. There are three options open to you: + +* To enable the automatic deletion of monitoring indices from dedicated monitoring deployments, [enable monitoring](#ece-enable-logging-and-monitoring-steps) on your dedicated monitoring deployment in Elastic Cloud Enterprise to send monitoring data to itself. When an {{es}} deployment sends monitoring data to itself, all monitoring indices are deleted automatically after the retention period, regardless of the origin of the monitoring data. +* Alternatively, you can enable the cleaner service on the monitoring deployment by creating a local exporter. You can define the retention period at the same time. + + For example + + ```sh + PUT _cluster/settings + { + "persistent": { + "xpack" : { + "monitoring" : { + "exporters" : { + "found-user-defined" : { + "type" : "local", + "enabled" : "true" + } + }, + "history" : { + "duration" : "24h" + } + } + } + } + } + ``` + +* To retain monitoring indices on a dedicated monitoring deployment as is without deleting them automatically, no additional steps are required other than making sure that you do not enable the monitoring deployment to send monitoring data to itself. You should also monitor the deployment for disk space usage and upgrade your deployment periodically, if necessary. + + +### Retention of logging indices [ece-logging-and-monitoring-log-retention] + +An ILM policy is pre-configured to manage log retention. The policy can be adjusted according to your requirements. + + +### Index management [ece-logging-and-monitoring-index-management-ilm] + +When sending monitoring data to a deployment, you can configure [Index Lifecycle Management (ILM)](../../../manage-data/lifecycle/index-lifecycle-management.md) to manage retention of your monitoring and logging indices. When sending logs to a deployment, an ILM policy is pre-configured to manage log retention and the policy can be customized to your needs. + + +### Enable logging and monitoring [ece-enable-logging-and-monitoring-steps] + +Elastic Cloud Enterprise manages the installation and configuration of the monitoring agent for you. When you enable monitoring on a deployment, you are configuring where the monitoring agent for your current deployment should send its logs and metrics. + +To enable monitoring on your deployment: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From your deployment menu, go to the **Logs and metrics** page. +4. Select **Enable**. +5. Choose where to send your logs and metrics. Select **Save**. + + If a deployment is not listed, make sure that it is running a compatible version. The monitoring deployment and production deployment must be on the same major version, cloud provider, and region. + + ::::{tip} + Remember to send logs and metrics for production deployments to a dedicated monitoring deployment, so that your production deployments are not impacted by the overhead of indexing and storing monitoring data. A dedicated monitoring deployment also gives you more control over the retention period for monitoring data. + :::: + + +::::{note} +Enabling logs and monitoring may trigger a plan change on your deployment. You can monitor the plan change progress from the deployment’s **Activity** page. +:::: + + +::::{note} +Enabling logs and monitoring requires some extra resource on a deployment. For production systems, we recommend sizing deployments with logs and monitoring enabled to at least 4 GB of RAM. +:::: + + + +### Access the monitoring application in Kibana [ece-access-kibana-monitoring] + +With monitoring enabled for your deployment, you can access the [logs](https://www.elastic.co/guide/en/kibana/current/observability.html) and [stack monitoring](../monitoring-data/visualizing-monitoring-data.md) through Kibana. + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From your deployment menu, go to the **Logs and Metrics** page. +4. Select the corresponding **View** button to check the logs or metrics data. + +Alternatively, you can access logs and metrics directly on the Kibana **Logs** and **Stack Monitoring** pages in the target monitoring deployment. You can also create an `elastic-cloud-logs-*` data view (formerly *index pattern*) to view your deployment’s logs in the Kibana **Discover** tab. Several fields are available for you to view logs based on key details, such as the source deployment: + +| Field | Description | Example value | +| --- | --- | --- | +| `service.id` | The ID of the deployment that generated the log | `6ff525333d2844539663f3b1da6c04b6` | +| `service.name` | The name of the deployment that generated the log | `My Production Deployment` | +| `cloud.availability_zone` | The availability zone in which the instance that generated the log is deployed | `ap-northeast-1d` | +| `service.node.name` | The ID of the instance that generated the log | `instance-0000000008` | +| `service.type` | The type of instance that generated the log | `elasticsearch` | +| `service.version` | The version of the stack resource that generated the log | `8.13.1` | + + +### Logging features [ece-extra-logging-features] + +When shipping logs to a monitoring deployment there are more logging features available to you. These features include: + + +#### For {{es}}: [ece-extra-logging-features-elasticsearch] + +* [Audit logging](../logging-configuration/enabling-elasticsearch-audit-logs.md) - logs security-related events on your deployment +* [Slow query and index logging](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-slowlog.html) - helps find and debug slow queries and indexing +* Verbose logging - helps debug stack issues by increasing component logs + +After you’ve enabled log delivery on your deployment, you can [add the Elasticsearch user settings](../../deploy/cloud-enterprise/edit-stack-settings.md) to enable these features. + + +#### For Kibana: [ece-extra-logging-features-kibana] + +* [Audit logging](../logging-configuration/enabling-kibana-audit-logs.md) - logs security-related events on your deployment + +After you’ve enabled log delivery on your deployment, you can [add the Kibana user settings](../../deploy/cloud-enterprise/edit-stack-settings.md) to enable this feature. + + +### Other components [ece-extra-logging-features-enterprise-search] + +Enabling log collection also supports collecting and indexing the following types of logs from other components in your deployments: + +**Enterprise Search** + +* connectors.log* +* crawler.log* +* filebeat* +* app-server.log* +* system.log* +* worker.log* +* kibana.log* + +**App Search** + +* app-search*.log + +**APM** + +* apm*.log* + +**Fleet and Elastic Agent** + +* fleet-server-json.log-* +* elastic-agent-json.log-* + +The ˆ*ˆ indicates that we also index the archived files of each type of log. + +Check the respective product documentation for more information about the logging capabilities of each product. + + +## Metrics features [ece-extra-metrics-features] + +With logging and monitoring enabled for a deployment, metrics are collected for Elasticsearch, Kibana, Enterprise Search, and APM with Fleet Server. + + +#### Enabling Elasticsearch/Kibana audit logs on your deployment [ece-enable-audit-logs] + +Audit logs are useful for tracking security events on your {{es}} and/or {{kib}} clusters. To enable {{es}} audit logs on your deployment: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From your deployment menu, go to the **Edit** page. +4. To enable audit logs in {{es}}, in the **Elasticsearch** section select **Manage user settings and extensions**. For deployments with existing user settings, you may have to expand the **Edit elasticsearch.yml** caret for each node instead. +5. To enable audit logs in {{kib}}, in the **Kibana** section select **Edit user settings**. For deployments with existing user settings, you may have to expand the **Edit kibana.yml** caret instead. +6. Add `xpack.security.audit.enabled: true` to the user settings. +7. Select **Save changes**. + +A plan change will run on your deployment. When it finishes, audit logs will be delivered to your monitoring deployment. + + diff --git a/deploy-manage/monitor/stack-monitoring/enable-stack-monitoring-on-eck-deployments.md b/deploy-manage/monitor/stack-monitoring/enable-stack-monitoring-on-eck-deployments.md new file mode 100644 index 000000000..defe7cfe8 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/enable-stack-monitoring-on-eck-deployments.md @@ -0,0 +1,86 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-stack-monitoring.html +--- + +# Enable stack monitoring on ECK deployments [k8s-stack-monitoring] + +You can enable [Stack Monitoring](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitor-elasticsearch-cluster.html) on Elasticsearch, Kibana, Beats and Logstash to collect and ship their metrics and logs to a monitoring cluster. Although self-monitoring is possible, it is advised to use a [separate monitoring cluster](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-overview.html). + +To enable Stack Monitoring, simply reference the monitoring Elasticsearch cluster in the `spec.monitoring` section of their specification. + +The following example shows how Elastic Stack components can be configured to send their monitoring data to a separate Elasticsearch cluster in the same Kubernetes cluster. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: monitored-sample + namespace: production +spec: + version: 8.16.1 + monitoring: + metrics: + elasticsearchRefs: + - name: monitoring <1> + namespace: observability <2> + logs: + elasticsearchRefs: + - name: monitoring <1> + namespace: observability <2> + nodeSets: + - name: default + count: 1 + config: + node.store.allow_mmap: false + +apiVersion: beat.k8s.elastic.co/v1beta1 +kind: Beat +metadata: + name: monitored-sample +spec: + type: filebeat + version: 8.16.1 + monitoring: + metrics: + elasticsearchRefs: + - name: monitoring + namespace: observability <2> + logs: + elasticsearchRefs: + - name: monitoring + namespace: observability <2> +--- +apiVersion: logstash.k8s.elastic.co/v1alpha1 +kind: Logstash +metadata: + name: monitored-sample +spec: + version: 8.16.1 + monitoring: + metrics: + elasticsearchRefs: + - name: monitoring + namespace: observability <2> + logs: + elasticsearchRefs: + - name: monitoring + namespace: observability <2> +``` + +1. The same monitoring cluster is used for metrics and logs, but separate clusters could be used. +2. The use of `namespace` is optional if the monitoring Elasticsearch cluster and the monitored Elastic Stack resource are running in the same namespace. + + +::::{note} +If Logs Stack Monitoring is configured for a Beat, and custom container arguments (`podTemplate.spec.containers[].args`) include `-e`, which enables logging to stderr and disables log file output, this argument will be removed from the Pod to allow the Filebeat sidecar to consume the Beat’s log files. +:::: + + +You can also enable Stack Monitoring on a single Stack component only. In case Elasticsearch is not monitored, other Stack components will not be available on the Stack Monitoring Kibana page (check [View monitoring data in Kibana](https://www.elastic.co/guide/en/kibana/current/monitoring-data.html#monitoring-data)). + + + + + + diff --git a/deploy-manage/monitor/stack-monitoring/es-monitoring-collectors.md b/deploy-manage/monitor/stack-monitoring/es-monitoring-collectors.md new file mode 100644 index 000000000..b07ba8717 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/es-monitoring-collectors.md @@ -0,0 +1,63 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-monitoring-collectors.html +--- + +# Collectors [es-monitoring-collectors] + +::::{important} +{{agent}} and {{metricbeat}} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. + +If you have previously configured legacy collection methods, you should migrate to using [{{agent}}](collecting-monitoring-data-with-elastic-agent.md) or [{{metricbeat}}](collecting-monitoring-data-with-metricbeat.md) collection. Do not use legacy collection alongside other collection methods. + +:::: + + +Collectors, as their name implies, collect things. Each collector runs once for each collection interval to obtain data from the public APIs in {{es}} and {{xpack}} that it chooses to monitor. When the data collection is finished, the data is handed in bulk to the [exporters](es-monitoring-exporters.md) to be sent to the monitoring clusters. Regardless of the number of exporters, each collector only runs once per collection interval. + +There is only one collector per data type gathered. In other words, for any monitoring document that is created, it comes from a single collector rather than being merged from multiple collectors. The {{es}} {monitor-features} currently have a few collectors because the goal is to minimize overlap between them for optimal performance. + +Each collector can create zero or more monitoring documents. For example, the `index_stats` collector collects all index statistics at the same time to avoid many unnecessary calls. + +| Collector | Data Types | Description | +| --- | --- | --- | +| Cluster Stats | `cluster_stats` | Gathers details about the cluster state, including parts of the actual clusterstate (for example `GET /_cluster/state`) and statistics about it (for example,`GET /_cluster/stats`). This produces a single document type. In versions priorto X-Pack 5.5, this was actually three separate collectors that resulted inthree separate types: `cluster_stats`, `cluster_state`, and `cluster_info`. In5.5 and later, all three are combined into `cluster_stats`. This only runs onthe *elected* master node and the data collected (`cluster_stats`) largelycontrols the UI. When this data is not present, it indicates either amisconfiguration on the elected master node, timeouts related to the collectionof the data, or issues with storing the data. Only a single document is producedper collection. | +| Index Stats | `indices_stats`, `index_stats` | Gathers details about the indices in the cluster, both in summary andindividually. This creates many documents that represent parts of the indexstatistics output (for example, `GET /_stats`). This information only needs tobe collected once, so it is collected on the *elected* master node. The mostcommon failure for this collector relates to an extreme number of indices — andtherefore time to gather them — resulting in timeouts. One summary`indices_stats` document is produced per collection and one `index_stats`document is produced per index, per collection. | +| Index Recovery | `index_recovery` | Gathers details about index recovery in the cluster. Index recovery representsthe assignment of *shards* at the cluster level. If an index is not recovered,it is not usable. This also corresponds to shard restoration via snapshots. Thisinformation only needs to be collected once, so it is collected on the *elected*master node. The most common failure for this collector relates to an extremenumber of shards — and therefore time to gather them — resulting in timeouts.This creates a single document that contains all recoveries by default, whichcan be quite large, but it gives the most accurate picture of recovery in theproduction cluster. | +| Shards | `shards` | Gathers details about all *allocated* shards for all indices, particularlyincluding what node the shard is allocated to. This information only needs to becollected once, so it is collected on the *elected* master node. The collectoruses the local cluster state to get the routing table without any networktimeout issues unlike most other collectors. Each shard is represented by aseparate monitoring document. | +| Jobs | `job_stats` | Gathers details about all machine learning job statistics (for example, `GET/_ml/anomaly_detectors/_stats`). This information only needs to be collectedonce, so it is collected on the *elected* master node. However, for the masternode to be able to perform the collection, the master node must have`xpack.ml.enabled` set to true (default) and a license level that supports {{ml}}. | +| Node Stats | `node_stats` | Gathers details about the running node, such as memory utilization and CPUusage (for example, `GET /_nodes/_local/stats`). This runs on *every* node with{{monitor-features}} enabled. One common failure results in the timeout of the nodestats request due to too many segment files. As a result, the collector spendstoo much time waiting for the file system stats to be calculated until itfinally times out. A single `node_stats` document is created per collection.This is collected per node to help to discover issues with nodes communicatingwith each other, but not with the monitoring cluster (for example, intermittentnetwork issues or memory pressure). | + +The {{es}} {monitor-features} use a single threaded scheduler to run the collection of {{es}} monitoring data by all of the appropriate collectors on each node. This scheduler is managed locally by each node and its interval is controlled by specifying the `xpack.monitoring.collection.interval`, which defaults to 10 seconds (`10s`), at either the node or cluster level. + +Fundamentally, each collector works on the same principle. Per collection interval, each collector is checked to see whether it should run and then the appropriate collectors run. The failure of an individual collector does not impact any other collector. + +Once collection has completed, all of the monitoring data is passed to the exporters to route the monitoring data to the monitoring clusters. + +If gaps exist in the monitoring charts in {{kib}}, it is typically because either a collector failed or the monitoring cluster did not receive the data (for example, it was being restarted). In the event that a collector fails, a logged error should exist on the node that attempted to perform the collection. + +::::{note} +Collection is currently done serially, rather than in parallel, to avoid extra overhead on the elected master node. The downside to this approach is that collectors might observe a different version of the cluster state within the same collection period. In practice, this does not make a significant difference and running the collectors in parallel would not prevent such a possibility. +:::: + + +For more information about the configuration options for the collectors, see [Monitoring collection settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html#monitoring-collection-settings). + + +## Collecting data from across the Elastic Stack [es-monitoring-stack] + +{{es}} {monitor-features} also receive monitoring data from other parts of the Elastic Stack. In this way, it serves as an unscheduled monitoring data collector for the stack. + +By default, data collection is disabled. {{es}} monitoring data is not collected and all monitoring data from other sources such as {{kib}}, Beats, and Logstash is ignored. You must set `xpack.monitoring.collection.enabled` to `true` to enable the collection of monitoring data. See [Monitoring settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html). + +Once data is received, it is forwarded to the exporters to be routed to the monitoring cluster like all monitoring data. + +::::{warning} +Because this stack-level "collector" lives outside of the collection interval of {{es}} {monitor-features}, it is not impacted by the `xpack.monitoring.collection.interval` setting. Therefore, data is passed to the exporters whenever it is received. This behavior can result in indices for {{kib}}, Logstash, or Beats being created somewhat unexpectedly. +:::: + + +While the monitoring data is collected and processed, some production cluster metadata is added to incoming documents. This metadata enables {{kib}} to link the monitoring data to the appropriate cluster. If this linkage is unimportant to the infrastructure that you’re monitoring, it might be simpler to configure Logstash and Beats to report monitoring data directly to the monitoring cluster. This scenario also prevents the production cluster from adding extra overhead related to monitoring data, which can be very useful when there are a large number of Logstash nodes or Beats. + +For more information about typical monitoring architectures, see [How it works](../stack-monitoring.md). + diff --git a/deploy-manage/monitor/stack-monitoring/es-monitoring-exporters.md b/deploy-manage/monitor/stack-monitoring/es-monitoring-exporters.md new file mode 100644 index 000000000..7aea5b922 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/es-monitoring-exporters.md @@ -0,0 +1,105 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-monitoring-exporters.html +--- + +# Exporters [es-monitoring-exporters] + +::::{important} +{{agent}} and {{metricbeat}} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. + +If you have previously configured legacy collection methods, you should migrate to using [{{agent}}](collecting-monitoring-data-with-elastic-agent.md) or [{{metricbeat}}](collecting-monitoring-data-with-metricbeat.md) collection. Do not use legacy collection alongside other collection methods. + +:::: + + +The purpose of exporters is to take data collected from any Elastic Stack source and route it to the monitoring cluster. It is possible to configure more than one exporter, but the general and default setup is to use a single exporter. + +There are two types of exporters in {{es}}: + +`local` +: The default exporter used by {{es}} {monitor-features}. This exporter routes data back into the *same* cluster. See [Local exporters](local-exporter.md). + +`http` +: The preferred exporter, which you can use to route data into any supported {{es}} cluster accessible via HTTP. Production environments should always use a separate monitoring cluster. See [HTTP exporters](http-exporter.md). + +Both exporters serve the same purpose: to set up the monitoring cluster and route monitoring data. However, they perform these tasks in very different ways. Even though things happen differently, both exporters are capable of sending all of the same data. + +Exporters are configurable at both the node and cluster level. Cluster-wide settings, which are updated with the [`_cluster/settings` API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html), take precedence over settings in the `elasticsearch.yml` file on each node. When you update an exporter, it is completely replaced by the updated version of the exporter. + +::::{important} +It is critical that all nodes share the same setup. Otherwise, monitoring data might be routed in different ways or to different places. +:::: + + +When the exporters route monitoring data into the monitoring cluster, they use `_bulk` indexing for optimal performance. All monitoring data is forwarded in bulk to all enabled exporters on the same node. From there, the exporters serialize the monitoring data and send a bulk request to the monitoring cluster. There is no queuing—​in memory or persisted to disk—​so any failure during the export results in the loss of that batch of monitoring data. This design limits the impact on {{es}} and the assumption is that the next pass will succeed. + +Routing monitoring data involves indexing it into the appropriate monitoring indices. Once the data is indexed, it exists in a monitoring index that, by default, is named with a daily index pattern. For {{es}} monitoring data, this is an index that matches `.monitoring-es-6-*`. From there, the data lives inside the monitoring cluster and must be curated or cleaned up as necessary. If you do not curate the monitoring data, it eventually fills up the nodes and the cluster might fail due to lack of disk space. + +::::{tip} +You are strongly recommended to manage the curation of indices and particularly the monitoring indices. To do so, you can take advantage of the [cleaner service](local-exporter.md#local-exporter-cleaner) or [Elastic Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/current/index.html). +:::: + + +There is also a disk watermark (known as the flood stage watermark), which protects clusters from running out of disk space. When this feature is triggered, it makes all indices (including monitoring indices) read-only until the issue is fixed and a user manually makes the index writeable again. While an active monitoring index is read-only, it will naturally fail to write (index) new data and will continuously log errors that indicate the write failure. For more information, see [Disk-based shard allocation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#disk-based-shard-allocation). + + +## Default exporters [es-monitoring-default-exporter] + +If a node or cluster does not explicitly define an exporter, the following default exporter is used: + +```yaml +xpack.monitoring.exporters.default_local: <1> + type: local +``` + +1. The exporter name uniquely defines the exporter, but it is otherwise unused. When you specify your own exporters, you do not need to explicitly overwrite or reference `default_local`. + + +If another exporter is already defined, the default exporter is *not* created. When you define a new exporter, if the default exporter exists, it is automatically removed. + + +## Exporter templates and ingest pipelines [es-monitoring-templates] + +Before exporters can route monitoring data, they must set up certain {{es}} resources. These resources include templates and ingest pipelines. The following table lists the templates that are required before an exporter can route monitoring data: + +| Template | Purpose | +| --- | --- | +| `.monitoring-alerts` | All cluster alerts for monitoring data. | +| `.monitoring-beats` | All Beats monitoring data. | +| `.monitoring-es` | All {{es}} monitoring data. | +| `.monitoring-kibana` | All {{kib}} monitoring data. | +| `.monitoring-logstash` | All Logstash monitoring data. | + +The templates are ordinary {{es}} templates that control the default settings and mappings for the monitoring indices. + +By default, monitoring indices are created daily (for example, `.monitoring-es-6-2017.08.26`). You can change the default date suffix for monitoring indices with the `index.name.time_format` setting. You can use this setting to control how frequently monitoring indices are created by a specific `http` exporter. You cannot use this setting with `local` exporters. For more information, see [HTTP exporter settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html#http-exporter-settings). + +::::{warning} +Some users create their own templates that match *all* index patterns, which therefore impact the monitoring indices that get created. It is critical that you do not disable `_source` storage for the monitoring indices. If you do, {{kib}} {monitor-features} do not work and you cannot visualize monitoring data for your cluster. +:::: + + +The following table lists the ingest pipelines that are required before an exporter can route monitoring data: + +| Pipeline | Purpose | +| --- | --- | +| `xpack_monitoring_2` | Upgrades X-Pack monitoring data coming from X-Pack5.0 - 5.4 to be compatible with the format used in 5.5 {{monitor-features}}. | +| `xpack_monitoring_6` | A placeholder pipeline that is empty. | + +Exporters handle the setup of these resources before ever sending data. If resource setup fails (for example, due to security permissions), no data is sent and warnings are logged. + +::::{note} +Empty pipelines are evaluated on the coordinating node during indexing and they are ignored without any extra effort. This inherently makes them a safe, no-op operation. +:::: + + +For monitoring clusters that have disabled `node.ingest` on all nodes, it is possible to disable the use of the ingest pipeline feature. However, doing so blocks its purpose, which is to upgrade older monitoring data as our mappings improve over time. Beginning in 6.0, the ingest pipeline feature is a requirement on the monitoring cluster; you must have `node.ingest` enabled on at least one node. + +::::{warning} +Once any node running 5.5 or later has set up the templates and ingest pipeline on a monitoring cluster, you must use {{kib}} 5.5 or later to view all subsequent data on the monitoring cluster. The easiest way to determine whether this update has occurred is by checking for the presence of indices matching `.monitoring-es-6-*` (or more concretely the existence of the new pipeline). Versions prior to 5.5 used `.monitoring-es-2-*`. +:::: + + +Each resource that is created by an exporter has a `version` field, which is used to determine whether the resource should be replaced. The `version` field value represents the latest version of {{monitor-features}} that changed the resource. If a resource is edited by someone or something external to the {{monitor-features}}, those changes are lost the next time an automatic update occurs. + diff --git a/deploy-manage/monitor/stack-monitoring/http-exporter.md b/deploy-manage/monitor/stack-monitoring/http-exporter.md new file mode 100644 index 000000000..05c168b4c --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/http-exporter.md @@ -0,0 +1,81 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/http-exporter.html +--- + +# HTTP exporters [http-exporter] + +::::{important} +{{agent}} and {{metricbeat}} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. + +If you have previously configured legacy collection methods, you should migrate to using [{{agent}}](collecting-monitoring-data-with-elastic-agent.md) or [{{metricbeat}}](collecting-monitoring-data-with-metricbeat.md) collection. Do not use legacy collection alongside other collection methods. + +:::: + + +The `http` exporter is the preferred exporter in the {{es}} {monitor-features} because it enables the use of a separate monitoring cluster. As a secondary benefit, it avoids using a production cluster node as a coordinating node for indexing monitoring data because all requests are HTTP requests to the monitoring cluster. + +The `http` exporter uses the low-level {{es}} REST Client, which enables it to send its data to any {{es}} cluster it can access through the network. Its requests make use of the [`filter_path`](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#common-options-response-filtering) parameter to reduce bandwidth whenever possible, which helps to ensure that communications between the production and monitoring clusters are as lightweight as possible. + +The `http` exporter supports a number of settings that control how it communicates over HTTP to remote clusters. In most cases, it is not necessary to explicitly configure these settings. For detailed descriptions, see [Monitoring settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html). + +```yaml +xpack.monitoring.exporters: + my_local: <1> + type: local + my_remote: <2> + type: http + host: [ "10.1.2.3:9200", ... ] <3> + auth: <4> + username: my_username + # "xpack.monitoring.exporters.my_remote.auth.secure_password" must be set in the keystore + connection: + timeout: 6s + read_timeout: 60s + ssl: ... <5> + proxy: + base_path: /some/base/path <6> + headers: <7> + My-Proxy-Header: abc123 + My-Other-Thing: [ def456, ... ] + index.name.time_format: YYYY-MM <8> +``` + +1. A `local` exporter defined explicitly whose arbitrary name is `my_local`. +2. An `http` exporter defined whose arbitrary name is `my_remote`. This name uniquely defines the exporter but is otherwise unused. +3. `host` is a required setting for `http` exporters. It must specify the HTTP port rather than the transport port. The default port value is `9200`. +4. User authentication for those using {{stack}} {security-features} or some other form of user authentication protecting the cluster. +5. See [HTTP exporter settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html#http-exporter-settings) for all TLS/SSL settings. If not supplied, the default node-level TLS/SSL settings are used. +6. Optional base path to prefix any outgoing request with in order to work with proxies. +7. Arbitrary key/value pairs to define as headers to send with every request. The array-based key/value format sends one header per value. +8. A mechanism for changing the date suffix used by default. + + +::::{note} +The `http` exporter accepts an array of `hosts` and it will round robin through the list. It is a good idea to take advantage of that feature when the monitoring cluster contains more than one node. +:::: + + +Unlike the `local` exporter, *every* node that uses the `http` exporter attempts to check and create the resources that it needs. The `http` exporter avoids re-checking the resources unless something triggers it to perform the checks again. These triggers include: + +* The production cluster’s node restarts. +* A connection failure to the monitoring cluster. +* The license on the production cluster changes. +* The `http` exporter is dynamically updated (and it is therefore replaced). + +The easiest way to trigger a check is to disable, then re-enable the exporter. + +::::{warning} +This resource management behavior can create a hole for users that delete monitoring resources. Since the `http` exporter does not re-check its resources unless one of the triggers occurs, this can result in malformed index mappings. +:::: + + +Unlike the `local` exporter, the `http` exporter is inherently routing requests outside of the cluster. This situation means that the exporter must provide a username and password when the monitoring cluster requires one (or other appropriate security configurations, such as TLS/SSL settings). + +::::{important} +When discussing security relative to the `http` exporter, it is critical to remember that all users are managed on the monitoring cluster. This is particularly important to remember when you move from development environments to production environments, where you often have dedicated monitoring clusters. +:::: + + +For more information about the configuration options for the `http` exporter, see [HTTP exporter settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html#http-exporter-settings). + diff --git a/deploy-manage/monitor/stack-monitoring/k8s_audit_logging.md b/deploy-manage/monitor/stack-monitoring/k8s_audit_logging.md new file mode 100644 index 000000000..819713023 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/k8s_audit_logging.md @@ -0,0 +1,45 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_audit_logging.html +--- + +# Audit logging [k8s_audit_logging] + +Audit logs are collected and shipped to the monitoring cluster referenced in the `monitoring.logs` section when audit logging is enabled (it is disabled by default). + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +spec: + monitoring: + metrics: + elasticsearchRefs: + - name: monitoring + namespace: observability + logs: + elasticsearchRefs: + - name: monitoring + namespace: observability + nodeSets: + - name: default + config: + # https://www.elastic.co/guide/en/elasticsearch/reference/current/enable-audit-logging.html + xpack.security.audit.enabled: true +--- +apiVersion: kibana.k8s.elastic.co/v1 +kind: Kibana +spec: + monitoring: + metrics: + elasticsearchRefs: + - name: monitoring + namespace: observability + logs: + elasticsearchRefs: + - name: monitoring + namespace: observability + config: + # https://www.elastic.co/guide/en/kibana/current/xpack-security-audit-logging.html + xpack.security.audit.enabled: true +``` + diff --git a/deploy-manage/monitor/stack-monitoring/k8s_connect_to_an_external_monitoring_elasticsearch_cluster.md b/deploy-manage/monitor/stack-monitoring/k8s_connect_to_an_external_monitoring_elasticsearch_cluster.md new file mode 100644 index 000000000..800a8334c --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/k8s_connect_to_an_external_monitoring_elasticsearch_cluster.md @@ -0,0 +1,57 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_connect_to_an_external_monitoring_elasticsearch_cluster.html +--- + +# Connect to an external monitoring Elasticsearch cluster [k8s_connect_to_an_external_monitoring_elasticsearch_cluster] + +If you want to connect to a monitoring Elasticsearch cluster not managed by ECK, you can reference a Secret instead of an Elastisearch cluster in the `monitoring` section through the `secretName` attribute: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: monitored-sample + namespace: production +spec: + version: 8.16.1 + monitoring: + metrics: + elasticsearchRefs: + - secretName: monitoring-metrics-es-ref <1> + logs: + elasticsearchRefs: + - name: monitoring-logs + namespace: observability <2> + serviceName: monitoring-logs-es-coordinating-nodes <2> + nodeSets: + - name: default + count: 1 + config: + node.store.allow_mmap: false +``` + +1. The `secretName` and `name` attributes are mutually exclusive, you have to choose one or the other. +2. The `namespace` and `serviceName` attributes can only be used in conjunction with `name`, not with `secretName`. + + +The referenced Secret must contain the following connection information: + +* `url`: the URL to reach the Elasticsearch cluster +* `username`: the username of the user to be authenticated to the Elasticsearch cluster +* `password`: the password of the user to be authenticated to the Elasticsearch cluster +* `ca.crt`: the contents of the CA certificate in PEM format to secure communication to the Elasticsearch cluster (optional) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: monitoring-metrics-es-ref +stringData: + url: https://mon1.es.abcd-42.xyz.elastic-cloud.com:9243 + username: monitoring-user + password: REDACTED +``` + +The user referenced in the Secret must have been created beforehand. + diff --git a/deploy-manage/monitor/stack-monitoring/k8s_how_it_works.md b/deploy-manage/monitor/stack-monitoring/k8s_how_it_works.md new file mode 100644 index 000000000..777b2440d --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/k8s_how_it_works.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_how_it_works.html +--- + +# How it works [k8s_how_it_works] + +In the background, Metricbeat and Filebeat are deployed as sidecar containers in the same Pod as Elasticsearch and Kibana. + +Metricbeat is used to collect monitoring metrics and Filebeat to monitor the Elasticsearch log files and collect log events. + +The two Beats are configured to ship data directly to the monitoring cluster(s) using HTTPS and dedicated Elastic users managed by ECK. + diff --git a/deploy-manage/monitor/stack-monitoring/k8s_override_the_beats_pod_template.md b/deploy-manage/monitor/stack-monitoring/k8s_override_the_beats_pod_template.md new file mode 100644 index 000000000..62e7daa88 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/k8s_override_the_beats_pod_template.md @@ -0,0 +1,35 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_override_the_beats_pod_template.html +--- + +# Override the Beats Pod Template [k8s_override_the_beats_pod_template] + +You can customize the Filebeat and Metricbeat containers through the Pod template. Your configuration is merged with the values of the default Pod template that ECK uses. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +spec: + monitoring: + metrics: + elasticsearchRef: + name: monitoring + namespace: observability + logs: + elasticsearchRef: + name: monitoring + namespace: observability + nodeSets: + - name: default + podTemplate: + spec: + containers: + - name: metricbeat + env: + - foo: bar + - name: filebeat + env: + - foo: bar +``` + diff --git a/deploy-manage/monitor/stack-monitoring/k8s_when_to_use_it.md b/deploy-manage/monitor/stack-monitoring/k8s_when_to_use_it.md new file mode 100644 index 000000000..1f880569c --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/k8s_when_to_use_it.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s_when_to_use_it.html +--- + +# When to use it [k8s_when_to_use_it] + +This feature is a good solution if you need to monitor your Elastic applications in restricted Kubernetes environments where you cannot grant advanced permissions: + +* to Metricbeat to allow queriying the k8s API +* to Filebeat to deploy a privileged DaemonSet + +However, for maximum efficiency and minimising resource consumption, or advanced use cases that require specific Beats configurations, you can deploy a standalone Metricbeat Deployment and a Filebeat Daemonset. Check the [Beats configuration Examples](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-beat-configuration-examples.html) for more information. + diff --git a/deploy-manage/monitor/stack-monitoring/kibana-monitoring-self-managed.md b/deploy-manage/monitor/stack-monitoring/kibana-monitoring-self-managed.md new file mode 100644 index 000000000..f50125f5a --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/kibana-monitoring-self-managed.md @@ -0,0 +1,25 @@ +--- +navigation_title: "Configure monitoring" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/configuring-monitoring.html +--- + + + +# Kibana monitoring self-managed [configuring-monitoring] + + +If you enable the {{monitor-features}} in your cluster, there are a few methods available to collect metrics about {{kib}}: + +* [{{agent}} collection](monitoring-elastic-agent.md): Uses a single agent to gather logs and metrics. Can be managed from a central location in {{fleet}}. +* [{{metricbeat}} collection](monitoring-metricbeat.md): Uses a lightweight {{beats}} shipper to gather metrics. May be preferred if you have an existing investment in {{beats}} or are not yet ready to use {{agent}}. +* [Legacy collection](monitoring-kibana.md): Uses internal collectors to gather metrics. Not recommended. If you have previously configured legacy collection methods, you should migrate to using {{agent}} or {{metricbeat}}. + +You can also use {{kib}} to [visualize monitoring data from across the {{stack}}](monitoring-data.md). + +To learn about monitoring in general, see [Monitor a cluster](../../monitor.md). + + + + + diff --git a/deploy-manage/monitor/stack-monitoring/legacy-collection-methods.md b/deploy-manage/monitor/stack-monitoring/legacy-collection-methods.md new file mode 100644 index 000000000..b53a15917 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/legacy-collection-methods.md @@ -0,0 +1,157 @@ +--- +navigation_title: "Legacy collection methods" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/collecting-monitoring-data.html +--- + + + +# Legacy collection methods [collecting-monitoring-data] + + +::::{admonition} Deprecated in 7.16. +:class: warning + +Using the {{es}} Monitoring plugin to collect and ship monitoring data is deprecated. {{agent}} and {{metricbeat}} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. If you previously configured legacy collection methods, you should migrate to using [{{agent}}](collecting-monitoring-data-with-elastic-agent.md) or [{{metricbeat}}](collecting-monitoring-data-with-metricbeat.md) collection methods. +:::: + + +This method for collecting metrics about {{es}} involves sending the metrics to the monitoring cluster by using exporters. + +Advanced monitoring settings enable you to control how frequently data is collected, configure timeouts, and set the retention period for locally-stored monitoring indices. You can also adjust how monitoring data is displayed. + +To learn about monitoring in general, see [Monitor a cluster](../../monitor.md). + +1. Configure your cluster to collect monitoring data: + + 1. Verify that the `xpack.monitoring.elasticsearch.collection.enabled` setting is `true`, which is its default value, on each node in the cluster. + + ::::{note} + You can specify this setting in either the `elasticsearch.yml` on each node or across the cluster as a dynamic cluster setting. If {{es}} {security-features} are enabled, you must have `monitor` cluster privileges to view the cluster settings and `manage` cluster privileges to change them. + :::: + + + For more information, see [Monitoring settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html) and [Cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). + + 2. Set the `xpack.monitoring.collection.enabled` setting to `true` on each node in the cluster. By default, it is disabled (`false`). + + ::::{note} + You can specify this setting in either the `elasticsearch.yml` on each node or across the cluster as a dynamic cluster setting. If {{es}} {security-features} are enabled, you must have `monitor` cluster privileges to view the cluster settings and `manage` cluster privileges to change them. + :::: + + + For example, use the following APIs to review and change this setting: + + ```console + GET _cluster/settings + ``` + + ```console + PUT _cluster/settings + { + "persistent": { + "xpack.monitoring.collection.enabled": true + } + } + ``` + + Alternatively, you can enable this setting in {{kib}}. In the side navigation, click **Monitoring**. If data collection is disabled, you are prompted to turn it on. + + For more information, see [Monitoring settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html) and [Cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). + + 3. Optional: Specify which indices you want to monitor. + + By default, the monitoring agent collects data from all {{es}} indices. To collect data from particular indices, configure the `xpack.monitoring.collection.indices` setting. You can specify multiple indices as a comma-separated list or use an index pattern to match multiple indices. For example: + + ```yaml + xpack.monitoring.collection.indices: logstash-*, index1, test2 + ``` + + You can prepend `-` to explicitly exclude index names or patterns. For example, to include all indices that start with `test` except `test3`, you could specify `test*,-test3`. To include system indices such as .security and .kibana, add `.*` to the list of included names. For example `.*,test*,-test3` + + 4. Optional: Specify how often to collect monitoring data. The default value for the `xpack.monitoring.collection.interval` setting 10 seconds. See [Monitoring settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html). + +2. Identify where to store monitoring data. + + By default, the data is stored on the same cluster by using a [`local` exporter](local-exporter.md). Alternatively, you can use an [`http` exporter](http-exporter.md) to send data to a separate *monitoring cluster*. + + ::::{important} + The {{es}} {monitor-features} use ingest pipelines, therefore the cluster that stores the monitoring data must have at least one [ingest node](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md). + :::: + + + For more information about typical monitoring architectures, see [How it works](../stack-monitoring.md). + +3. If you choose to use an `http` exporter: + + 1. On the cluster that you want to monitor (often called the *production cluster*), configure each node to send metrics to your monitoring cluster. Configure an HTTP exporter in the `xpack.monitoring.exporters` settings in the `elasticsearch.yml` file. For example: + + ```yaml + xpack.monitoring.exporters: + id1: + type: http + host: ["http://es-mon-1:9200", "http://es-mon-2:9200"] + ``` + + 2. If the Elastic {{security-features}} are enabled on the monitoring cluster, you must provide appropriate credentials when data is shipped to the monitoring cluster: + + 1. Create a user on the monitoring cluster that has the [`remote_monitoring_agent` built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). Alternatively, use the [`remote_monitoring_user` built-in user](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + 2. Add the user ID and password settings to the HTTP exporter settings in the `elasticsearch.yml` file and keystore on each node.
+ + For example: + + ```yaml + xpack.monitoring.exporters: + id1: + type: http + host: ["http://es-mon-1:9200", "http://es-mon-2:9200"] + auth.username: remote_monitoring_user + # "xpack.monitoring.exporters.id1.auth.secure_password" must be set in the keystore + ``` + + 3. If you configured the monitoring cluster to use [encrypted communications](../../security/secure-cluster-communications.md#encrypt-internode-communication), you must use the HTTPS protocol in the `host` setting. You must also specify the trusted CA certificates that will be used to verify the identity of the nodes in the monitoring cluster. + + * To add a CA certificate to an {{es}} node’s trusted certificates, you can specify the location of the PEM encoded certificate with the `certificate_authorities` setting. For example: + + ```yaml + xpack.monitoring.exporters: + id1: + type: http + host: ["https://es-mon1:9200", "https://es-mon-2:9200"] + auth: + username: remote_monitoring_user + # "xpack.monitoring.exporters.id1.auth.secure_password" must be set in the keystore + ssl: + certificate_authorities: [ "/path/to/ca.crt" ] + ``` + + * Alternatively, you can configure trusted certificates using a truststore (a Java Keystore file that contains the certificates). For example: + + ```yaml + xpack.monitoring.exporters: + id1: + type: http + host: ["https://es-mon1:9200", "https://es-mon-2:9200"] + auth: + username: remote_monitoring_user + # "xpack.monitoring.exporters.id1.auth.secure_password" must be set in the keystore + ssl: + truststore.path: /path/to/file + truststore.password: password + ``` + +4. Configure your cluster to route monitoring data from sources such as {{kib}}, Beats, and {{ls}} to the monitoring cluster. For information about configuring each product to collect and send monitoring data, see [Monitor a cluster](../../monitor.md). +5. If you updated settings in the `elasticsearch.yml` files on your production cluster, restart {{es}}. See [*Stopping Elasticsearch*](../../maintenance/start-stop-services/start-stop-elasticsearch.md) and [*Starting Elasticsearch*](../../maintenance/start-stop-services/start-stop-elasticsearch.md). + + ::::{tip} + You may want to temporarily [disable shard allocation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html) before you restart your nodes to avoid unnecessary shard reallocation during the install process. + :::: + +6. Optional: [Configure the indices that store the monitoring data](../monitoring-data/configuring-data-streamsindices-for-monitoring.md). +7. [View the monitoring data in {{kib}}](monitoring-data.md). + + + + + + diff --git a/deploy-manage/monitor/stack-monitoring/local-exporter.md b/deploy-manage/monitor/stack-monitoring/local-exporter.md new file mode 100644 index 000000000..895eb9490 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/local-exporter.md @@ -0,0 +1,69 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/local-exporter.html +--- + +# Local exporters [local-exporter] + +::::{important} +{{agent}} and {{metricbeat}} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. + +If you have previously configured legacy collection methods, you should migrate to using [{{agent}}](collecting-monitoring-data-with-elastic-agent.md) or [{{metricbeat}}](collecting-monitoring-data-with-metricbeat.md) collection. Do not use legacy collection alongside other collection methods. + +:::: + + +The `local` exporter is the default exporter in {{monitoring}}. It routes data back into the same (local) cluster. In other words, it uses the production cluster as the monitoring cluster. For example: + +```yaml +xpack.monitoring.exporters.my_local_exporter: <1> + type: local +``` + +1. The exporter name uniquely defines the exporter, but it is otherwise unused. + + +This exporter exists to provide a convenient option when hardware is simply not available. It is also a way for developers to get an idea of what their actions do for pre-production clusters when they do not have the time or resources to provide a separate monitoring cluster. However, this exporter has disadvantages that impact the local cluster: + +* All indexing impacts the local cluster and the nodes that hold the monitoring indices' shards. +* Most collectors run on the elected master node. Therefore most indexing occurs with the elected master node as the coordinating node, which is a bad practice. +* Any usage of {{monitoring}} for {{kib}} uses the local cluster’s resources for searches and aggregations, which means that they might not be available for non-monitoring tasks. +* If the local cluster goes down, the monitoring cluster has inherently gone down with it (and vice versa), which generally defeats the purpose of monitoring. + +For the `local` exporter, all setup occurs only on the elected master node. This means that if you do not see any monitoring templates or ingest pipelines, the elected master node is having issues or it is not configured in the same way. Unlike the `http` exporter, the `local` exporter has the advantage of accessing the monitoring cluster’s up-to-date cluster state. It can therefore always check that the templates and ingest pipelines exist without a performance penalty. If the elected master node encounters errors while trying to create the monitoring resources, it logs errors, ignores that collection, and tries again after the next collection. + +The elected master node is the only node to set up resources for the `local` exporter. Therefore all other nodes wait for the resources to be set up before indexing any monitoring data from their own collectors. Each of these nodes logs a message indicating that they are waiting for the resources to be set up. + +One benefit of the `local` exporter is that it lives within the cluster and therefore no extra configuration is required when the cluster is secured with {{stack}} {security-features}. All operations, including indexing operations, that occur from a `local` exporter make use of the internal transport mechanisms within {{es}}. This behavior enables the exporter to be used without providing any user credentials when {{security-features}} are enabled. + +For more information about the configuration options for the `local` exporter, see [Local exporter settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html#local-exporter-settings). + +## Cleaner service [local-exporter-cleaner] + +One feature of the `local` exporter, which is not present in the `http` exporter, is a cleaner service. The cleaner service runs once per day at 01:00 AM UTC on the elected master node. + +The role of the cleaner service is to clean, or curate, the monitoring indices that are older than a configurable amount of time (the default is `7d`). This cleaner exists as part of the `local` exporter as a safety mechanism. The `http` exporter does not make use of it because it could enable a single misconfigured node to prematurely curate data from other production clusters that share the same monitoring cluster. + +In a dedicated monitoring cluster, you can use the cleaner service without having to monitor the monitoring cluster itself. For example: + +```yaml +xpack.monitoring.collection.enabled: false <1> +xpack.monitoring.history.duration: 3d <2> +``` + +1. Disables the collection of data on the monitoring cluster. +2. Lowers the default history duration from `7d` to `3d`. The minimum value is `1d`. This setting can be modified only when using a Gold or higher level license. For the Basic license level, it uses the default of 7 days. + + +To disable the cleaner service, add a disabled local exporter: + +```yaml +xpack.monitoring.exporters.my_local.type: local <1> +xpack.monitoring.exporters.my_local.enabled: false <2> +``` + +1. Adds a local exporter named `my_local` +2. Disables the local exporter. This also disables the cleaner service. + + + diff --git a/deploy-manage/monitor/stack-monitoring/monitoring-data.md b/deploy-manage/monitor/stack-monitoring/monitoring-data.md new file mode 100644 index 000000000..98eabc7e2 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/monitoring-data.md @@ -0,0 +1,73 @@ +--- +navigation_title: "View monitoring data" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/monitoring-data.html +--- + + + +# View monitoring data [monitoring-data] + + +After you collect monitoring data for one or more products in the {{stack}}, you can configure {{kib}} to retrieve that information and display it in on the **Stack Monitoring** page. + +At a minimum, you must have monitoring data for the {{es}} production cluster. Once that data exists, {{kib}} can display monitoring data for other products in the cluster. + +::::{tip} +If you use a separate monitoring cluster to store the monitoring data, it is strongly recommended that you use a separate {{kib}} instance to view it. If you log in to {{kib}} using SAML, Kerberos, PKI, OpenID Connect, or token authentication providers, a dedicated {{kib}} instance is **required**. The security tokens that are used in these contexts are cluster-specific, therefore you cannot use a single {{kib}} instance to connect to both production and monitoring clusters. For more information about the recommended configuration, see [Monitoring overview](../stack-monitoring.md). +:::: + + +1. Identify where to retrieve monitoring data from. + + If the monitoring data is stored on a dedicated monitoring cluster, it is accessible even when the cluster you’re monitoring is not. If you have at least a gold license, you can send data from multiple clusters to the same monitoring cluster and view them all through the same instance of {{kib}}. + + By default, data is retrieved from the cluster specified in the `elasticsearch.hosts` value in the `kibana.yml` file. If you want to retrieve it from a different cluster, set `monitoring.ui.elasticsearch.hosts`. + + To learn more about typical monitoring architectures, see [How monitoring works](../stack-monitoring.md) and [Monitoring in a production environment](elasticsearch-monitoring-self-managed.md). + +2. Verify that `monitoring.ui.enabled` is set to `true`, which is the default value, in the `kibana.yml` file. For more information, see [Monitoring settings](https://www.elastic.co/guide/en/kibana/current/monitoring-settings-kb.html). +3. If the Elastic {{security-features}} are enabled on the monitoring cluster, you must provide a user ID and password so {{kib}} can retrieve the data. + + 1. Create a user that has the `monitoring_user` [built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md) on the monitoring cluster. + + ::::{note} + Make sure the `monitoring_user` role has read privileges on `metrics-*` indices. If it doesn’t, create a new role with `read` and `read_cross_cluster` index privileges on `metrics-*`, then assign the new role (along with `monitoring_user`) to your user. + :::: + + 2. Add the `monitoring.ui.elasticsearch.username` and `monitoring.ui.elasticsearch.password` settings in the `kibana.yml` file. If these settings are omitted, {{kib}} uses the `elasticsearch.username` and `elasticsearch.password` setting values. For more information, see [Configuring security in {{kib}}](../../security.md). + +4. (Optional) Configure {{kib}} to encrypt communications between the {{kib}} server and the monitoring cluster. See [*Encrypt TLS communications in {{kib}}*](https://www.elastic.co/guide/en/kibana/current/configuring-tls.html). +5. If the Elastic {{security-features}} are enabled on the {{kib}} server, only users that have the authority to access {{kib}} indices and to read the monitoring indices can use the monitoring dashboards. + + ::::{note} + These users must exist on the monitoring cluster. If you are accessing a remote monitoring cluster, you must use credentials that are valid on both the {{kib}} server and the monitoring cluster. + :::: + + + 1. Create users that have the `monitoring_user` and `kibana_admin` [built-in roles](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). If you created a new role with read privileges on `metrics-*` indices, also assign that role to the users. + +6. Open {{kib}} in your web browser. + + By default, if you are running {{kib}} locally, go to `http://localhost:5601/`. + + If the Elastic {{security-features}} are enabled, log in. + +7. Go to the **Stack Monitoring** page using the [global search field](../../../get-started/the-stack.md#kibana-navigation-search). + + If data collection is disabled, you are prompted to turn on data collection. If {{es}} {security-features} are enabled, you must have `manage` cluster privileges to turn on data collection. + + ::::{note} + If you are using a separate monitoring cluster, you do not need to turn on data collection. The dashboards appear when there is data in the monitoring cluster. + :::: + + +You’ll see cluster alerts that require your attention and a summary of the available monitoring metrics for {{es}}, Logstash, {{kib}}, and Beats. To view additional information, click the Overview, Nodes, Indices, or Instances links. See [Stack Monitoring](../monitoring-data/visualizing-monitoring-data.md). + +:::{image} ../../../images/kibana-monitoring-dashboard.png +:alt: Monitoring dashboard +:class: screenshot +::: + +If you encounter problems, see [Troubleshooting monitoring](../monitoring-data/monitor-troubleshooting.md). + diff --git a/deploy-manage/monitor/stack-monitoring/monitoring-elastic-agent.md b/deploy-manage/monitor/stack-monitoring/monitoring-elastic-agent.md new file mode 100644 index 000000000..264f36a2b --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/monitoring-elastic-agent.md @@ -0,0 +1,55 @@ +--- +navigation_title: "Collect monitoring data with {{agent}}" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/monitoring-elastic-agent.html +--- + + + +# Collect monitoring data with Elastic Agent [monitoring-elastic-agent] + + +In 8.5 and later, you can use {{agent}} to collect data about {{kib}} and ship it to the monitoring cluster, rather than [using {{metricbeat}}](monitoring-metricbeat.md) or routing data through the production cluster as described in [Legacy collection methods](monitoring-kibana.md). + +To learn about monitoring in general, see [Monitor a cluster](../../monitor.md). + + +## Prerequisites [_prerequisites] + +* Set up {{es}} monitoring and optionally create a monitoring cluster as described in the [{{es}} monitoring documentation](elasticsearch-monitoring-self-managed.md). +* Create a user on the production cluster that has the `remote_monitoring_collector` [built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). + + +## Add {{kib}} monitoring data [_add_kib_monitoring_data] + +To collect {{kib}} monitoring data, add a {{kib}} integration to an {{agent}} and deploy it to the host where {{kib}} is running. + +1. Go to the **Integrations** page. + + ::::{note} + If you’re using a monitoring cluster, use the {{kib}} instance connected to the monitoring cluster. + :::: + +2. In the query bar, search for and select the **Kibana** integration for {{agent}}. +3. Read the overview to make sure you understand integration requirements and other considerations. +4. Click **Add Kibana**. + + ::::{tip} + If you’re installing an integration for the first time, you may be prompted to install {{agent}}. Click **Add integration only (skip agent installation)**. + :::: + +5. Configure the integration name and optionally add a description. Make sure you configure all required settings: + + * Under **Collect Kibana logs**, modify the log paths to match your {{kib}} environment. + * Under **Collect Kibana metrics**, make sure the hosts setting points to your Kibana host URLs. By default, the integration collects {{kib}} monitoring metrics from `localhost:5601`. If that host and port number are not correct, update the `hosts` setting. If you configured {{kib}} to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://localhost:5601`. + * If the Elastic {{security-features}} are enabled, expand **Advanced options** under the Hosts setting and enter the username and password of a user that has the `remote_monitoring_collector` role. + +6. Choose where to add the integration policy. Click **New hosts*** to add it to new agent policy or ***Existing hosts** to add it to an existing agent policy. +7. Click **Save and continue**. This step takes a minute or two to complete. When it’s done, you’ll have an agent policy that contains an integration for collecting monitoring data from {{kib}}. +8. If an {{agent}} is already assigned to the policy and deployed to the host where {{kib}} is running, you’re done. Otherwise, you need to deploy an {{agent}}. To deploy an {{agent}}: + + 1. Go to **{{fleet}} → Agents***, then click ***Add agent**. + 2. Follow the steps in the **Add agent** flyout to download, install, and enroll the {{agent}}. Make sure you choose the agent policy you created earlier. + +9. Wait a minute or two until incoming data is confirmed. +10. [View the monitoring data in {{kib}}](monitoring-data.md). diff --git a/deploy-manage/monitor/stack-monitoring/monitoring-kibana.md b/deploy-manage/monitor/stack-monitoring/monitoring-kibana.md new file mode 100644 index 000000000..ecea504b4 --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/monitoring-kibana.md @@ -0,0 +1,79 @@ +--- +navigation_title: "Legacy collection methods" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/monitoring-kibana.html +--- + + + +# Legacy collection methods [monitoring-kibana] + + +If you enable the Elastic {{monitor-features}} in your cluster, you can optionally collect metrics about {{kib}}. + +::::{important} +{{agent}} and {{metricbeat}} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. + +If you have previously configured legacy collection methods, you should migrate to using {{agent}} or {{metricbeat}} collection. Do not use legacy collection alongside other collection methods. + +For more information, refer to [Collect monitoring data with {{agent}}](monitoring-elastic-agent.md) and [Collect monitoring data with {{metricbeat}}](monitoring-metricbeat.md). + +:::: + + +The following method involves sending the metrics to the production cluster, which ultimately routes them to the monitoring cluster. + +To learn about monitoring in general, see [Monitor a cluster](../../monitor.md). + +1. Set the `xpack.monitoring.collection.enabled` setting to `true` on each node in the production cluster. By default, it is is disabled (`false`). + + ::::{note} + You can specify this setting in either the `elasticsearch.yml` on each node or across the cluster as a dynamic cluster setting. If {{stack-security-features}} are enabled, you must have `monitor` cluster privileges to view the cluster settings and `manage` cluster privileges to change them. + :::: + + + * To update the cluster settings in {{kib}}: + + 1. Open {{kib}} in your web browser. + + By default, if you are running {{kib}} locally, go to `http://localhost:5601/`. + + If {{security-features}} are enabled, log in. + + 2. Go to the **Stack Monitoring** page using the [global search field](../../../get-started/the-stack.md#kibana-navigation-search). If data collection is disabled, you are prompted to turn it on. + + * From the Console or command line, set `xpack.monitoring.collection.enabled` to `true` on the production cluster.
+ + For example, you can use the following APIs to review and change this setting: + + ```js + GET _cluster/settings + + PUT _cluster/settings + { + "persistent": { + "xpack.monitoring.collection.enabled": true + } + } + ``` + + For more information, see [Monitoring settings in {{es}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html) and [Cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). + +2. Verify that `monitoring.enabled` and `monitoring.kibana.collection.enabled` are set to `true` in the `kibana.yml` file. These are the default values. For more information, see [Monitoring settings in {{kib}}](https://www.elastic.co/guide/en/kibana/current/monitoring-settings-kb.html). +3. Identify where to send monitoring data. {{kib}} automatically sends metrics to the {{es}} cluster specified in the `elasticsearch.hosts` setting in the `kibana.yml` file. This property has a default value of `http://localhost:9200`.
+ + ::::{tip} + In production environments, we strongly recommend using a separate cluster (referred to as the *monitoring cluster*) to store the data. Using a separate monitoring cluster prevents production cluster outages from impacting your ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. + + If {{security-features}} are enabled on the production cluster, use an HTTPS URL such as `https://:9200` in this setting. + + :::: + +4. If {{security-features}} are enabled on the production cluster: + + 1. Verify that there is a valid user ID and password in the `elasticsearch.username` and `elasticsearch.password` settings in the `kibana.yml` file. These values are used when {{kib}} sends monitoring data to the production cluster. + 2. [Configure encryption for traffic between {{kib}} and {{es}}](https://www.elastic.co/guide/en/kibana/current/configuring-tls.html#configuring-tls-kib-es). + +5. [Start {{kib}}](../../maintenance/start-stop-services/start-stop-kibana.md). +6. [View the monitoring data in {{kib}}](monitoring-data.md). + diff --git a/deploy-manage/monitor/stack-monitoring/monitoring-metricbeat.md b/deploy-manage/monitor/stack-monitoring/monitoring-metricbeat.md new file mode 100644 index 000000000..0a9039b3c --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/monitoring-metricbeat.md @@ -0,0 +1,146 @@ +--- +navigation_title: "Collect monitoring data with {{metricbeat}}" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/monitoring-metricbeat.html +--- + + + +# Collect monitoring data with Metricbeat [monitoring-metricbeat] + + +In 6.4 and later, you can use {{metricbeat}} to collect data about {{kib}} and ship it to the monitoring cluster, rather than routing it through the production cluster as described in [Legacy collection methods](monitoring-kibana.md). + +:::{image} ../../../images/kibana-metricbeat.png +:alt: Example monitoring architecture +::: + +To learn about monitoring in general, see [Monitor a cluster](../../monitor.md). + +1. Disable the default collection of {{kib}} monitoring metrics.
+ + Add the following setting in the {{kib}} configuration file (`kibana.yml`): + + ```yaml + monitoring.kibana.collection.enabled: false + ``` + + Leave the `monitoring.enabled` set to its default value (`true`). For more information, see [Monitoring settings in {{kib}}](https://www.elastic.co/guide/en/kibana/current/monitoring-settings-kb.html). + +2. [Start {{kib}}](../../maintenance/start-stop-services/start-stop-kibana.md). +3. Set the `xpack.monitoring.collection.enabled` setting to `true` on each node in the production cluster. By default, it is disabled (`false`). + + ::::{note} + You can specify this setting in either the `elasticsearch.yml` on each node or across the cluster as a dynamic cluster setting. If {{es}} {security-features} are enabled, you must have `monitor` cluster privileges to view the cluster settings and `manage` cluster privileges to change them. + :::: + + + * In {{kib}}: + + 1. Open {{kib}} in your web browser. + + If you are running {{kib}} locally, go to `http://localhost:5601/`. + + If the Elastic {{security-features}} are enabled, log in. + + 2. In the side navigation, click **Stack Monitoring**. If data collection is disabled, you are prompted to turn it on. + + * From the Console or command line, set `xpack.monitoring.collection.enabled` to `true` on the production cluster.
+ + For example, you can use the following APIs to review and change this setting: + + ```js + GET _cluster/settings + + PUT _cluster/settings + { + "persistent": { + "xpack.monitoring.collection.enabled": true + } + } + ``` + + For more information, see [Monitoring settings in {{es}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-settings.html) and [Cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). + +4. [Install {{metricbeat}}](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-installation-configuration.html) on the same server as {{kib}}. +5. Enable the {{kib}} {xpack} module in {{metricbeat}}.
+ + For example, to enable the default configuration in the `modules.d` directory, run the following command: + + ```sh + metricbeat modules enable kibana-xpack + ``` + + For more information, see [Specify which modules to run](https://www.elastic.co/guide/en/beats/metricbeat/current/configuration-metricbeat.html) and [{{kib}} module](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-module-kibana.html). + +6. Configure the {{kib}} {xpack} module in {{metricbeat}}.
+ + The `modules.d/kibana-xpack.yml` file contains the following settings: + + ```yaml + - module: kibana + metricsets: + - stats + period: 10s + hosts: ["localhost:5601"] + #basepath: "" + #username: "user" + #password: "secret" + xpack.enabled: true + ``` + + By default, the module collects {{kib}} monitoring metrics from `localhost:5601`. If that host and port number are not correct, you must update the `hosts` setting. If you configured {{kib}} to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://localhost:5601`. + + If the Elastic {{security-features}} are enabled, you must also provide a user ID and password so that {{metricbeat}} can collect metrics successfully: + + 1. Create a user on the production cluster that has the `remote_monitoring_collector` [built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). Alternatively, use the `remote_monitoring_user` [built-in user](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + 2. Add the `username` and `password` settings to the {{kib}} module configuration file. + +7. Optional: Disable the system module in {{metricbeat}}. + + By default, the [system module](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-module-system.html) is enabled. The information it collects, however, is not shown on the **Monitoring** page in {{kib}}. Unless you want to use that information for other purposes, run the following command: + + ```sh + metricbeat modules disable system + ``` + +8. Identify where to send the monitoring data.
+ + ::::{tip} + In production environments, we strongly recommend using a separate cluster (referred to as the *monitoring cluster*) to store the data. Using a separate monitoring cluster prevents production cluster outages from impacting your ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. + :::: + + + For example, specify the {{es}} output information in the {{metricbeat}} configuration file (`metricbeat.yml`): + + ```yaml + output.elasticsearch: + # Array of hosts to connect to. + hosts: ["http://es-mon-1:9200", "http://es-mon2:9200"] <1> + + # Optional protocol and basic auth credentials. + #protocol: "https" + #username: "elastic" + #password: "changeme" + ``` + + 1. In this example, the data is stored on a monitoring cluster with nodes `es-mon-1` and `es-mon-2`. + + + If you configured the monitoring cluster to use encrypted communications, you must access it via HTTPS. For example, use a `hosts` setting like `https://es-mon-1:9200`. + + ::::{important} + The {{es}} {monitor-features} use ingest pipelines. The cluster that stores the monitoring data must have at least one node with the `ingest` role. + :::: + + + If the {{es}} {security-features} are enabled on the monitoring cluster, you must provide a valid user ID and password so that {{metricbeat}} can send metrics successfully: + + 1. Create a user on the monitoring cluster that has the `remote_monitoring_agent` [built-in role](../../users-roles/cluster-or-deployment-auth/built-in-roles.md). Alternatively, use the `remote_monitoring_user` [built-in user](../../users-roles/cluster-or-deployment-auth/built-in-users.md). + 2. Add the `username` and `password` settings to the {{es}} output information in the {{metricbeat}} configuration file. + + For more information about these configuration options, see [Configure the {{es}} output](https://www.elastic.co/guide/en/beats/metricbeat/current/elasticsearch-output.html). + +9. [Start {{metricbeat}}](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-starting.html). +10. [View the monitoring data in {{kib}}](monitoring-data.md). + diff --git a/deploy-manage/monitor/stack-monitoring/pause-export.md b/deploy-manage/monitor/stack-monitoring/pause-export.md new file mode 100644 index 000000000..29c140aaa --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/pause-export.md @@ -0,0 +1,43 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/pause-export.html +--- + +# Pausing data collection [pause-export] + +To stop generating {{monitoring}} data in {{es}}, disable data collection: + +```yaml +xpack.monitoring.collection.enabled: false +``` + +When this setting is `false`, {{es}} monitoring data is not collected and all monitoring data from other sources such as {{kib}}, Beats, and Logstash is ignored. + +You can update this setting by using the [Cluster Update Settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). + +If you want to collect data from sources such as {{kib}}, Beats, and Logstash but not collect data about your {{es}} cluster, you can disable data collection just for {{es}}: + +```yaml +xpack.monitoring.collection.enabled: true +xpack.monitoring.elasticsearch.collection.enabled: false +``` + +If you want to separately disable a specific exporter, you can specify the `enabled` setting (which defaults to `true`) per exporter. For example: + +```yaml +xpack.monitoring.exporters.my_http_exporter: + type: http + host: ["10.1.2.3:9200", "10.1.2.4:9200"] + enabled: false <1> +``` + +1. Disable the named exporter. If the same name as an existing exporter is not used, then this will create a completely new exporter that is completely ignored. This value can be set dynamically by using cluster settings. + + +::::{note} +Defining a disabled exporter prevents the default exporter from being created. +:::: + + +To re-start data collection, re-enable these settings. + diff --git a/deploy-manage/monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md b/deploy-manage/monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md new file mode 100644 index 000000000..c383459fc --- /dev/null +++ b/deploy-manage/monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md @@ -0,0 +1,57 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-monitoring.html + - https://www.elastic.co/guide/en/cloud/current/ec-monitoring-setup.html + - https://www.elastic.co/guide/en/cloud/current/ec-enable-logging-and-monitoring.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-enable-logging-and-monitoring.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-monitoring-setup.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-restrictions-monitoring.html +--- + +# Stack Monitoring on Elastic Cloud deployments + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/350 + +% Scope notes: deal with ech redirect. Refine all these docs, part of the info should go to the stack monitoring intro doc. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-monitoring.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-monitoring-setup.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/cloud/cloud/ec-enable-logging-and-monitoring.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-enable-logging-and-monitoring.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-monitoring-setup.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-restrictions-monitoring.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-check-logs$$$ + +$$$ec-restrictions-monitoring$$$ + +$$$ec-enable-logging-and-monitoring-steps$$$ + +$$$ec-logging-and-monitoring-production$$$ + +$$$ec-logging-and-monitoring-retention$$$ + +$$$ech-enable-logging-and-monitoring-steps$$$ + +$$$ech-es-cluster-health$$$ + +$$$ech-es-cluster-performance$$$ + +$$$ech-es-health-dedicated$$$ + +$$$ech-es-health-preconfigured$$$ + +$$$ech-es-health-warnings$$$ + +$$$ech-health-best-practices$$$ + +$$$ech-logging-and-monitoring-production$$$ + +$$$ech-logging-and-monitoring-retention$$$ \ No newline at end of file diff --git a/deploy-manage/production-guidance.md b/deploy-manage/production-guidance.md new file mode 100644 index 000000000..924050a76 --- /dev/null +++ b/deploy-manage/production-guidance.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-best-practices-data.html +--- + +# Production guidance [ec-best-practices-data] + +This section provides some best practices for managing your data to help you set up a production environment that matches your workloads, policies, and deployment needs. + + +## Plan your data structure, availability, and formatting [ec_plan_your_data_structure_availability_and_formatting] + +* Build a [data architecture](https://www.elastic.co/guide/en/elasticsearch/reference/current/data-tiers.md) that best fits your needs. Your Elasticsearch Service deployment comes with default hot tier {{es}} nodes that store your most frequently accessed data. Based on your own access and retention policies, you can add warm, cold, frozen data tiers, and automated deletion of old data. +* Make your data [highly available](https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability.md) for production environments or otherwise critical data stores, and take regular [backup snapshots](tools/snapshot-and-restore.md). +* Normalize event data to better analyze, visualize, and correlate your events by adopting the [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/{{ecs_version}}/ecs-getting-started.md) (ECS). Elastic integrations use ECS out-of-the-box. If you are writing your own integrations, ECS is recommended. + + +## Optimize data storage and retention [ec_optimize_data_storage_and_retention] + +Once you have your data tiers deployed and you have data flowing, you can [manage the index lifecycle](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.md). + +::::{tip} +[Elastic integrations](https://www.elastic.co/integrations) provide default index lifecycle policies, and you can [build your own policies for your custom integrations](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started-index-lifecycle-management.md). +:::: + + diff --git a/deploy-manage/production-guidance/availability-and-resilience.md b/deploy-manage/production-guidance/availability-and-resilience.md new file mode 100644 index 000000000..b4ce8f1bf --- /dev/null +++ b/deploy-manage/production-guidance/availability-and-resilience.md @@ -0,0 +1,36 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability-cluster-design.html +--- + +# Availability and resilience [high-availability-cluster-design] + +Distributed systems like {{es}} are designed to keep working even if some of their components have failed. As long as there are enough well-connected nodes to take over their responsibilities, an {{es}} cluster can continue operating normally if some of its nodes are unavailable or disconnected. + +There is a limit to how small a resilient cluster can be. All {{es}} clusters require the following components to function: + +* One [elected master node](../distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md) +* At least one node for each [role](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html) +* At least one copy of every [shard](../../deploy-manage/index.md) + +A resilient cluster requires redundancy for every required cluster component. This means a resilient cluster must have the following components: + +* At least three master-eligible nodes +* At least two nodes of each role +* At least two copies of each shard (one primary and one or more replicas, unless the index is a [searchable snapshot index](../tools/snapshot-and-restore/searchable-snapshots.md)) + +A resilient cluster needs three master-eligible nodes so that if one of them fails then the remaining two still form a majority and can hold a successful election. + +Similarly, redundancy of nodes of each role means that if a node for a particular role fails, another node can take on its responsibilities. + +Finally, a resilient cluster should have at least two copies of each shard. If one copy fails then there should be another good copy to take over. {{es}} automatically rebuilds any failed shard copies on the remaining nodes in order to restore the cluster to full health after a failure. + +Failures temporarily reduce the total capacity of your cluster. In addition, after a failure the cluster must perform additional background activities to restore itself to health. You should make sure that your cluster has the capacity to handle your workload even if some nodes fail. + +Depending on your needs and budget, an {{es}} cluster can consist of a single node, hundreds of nodes, or any number in between. When designing a smaller cluster, you should typically focus on making it resilient to single-node failures. Designers of larger clusters must also consider cases where multiple nodes fail at the same time. The following pages give some recommendations for building resilient clusters of various sizes: + +* [Resilience in small clusters](availability-and-resilience/resilience-in-small-clusters.md) +* [Resilience in larger clusters](availability-and-resilience/resilience-in-larger-clusters.md) + + + diff --git a/deploy-manage/production-guidance/availability-and-resilience/resilience-in-larger-clusters.md b/deploy-manage/production-guidance/availability-and-resilience/resilience-in-larger-clusters.md new file mode 100644 index 000000000..d11c8db75 --- /dev/null +++ b/deploy-manage/production-guidance/availability-and-resilience/resilience-in-larger-clusters.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability-cluster-design-large-clusters.html +--- + +# Resilience in larger clusters [high-availability-cluster-design-large-clusters] + +It’s not unusual for nodes to share common infrastructure, such as network interconnects or a power supply. If so, you should plan for the failure of this infrastructure and ensure that such a failure would not affect too many of your nodes. It is common practice to group all the nodes sharing some infrastructure into *zones* and to plan for the failure of any whole zone at once. + +{{es}} expects node-to-node connections to be reliable, have low latency, and have adequate bandwidth. Many {{es}} tasks require multiple round-trips between nodes. A slow or unreliable interconnect may have a significant effect on the performance and stability of your cluster. + +For example, a few milliseconds of latency added to each round-trip can quickly accumulate into a noticeable performance penalty. An unreliable network may have frequent network partitions. {{es}} will automatically recover from a network partition as quickly as it can but your cluster may be partly unavailable during a partition and will need to spend time and resources to [resynchronize any missing data](../../distributed-architecture/shard-allocation-relocation-recovery.md#shard-recovery) and [rebalance](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#shards-rebalancing-settings) itself once the partition heals. Recovering from a failure may involve copying a large amount of data between nodes so the recovery time is often determined by the available bandwidth. + +If you’ve divided your cluster into zones, the network connections within each zone are typically of higher quality than the connections between the zones. Ensure the network connections between zones are of sufficiently high quality. You will see the best results by locating all your zones within a single data center with each zone having its own independent power supply and other supporting infrastructure. You can also *stretch* your cluster across nearby data centers as long as the network interconnection between each pair of data centers is good enough. + +$$$high-availability-cluster-design-min-network-perf$$$ +There is no specific minimum network performance required to run a healthy {{es}} cluster. In theory, a cluster will work correctly even if the round-trip latency between nodes is several hundred milliseconds. In practice, if your network is that slow then the cluster performance will be very poor. In addition, slow networks are often unreliable enough to cause network partitions that lead to periods of unavailability. + +If you want your data to be available in multiple data centers that are further apart or not well connected, deploy a separate cluster in each data center and use [{{ccs}}](../../../solutions/search/cross-cluster-search.md) or [{{ccr}}](../../tools/cross-cluster-replication.md) to link the clusters together. These features are designed to perform well even if the cluster-to-cluster connections are less reliable or performant than the network within each cluster. + +After losing a whole zone’s worth of nodes, a properly-designed cluster may be functional but running with significantly reduced capacity. You may need to provision extra nodes to restore acceptable performance in your cluster when handling such a failure. + +For resilience against whole-zone failures, it is important that there is a copy of each shard in more than one zone, which can be achieved by placing data nodes in multiple zones and configuring [shard allocation awareness](../../distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md). You should also ensure that client requests are sent to nodes in more than one zone. + +You should consider all node roles and ensure that each role is split redundantly across two or more zones. For instance, if you are using [ingest pipelines](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md) or {{ml}}, you should have ingest or {{ml}} nodes in two or more zones. However, the placement of master-eligible nodes requires a little more care because a resilient cluster needs at least two of the three master-eligible nodes in order to function. The following sections explore the options for placing master-eligible nodes across multiple zones. + +## Two-zone clusters [high-availability-cluster-design-two-zones] + +If you have two zones, you should have a different number of master-eligible nodes in each zone so that the zone with more nodes will contain a majority of them and will be able to survive the loss of the other zone. For instance, if you have three master-eligible nodes then you may put all of them in one zone or you may put two in one zone and the third in the other zone. You should not place an equal number of master-eligible nodes in each zone. If you place the same number of master-eligible nodes in each zone, neither zone has a majority of its own. Therefore, the cluster may not survive the loss of either zone. + + +## Two-zone clusters with a tiebreaker [high-availability-cluster-design-two-zones-plus] + +The two-zone deployment described above is tolerant to the loss of one of its zones but not to the loss of the other one because master elections are majority-based. You cannot configure a two-zone cluster so that it can tolerate the loss of *either* zone because this is theoretically impossible. You might expect that if either zone fails then {{es}} can elect a node from the remaining zone as the master but it is impossible to tell the difference between the failure of a remote zone and a mere loss of connectivity between the zones. If both zones were capable of running independent elections then a loss of connectivity would lead to a [split-brain problem](https://en.wikipedia.org/wiki/Split-brain_(computing)) and therefore data loss. {{es}} avoids this and protects your data by not electing a node from either zone as master until that node can be sure that it has the latest cluster state and that there is no other master in the cluster. This may mean there is no master at all until connectivity is restored. + +You can solve this by placing one master-eligible node in each of your two zones and adding a single extra master-eligible node in an independent third zone. The extra master-eligible node acts as a tiebreaker in cases where the two original zones are disconnected from each other. The extra tiebreaker node should be a [dedicated voting-only master-eligible node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#voting-only-node), also known as a dedicated tiebreaker. A dedicated tiebreaker need not be as powerful as the other two nodes since it has no other roles and will not perform any searches nor coordinate any client requests nor be elected as the master of the cluster. + +You should use [shard allocation awareness](../../distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md) to ensure that there is a copy of each shard in each zone. This means either zone remains fully available if the other zone fails. + +All master-eligible nodes, including voting-only nodes, are on the critical path for [publishing cluster state updates](../../distributed-architecture/discovery-cluster-formation/cluster-state-overview.md#cluster-state-publishing). Cluster state updates are usually independent of performance-critical workloads such as indexing or searches, but they are involved in management activities such as index creation and rollover, mapping updates, and recovery after a failure. The performance characteristics of these activities are a function of the speed of the storage on each master-eligible node, as well as the reliability and latency of the network interconnections between all nodes in the cluster. You must therefore ensure that the storage and networking available to the nodes in your cluster are good enough to meet your performance goals. + + +## Clusters with three or more zones [high-availability-cluster-design-three-zones] + +If you have three zones then you should have one master-eligible node in each zone. If you have more than three zones then you should choose three of the zones and put a master-eligible node in each of these three zones. This will mean that the cluster can still elect a master even if one of the zones fails. + +As always, your indices should have at least one replica in case a node fails, unless they are [searchable snapshot indices](../../tools/snapshot-and-restore/searchable-snapshots.md). You should also use [shard allocation awareness](../../distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md) to limit the number of copies of each shard in each zone. For instance, if you have an index with one or two replicas configured then allocation awareness will ensure that the replicas of the shard are in a different zone from the primary. This means that a copy of every shard will still be available if one zone fails. The availability of this shard will not be affected by such a failure. + + +## Summary [high-availability-cluster-design-large-cluster-summary] + +The cluster will be resilient to the loss of any zone as long as: + +* The [cluster health status](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html) is `green`. +* There are at least two zones containing data nodes. +* Every index that is not a [searchable snapshot index](../../tools/snapshot-and-restore/searchable-snapshots.md) has at least one replica of each shard, in addition to the primary. +* [Shard allocation awareness](../../distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md) is configured to avoid concentrating all copies of a shard within a single zone. +* The cluster has at least three master-eligible nodes. At least two of these nodes are not [voting-only master-eligible nodes](../../distributed-architecture/clusters-nodes-shards/node-roles.md#voting-only-node), and they are spread evenly across at least three zones. +* Clients are configured to send their requests to nodes in more than one zone or are configured to use a load balancer that balances the requests across an appropriate set of nodes. The [Elastic Cloud](https://cloud.elastic.co/registration?page=docs&placement=docs-body) service provides such a load balancer. + + diff --git a/deploy-manage/production-guidance/availability-and-resilience/resilience-in-small-clusters.md b/deploy-manage/production-guidance/availability-and-resilience/resilience-in-small-clusters.md new file mode 100644 index 000000000..3533c35d5 --- /dev/null +++ b/deploy-manage/production-guidance/availability-and-resilience/resilience-in-small-clusters.md @@ -0,0 +1,75 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability-cluster-small-clusters.html +--- + +# Resilience in small clusters [high-availability-cluster-small-clusters] + +In smaller clusters, it is most important to be resilient to single-node failures. This section gives some guidance on making your cluster as resilient as possible to the failure of an individual node. + +## One-node clusters [high-availability-cluster-design-one-node] + +If your cluster consists of one node, that single node must do everything. To accommodate this, {{es}} assigns nodes every role by default. + +A single node cluster is not resilient. If the node fails, the cluster will stop working. Because there are no replicas in a one-node cluster, you cannot store your data redundantly. However, by default at least one replica is required for a [`green` cluster health status](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html). To ensure your cluster can report a `green` status, override the default by setting [`index.number_of_replicas`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#dynamic-index-settings) to `0` on every index. + +If the node fails, you may need to restore an older copy of any lost indices from a [snapshot](../../tools/snapshot-and-restore.md). + +Because they are not resilient to any failures, we do not recommend using one-node clusters in production. + + +## Two-node clusters [high-availability-cluster-design-two-nodes] + +If you have two nodes, we recommend they both be data nodes. You should also ensure every shard is stored redundantly on both nodes by setting [`index.number_of_replicas`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#dynamic-index-settings) to `1` on every index that is not a [searchable snapshot index](../../tools/snapshot-and-restore/searchable-snapshots.md). This is the default behaviour but may be overridden by an [index template](../../../manage-data/data-store/templates.md). [Auto-expand replicas](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#dynamic-index-settings) can also achieve the same thing, but it’s not necessary to use this feature in such a small cluster. + +We recommend you set only one of your two nodes to be [master-eligible](../../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role). This means you can be certain which of your nodes is the elected master of the cluster. The cluster can tolerate the loss of the other master-ineligible node. If you set both nodes to master-eligible, two nodes are required for a master election. Since the election will fail if either node is unavailable, your cluster cannot reliably tolerate the loss of either node. + +By default, each node is assigned every role. We recommend you assign both nodes all other roles except master eligibility. If one node fails, the other node can handle its tasks. + +You should avoid sending client requests to just one of your nodes. If you do and this node fails, such requests will not receive responses even if the remaining node is a healthy cluster on its own. Ideally, you should balance your client requests across both nodes. A good way to do this is to specify the addresses of both nodes when configuring the client to connect to your cluster. Alternatively, you can use a resilient load balancer to balance client requests across the nodes in your cluster. + +Because it’s not resilient to failures, we do not recommend deploying a two-node cluster in production. + + +## Two-node clusters with a tiebreaker [high-availability-cluster-design-two-nodes-plus] + +Because master elections are majority-based, the two-node cluster described above is tolerant to the loss of one of its nodes but not the other one. You cannot configure a two-node cluster so that it can tolerate the loss of *either* node because this is theoretically impossible. You might expect that if either node fails then {{es}} can elect the remaining node as the master, but it is impossible to tell the difference between the failure of a remote node and a mere loss of connectivity between the nodes. If both nodes were capable of running independent elections, a loss of connectivity would lead to a [split-brain problem](https://en.wikipedia.org/wiki/Split-brain_(computing)) and therefore data loss. {{es}} avoids this and protects your data by electing neither node as master until that node can be sure that it has the latest cluster state and that there is no other master in the cluster. This could result in the cluster having no master until connectivity is restored. + +You can solve this problem by adding a third node and making all three nodes master-eligible. A [master election](../../distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md) requires only two of the three master-eligible nodes. This means the cluster can tolerate the loss of any single node. This third node acts as a tiebreaker in cases where the two original nodes are disconnected from each other. You can reduce the resource requirements of this extra node by making it a [dedicated voting-only master-eligible node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#voting-only-node), also known as a dedicated tiebreaker. Because it has no other roles, a dedicated tiebreaker does not need to be as powerful as the other two nodes. It will not perform any searches nor coordinate any client requests and cannot be elected as the master of the cluster. + +The two original nodes should not be voting-only master-eligible nodes since a resilient cluster requires at least three master-eligible nodes, at least two of which are not voting-only master-eligible nodes. If two of your three nodes are voting-only master-eligible nodes then the elected master must be the third node. This node then becomes a single point of failure. + +We recommend assigning both non-tiebreaker nodes all other roles. This creates redundancy by ensuring any task in the cluster can be handled by either node. + +You should not send any client requests to the dedicated tiebreaker node. You should also avoid sending client requests to just one of the other two nodes. If you do, and this node fails, then any requests will not receive responses, even if the remaining nodes form a healthy cluster. Ideally, you should balance your client requests across both of the non-tiebreaker nodes. You can do this by specifying the address of both nodes when configuring your client to connect to your cluster. Alternatively, you can use a resilient load balancer to balance client requests across the appropriate nodes in your cluster. The [Elastic Cloud](https://cloud.elastic.co/registration?page=docs&placement=docs-body) service provides such a load balancer. + +A two-node cluster with an additional tiebreaker node is the smallest possible cluster that is suitable for production deployments. + + +## Three-node clusters [high-availability-cluster-design-three-nodes] + +If you have three nodes, we recommend they all be [data nodes](../../distributed-architecture/clusters-nodes-shards/node-roles.md#data-node-role) and every index that is not a [searchable snapshot index](../../tools/snapshot-and-restore/searchable-snapshots.md) should have at least one replica. Nodes are data nodes by default. You may prefer for some indices to have two replicas so that each node has a copy of each shard in those indices. You should also configure each node to be [master-eligible](../../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role) so that any two of them can hold a master election without needing to communicate with the third node. Nodes are master-eligible by default. This cluster will be resilient to the loss of any single node. + +You should avoid sending client requests to just one of your nodes. If you do, and this node fails, then any requests will not receive responses even if the remaining two nodes form a healthy cluster. Ideally, you should balance your client requests across all three nodes. You can do this by specifying the address of multiple nodes when configuring your client to connect to your cluster. Alternatively you can use a resilient load balancer to balance client requests across your cluster. The [Elastic Cloud](https://cloud.elastic.co/registration?page=docs&placement=docs-body) service provides such a load balancer. + + +## Clusters with more than three nodes [high-availability-cluster-design-three-plus-nodes] + +Once your cluster grows to more than three nodes, you can start to specialise these nodes according to their responsibilities, allowing you to scale their resources independently as needed. You can have as many [data nodes](../../distributed-architecture/clusters-nodes-shards/node-roles.md#data-node-role), [ingest nodes](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md), [{{ml}} nodes](../../distributed-architecture/clusters-nodes-shards/node-roles.md#ml-node-role), etc. as needed to support your workload. As your cluster grows larger, we recommend using dedicated nodes for each role. This allows you to independently scale resources for each task. + +However, it is good practice to limit the number of master-eligible nodes in the cluster to three. Master nodes do not scale like other node types since the cluster always elects just one of them as the master of the cluster. If there are too many master-eligible nodes then master elections may take a longer time to complete. In larger clusters, we recommend you configure some of your nodes as dedicated master-eligible nodes and avoid sending any client requests to these dedicated nodes. Your cluster may become unstable if the master-eligible nodes are overwhelmed with unnecessary extra work that could be handled by one of the other nodes. + +You may configure one of your master-eligible nodes to be a [voting-only node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#voting-only-node) so that it can never be elected as the master node. For instance, you may have two dedicated master nodes and a third node that is both a data node and a voting-only master-eligible node. This third voting-only node will act as a tiebreaker in master elections but will never become the master itself. + + +## Summary [high-availability-cluster-design-small-cluster-summary] + +The cluster will be resilient to the loss of any node as long as: + +* The [cluster health status](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html) is `green`. +* There are at least two data nodes. +* Every index that is not a [searchable snapshot index](../../tools/snapshot-and-restore/searchable-snapshots.md) has at least one replica of each shard, in addition to the primary. +* The cluster has at least three master-eligible nodes, as long as at least two of these nodes are not voting-only master-eligible nodes. +* Clients are configured to send their requests to more than one node or are configured to use a load balancer that balances the requests across an appropriate set of nodes. The [Elastic Cloud](https://cloud.elastic.co/registration?page=docs&placement=docs-body) service provides such a load balancer. + + diff --git a/deploy-manage/production-guidance/general-recommendations.md b/deploy-manage/production-guidance/general-recommendations.md new file mode 100644 index 000000000..c29f420e5 --- /dev/null +++ b/deploy-manage/production-guidance/general-recommendations.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/general-recommendations.html +--- + +# General recommendations [general-recommendations] + + +## Don’t return large result sets [large-size] + +Elasticsearch is designed as a search engine, which makes it very good at getting back the top documents that match a query. However, it is not as good for workloads that fall into the database domain, such as retrieving all documents that match a particular query. If you need to do this, make sure to use the [Scroll](https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results) API. + + +## Avoid large documents [maximum-document-size] + +Given that the default [`http.max_content_length`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#http-settings) is set to 100MB, Elasticsearch will refuse to index any document that is larger than that. You might decide to increase that particular setting, but Lucene still has a limit of about 2GB. + +Even without considering hard limits, large documents are usually not practical. Large documents put more stress on network, memory usage and disk, even for search requests that do not request the `_source` since Elasticsearch needs to fetch the `_id` of the document in all cases, and the cost of getting this field is bigger for large documents due to how the filesystem cache works. Indexing this document can use an amount of memory that is a multiplier of the original size of the document. Proximity search (phrase queries for instance) and [highlighting](https://www.elastic.co/guide/en/elasticsearch/reference/current/highlighting.html) also become more expensive since their cost directly depends on the size of the original document. + +It is sometimes useful to reconsider what the unit of information should be. For instance, the fact you want to make books searchable doesn’t necessarily mean that a document should consist of a whole book. It might be a better idea to use chapters or even paragraphs as documents, and then have a property in these documents that identifies which book they belong to. This does not only avoid the issues with large documents, it also makes the search experience better. For instance if a user searches for two words `foo` and `bar`, a match across different chapters is probably very poor, while a match within the same paragraph is likely good. + diff --git a/deploy-manage/production-guidance/getting-ready-for-production-elasticsearch.md b/deploy-manage/production-guidance/getting-ready-for-production-elasticsearch.md new file mode 100644 index 000000000..d76a4d103 --- /dev/null +++ b/deploy-manage/production-guidance/getting-ready-for-production-elasticsearch.md @@ -0,0 +1,69 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html +--- + +# Getting ready for production (Elasticsearch) [scalability] + +Many teams rely on {{es}} to run their key services. To keep these services running, you can design your {{es}} deployment to keep {{es}} available, even in case of large-scale outages. To keep it running fast, you also can design your deployment to be responsive to production workloads. + +{{es}} is built to be always available and to scale with your needs. It does this using a distributed architecture. By distributing your cluster, you can keep Elastic online and responsive to requests. + +In case of failure, {{es}} offers tools for cross-cluster replication and cluster snapshots that can help you fall back or recover quickly. You can also use cross-cluster replication to serve requests based on the geographic location of your users and your resources. + +{{es}} also offers security and monitoring tools to help you keep your cluster highly available. + + +## Use multiple nodes and shards [use-multiple-nodes-shards] + +When you move to production, you need to introduce multiple nodes and shards to your cluster. Nodes and shards are what make {{es}} distributed and scalable. The size and number of these nodes and shards depends on your data, your use case, and your budget. + +These concepts aren’t essential if you’re just getting started. How you [deploy {{es}}](../../get-started/deployment-options.md) in production determines what you need to know: + +* **Self-managed {{es}}**: You are responsible for setting up and managing nodes, clusters, shards, and replicas. This includes managing the underlying infrastructure, scaling, and ensuring high availability through failover and backup strategies. +* **Elastic Cloud**: Elastic can autoscale resources in response to workload changes. Choose from different deployment types to apply sensible defaults for your use case. A basic understanding of nodes, shards, and replicas is still important. +* **Elastic Cloud Serverless**: You don’t need to worry about nodes, shards, or replicas. These resources are 100% automated on the serverless platform, which is designed to scale with your workload. + +Learn more about [nodes and shards](../distributed-architecture/clusters-nodes-shards.md). + + +## CCR for disaster recovery and geo-proximity [ccr-disaster-recovery-geo-proximity] + +To effectively distribute read and write operations across nodes, the nodes in a cluster need good, reliable connections to each other. To provide better connections, you typically co-locate the nodes in the same data center or nearby data centers. + +Co-locating nodes in a single location exposes you to the risk of a single outage taking your entire cluster offline. To maintain high availability, you can prepare a second cluster that can take over in case of disaster by implementing cross-cluster replication (CCR). + +CCR provides a way to automatically synchronize indices from your primary cluster to a secondary remote cluster that can serve as a hot backup. If the primary cluster fails, the secondary cluster can take over. + +You can also use CCR to create secondary clusters to serve read requests in geo-proximity to your users. + +Learn more about [cross-cluster replication](../tools/cross-cluster-replication.md) and about [designing for resilience](availability-and-resilience.md). + +::::{tip} +You can also take [snapshots](../tools/snapshot-and-restore.md) of your cluster that can be restored in case of failure. + +:::: + + + +## Security and monitoring [security-and-monitoring] + +As with any enterprise system, you need tools to secure, manage, and monitor your {{es}} clusters. Security, monitoring, and administrative features that are integrated into {{es}} enable you to use [Kibana](../../get-started/the-stack.md) as a control center for managing a cluster. + +[Learn about securing an {{es}} cluster](../security.md). + +[Learn about monitoring your cluster](../monitor.md). + + +## Cluster design [cluster-design] + +{{es}} offers many options that allow you to configure your cluster to meet your organization’s goals, requirements, and restrictions. You can review the following guides to learn how to tune your cluster to meet your needs: + +* [Designing for resilience](availability-and-resilience.md) +* [Tune for indexing speed](optimize-performance/indexing-speed.md) +* [Tune for search speed](optimize-performance/search-speed.md) +* [Tune for disk usage](optimize-performance/disk-usage.md) +* [Tune for time series data](../../manage-data/use-case-use-elasticsearch-to-manage-time-series-data.md) + +Many {{es}} options come with different performance considerations and trade-offs. The best way to determine the optimal configuration for your use case is through [testing with your own data and queries](https://www.elastic.co/elasticon/conf/2016/sf/quantitative-cluster-sizing). + diff --git a/deploy-manage/production-guidance/kibana-alerting-production-considerations.md b/deploy-manage/production-guidance/kibana-alerting-production-considerations.md new file mode 100644 index 000000000..b10ef4d33 --- /dev/null +++ b/deploy-manage/production-guidance/kibana-alerting-production-considerations.md @@ -0,0 +1,108 @@ +--- +navigation_title: "Alerting" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/alerting-production-considerations.html +--- + + + +# Kibana alerting production considerations [alerting-production-considerations] + + +Alerting runs both rule checks and actions as persistent background tasks managed by the Task Manager. + +When relying on rules and actions as mission critical services, make sure you follow the [production considerations](../distributed-architecture/kibana-tasks-management.md) for Task Manager. + + +## Running background rule checks and actions [alerting-background-tasks] + +{{kib}} uses background tasks to run rules and actions, distributed across all {{kib}} instances in the cluster. + +By default, each {{kib}} instance polls for work at three second intervals, and can run a maximum of ten concurrent tasks. These tasks are then run on the {{kib}} server. + +Rules are recurring background tasks which are rescheduled according to the check interval on completion. Actions are non-recurring background tasks which are deleted on completion. + +For more details on Task Manager, see [Running background tasks](../distributed-architecture/kibana-tasks-management.md#task-manager-background-tasks). + +::::{important} +Rule and action tasks can run late or at an inconsistent schedule. This is typically a symptom of the specific usage of the cluster in question. + +You can address such issues by tweaking the [Task Manager settings](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) or scaling the deployment to better suit your use case. + +For detailed guidance, see [Alerting Troubleshooting](../../explore-analyze/alerts/kibana/alerting-troubleshooting.md). + +:::: + + + +## Scaling guidance [alerting-scaling-guidance] + +As rules and actions leverage background tasks to perform the majority of work, scaling Alerting is possible by following the [Task Manager Scaling Guidance](../distributed-architecture/kibana-tasks-management.md#task-manager-scaling-guidance). + +When estimating the required task throughput, keep the following in mind: + +* Each rule uses a single recurring task that is scheduled to run at the cadence defined by its check interval. +* Each action uses a single task. However, because actions are taken per instance, alerts can generate a large number of non-recurring tasks. + +It is difficult to predict how much throughput is needed to ensure all rules and actions are executed at consistent schedules. By counting rules as recurring tasks and actions as non-recurring tasks, a rough throughput [can be estimated](../distributed-architecture/kibana-tasks-management.md#task-manager-rough-throughput-estimation) as a *tasks per minute* measurement. + +Predicting the buffer required to account for actions depends heavily on the rule types you use, the amount of alerts they might detect, and the number of actions you might choose to assign to action groups. With that in mind, regularly [monitor the health](../monitor/kibana-task-manager-health-monitoring.md) of your Task Manager instances. + + +## Event log index lifecycle management [event-log-ilm] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +Alerts and actions log activity in a set of "event log" data streams, one per Kibana version, named `.kibana-event-log-{{VERSION}}`. These data streams are configured with a lifecycle data retention of 90 days. This can be updated to other values via the standard data stream lifecycle APIs. Note that the event log data contains the data shown in the alerting pages in {{kib}}, so reducing the data retention period will result in less data being available to view. + +For more information on data stream lifecycle management, see: [Data stream lifecycle](../../manage-data/lifecycle/data-stream.md). + + +## Circuit breakers [alerting-circuit-breakers] + +There are several scenarios where running alerting rules and actions can start to negatively impact the overall health of a {{kib}} instance either by clogging up Task Manager throughput or by consuming so much CPU/memory that other operations cannot complete in a reasonable amount of time. There are several [configurable](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#alert-settings) circuit breakers to help minimize these effects. + + +### Rules with very short intervals [_rules_with_very_short_intervals] + +Running large numbers of rules at very short intervals can quickly clog up Task Manager throughput, leading to higher schedule drift. Use `xpack.alerting.rules.minimumScheduleInterval.value` to set a minimum schedule interval for rules. The default (and recommended) value for this configuration is `1m`. Use `xpack.alerting.rules.minimumScheduleInterval.enforce` to specify whether to strictly enforce this minimum. While the default value for this setting is `false` to maintain backwards compatibility with existing rules, set this to `true` to prevent new and updated rules from running at an interval below the minimum. + +Another related setting is `xpack.alerting.rules.maxScheduledPerMinute`, which limits the number of rules that can run per minute. For example if it’s set to `400`, you can have 400 rules with one minute check intervals or 2,000 rules with 5 minute check intervals. You cannot create or edit a rule if its check interval would cause this setting to be exceeded. To stay within this limit, delete or disable some rules or update the check intervals so that your rules run less frequently. + + +### Rules that run for a long time [_rules_that_run_for_a_long_time] + +Rules that run for a long time typically do so because they are issuing resource-intensive {{es}} queries or performing CPU-intensive processing. This can block the event loop, making {{kib}} inaccessible while the rule runs. By default, rule processing is cancelled after `5m` but this can be overriden using the `xpack.alerting.rules.run.timeout` configuration. This value can also be configured per rule type using `xpack.alerting.rules.run.ruleTypeOverrides`. For example, the following configuration sets the global timeout value to `1m` while allowing **Index Threshold** rules to run for `10m` before being cancelled. + +```yaml +xpack.alerting.rules.run: + timeout: '1m' + ruleTypeOverrides: + - id: '.index-threshold' + timeout: '10m' +``` + +When a rule run is cancelled, any alerts and actions that were generated during the run are discarded. This behavior is controlled by the `xpack.alerting.cancelAlertsOnRuleTimeout` configuration, which defaults to `true`. Set this to `false` to receive alerts and actions after the timeout, although be aware that these may be incomplete and possibly inaccurate. + + +### Rules that spawn too many actions [_rules_that_spawn_too_many_actions] + +Rules that spawn too many actions can quickly clog up Task Manager throughput. This can occur if: + +* A rule configured with a single action generates many alerts. For example, if a rule configured to run a single email action generates 100,000 alerts, then 100,000 actions will be scheduled during a run. +* A rule configured with multiple actions generates alerts. For example, if a rule configured to run an email action, a server log action and a webhook action generates 30,000 alerts, then 90,000 actions will be scheduled during a run. + +Use `xpack.alerting.rules.run.actions.max` to limit the maximum number of actions a rule can generate per run. This value can also be configured by connector type using `xpack.alerting.rules.run.actions.connectorTypeOverrides`. For example, the following config sets the global maximum number of actions to 100 while allowing rules with **Email** actions to generate up to 200 actions. + +```yaml +xpack.alerting.rules.run: + actions: + max: 100 + connectorTypeOverrides: + - id: '.email' + max: 200 +``` + diff --git a/deploy-manage/production-guidance/kibana-in-production-environments.md b/deploy-manage/production-guidance/kibana-in-production-environments.md new file mode 100644 index 000000000..db354a5a8 --- /dev/null +++ b/deploy-manage/production-guidance/kibana-in-production-environments.md @@ -0,0 +1,114 @@ +--- +navigation_title: "Production considerations" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/production.html +--- + + + +# Kibana in production environments [production] + + +How you deploy {{kib}} largely depends on your use case. If you are the only user, you can run {{kib}} on your local machine and configure it to point to whatever {{es}} instance you want to interact with. Conversely, if you have a large number of heavy {{kib}} users, you might need to load balance across multiple {{kib}} instances that are all connected to the same {{es}} instance. + +While {{kib}} isn’t terribly resource intensive, we still recommend running {{kib}} separate from your {{es}} data or master nodes. To distribute {{kib}} traffic across the nodes in your {{es}} cluster, you can configure {{kib}} to use a list of {{es}} hosts. + +::::{warning} +{{kib}} does not support rolling upgrades, and deploying mixed versions of {{kib}} can result in data loss or upgrade failures. Please shut down all instances of {{kib}} before performing an upgrade, and ensure all running {{kib}} instances have matching versions. + +:::: + + + +## Load balancing across multiple {{kib}} instances [load-balancing-kibana] + +To serve multiple {{kib}} installations behind a load balancer, you must change the configuration. See [Configuring {{kib}}](../deploy/self-managed/configure.md) for details on each setting. + +These settings must be unique across each {{kib}} instance: + +```js +server.uuid // if not provided, this is autogenerated +server.name +path.data +pid.file +server.port +``` + +When using a file appender, the target file must also be unique: + +```yaml +logging: + appenders: + default: + type: file + fileName: /unique/path/per/instance +``` + +Settings that must be the same: + +```js +xpack.security.encryptionKey //decrypting session information +xpack.security.authc.* // authentication configuration +xpack.security.session.* // session configuration +xpack.reporting.encryptionKey //decrypting reports +xpack.encryptedSavedObjects.encryptionKey // decrypting saved objects +xpack.encryptedSavedObjects.keyRotation.decryptionOnlyKeys // saved objects encryption key rotation, if any +``` + +::::{warning} +If the authentication configuration does not match, sessions from unrecognized providers in each {{kib}} instance will be deleted during that instance’s regular session cleanup. Similarly, inconsistencies in session configuration can also lead to undesired session logouts. This also applies to any {{kib}} instances that are backed by the same {{es}} instance and share the same kibana.index, even if they are not behind the same load balancer. + +:::: + + +Separate configuration files can be used from the command line by using the `-c` flag: + +```js +bin/kibana -c config/instance1.yml +bin/kibana -c config/instance2.yml +``` + + +## Accessing multiple load-balanced {{kib}} clusters [accessing-load-balanced-kibana] + +To access multiple load-balanced {{kib}} clusters from the same browser, explicitly set `xpack.security.cookieName` to the same value in the {{kib}} configuration of each {{kib}} instance. + +Each {{kib}} cluster must have a different value of `xpack.security.cookieName`. + +This avoids conflicts between cookies from the different {{kib}} instances. + +This will achieve seamless high availability and keep the session active in case of failure from the currently used instance. + + +## High availability across multiple {{es}} nodes [high-availability] + +{{kib}} can be configured to connect to multiple {{es}} nodes in the same cluster. In situations where a node becomes unavailable, {{kib}} will transparently connect to an available node and continue operating. Requests to available hosts will be routed in a round robin fashion (except for Dev Tools which will connect only to the first node available). + +In kibana.yml: + +```js +elasticsearch.hosts: + - http://elasticsearch1:9200 + - http://elasticsearch2:9200 +``` + +Related configurations include `elasticsearch.sniffInterval`, `elasticsearch.sniffOnStart`, and `elasticsearch.sniffOnConnectionFault`. These can be used to automatically update the list of hosts as a cluster is resized. Parameters can be found on the [settings page](../deploy/self-managed/configure.md). + + +## Memory [memory] + +Kibana has a default memory limit that scales based on total memory available. In some scenarios, such as large reporting jobs, it may make sense to tweak limits to meet more specific requirements. + +A limit can be defined by setting `--max-old-space-size` in the `node.options` config file found inside the `kibana/config` folder or any other folder configured with the environment variable `KBN_PATH_CONF`. For example, in the Debian-based system, the folder is `/etc/kibana`. + +The option accepts a limit in MB: + +```js +--max-old-space-size=2048 +``` + + +## OpenSSL Legacy Provider [openssl-legacy-provider] + +Starting in 8.10.0, {{kib}} has upgraded its runtime environment, Node.js, from version 16 to version 18 and with it the underlying version of OpenSSL to version 3. Algorithms deemed legacy by OpenSSL 3 have been re-enabled to avoid potential breaking changes in a minor version release of {{kib}}. If SSL certificates configured for {{kib}} are not using any of the legacy algorithms mentioned in the [OpenSSL legacy provider documentation](https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.md), we recommend disabling this setting by removing `--openssl-legacy-provider` in the `node.options` config file. + diff --git a/deploy-manage/production-guidance/kibana-task-manager-scaling-considerations.md b/deploy-manage/production-guidance/kibana-task-manager-scaling-considerations.md new file mode 100644 index 000000000..f933b065b --- /dev/null +++ b/deploy-manage/production-guidance/kibana-task-manager-scaling-considerations.md @@ -0,0 +1,167 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/task-manager-production-considerations.html +--- + +# Kibana task manager scaling considerations [task-manager-production-considerations] + +{{kib}} Task Manager is leveraged by features such as Alerting, Actions, and Reporting to run mission critical work as persistent background tasks. These background tasks distribute work across multiple {{kib}} instances. This has three major benefits: + +* **Persistence**: All task state and scheduling is stored in {{es}}, so if you restart {{kib}}, tasks will pick up where they left off. +* **Scaling**: Multiple {{kib}} instances can read from and update the same task queue in {{es}}, allowing the work load to be distributed across instances. If a {{kib}} instance no longer has capacity to run tasks, you can increase capacity by adding additional {{kib}} instances. +* **Load Balancing**: Task Manager is equipped with a reactive self-healing mechanism, which allows it to reduce the amount of work it executes in reaction to an increased load related error rate in {{es}}. Additionally, when Task Manager experiences an increase in recurring tasks, it attempts to space out the work to better balance the load. + +::::{important} +Task definitions for alerts and actions are stored in the index called `.kibana_task_manager`. + +You must have at least one replica of this index for production deployments. + +If you lose this index, all scheduled alerts and actions are lost. + +:::: + + + +## Running background tasks [task-manager-background-tasks] + +{{kib}} background tasks are managed as follows: + +* An {{es}} task index is polled for overdue tasks at 3-second intervals. You can change this interval using the [`xpack.task_manager.poll_interval`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting. +* Tasks are claimed by updating them in the {{es}} index, using optimistic concurrency control to prevent conflicts. Each {{kib}} instance can run a maximum of 10 concurrent tasks, so a maximum of 10 tasks are claimed each interval. +* Tasks are run on the {{kib}} server. +* Task Manager ensures that tasks: + + * Are only executed once + * Are retried when they fail (if configured to do so) + * Are rescheduled to run again at a future point in time (if configured to do so) + + +::::{important} +It is possible for tasks to run late or at an inconsistent schedule. + +This is usually a symptom of the specific usage or scaling strategy of the cluster in question. + +To address these issues, tweak the {{kib}} Task Manager settings or the cluster scaling strategy to better suit the unique use case. + +For details on the settings that can influence the performance and throughput of Task Manager, see [Task Manager Settings](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html). + +For detailed troubleshooting guidance, see [Troubleshooting](../../troubleshoot/kibana/task-manager.md). + +:::: + + + +## Deployment considerations [_deployment_considerations] + +{{es}} and {{kib}} instances use the system clock to determine the current time. To ensure schedules are triggered when expected, synchronize the clocks of all nodes in the cluster using a time service such as [Network Time Protocol](http://www.ntp.org/). + + +## Scaling guidance [task-manager-scaling-guidance] + +How you deploy {{kib}} largely depends on your use case. Predicting the throughout a deployment might require to support Task Management is difficult because features can schedule an unpredictable number of tasks at a variety of scheduled cadences. + +However, there is a relatively straight forward method you can follow to produce a rough estimate based on your expected usage. + + +### Default scale [task-manager-default-scaling] + +By default, {{kib}} polls for tasks at a rate of 10 tasks every 3 seconds. This means that you can expect a single {{kib}} instance to support up to 200 *tasks per minute* (`200/tpm`). + +In practice, a {{kib}} instance will only achieve the upper bound of `200/tpm` if the duration of task execution is below the polling rate of 3 seconds. For the most part, the duration of tasks is below that threshold, but it can vary greatly as {{es}} and {{kib}} usage grow and task complexity increases (such as alerts executing heavy queries across large datasets). + +By [estimating a rough throughput requirement](../distributed-architecture/kibana-tasks-management.md#task-manager-rough-throughput-estimation), you can estimate the number of {{kib}} instances required to reliably execute tasks in a timely manner. An appropriate number of {{kib}} instances can be estimated to match the required scale. + +For details on monitoring the health of {{kib}} Task Manager, follow the guidance in [Health monitoring](../monitor/kibana-task-manager-health-monitoring.md). + + +### Scaling horizontally [task-manager-scaling-horizontally] + +At times, the sustainable approach might be to expand the throughput of your cluster by provisioning additional {{kib}} instances. By default, each additional {{kib}} instance will add an additional 10 tasks that your cluster can run concurrently, but you can also scale each {{kib}} instance vertically, if your diagnosis indicates that they can handle the additional workload. + + +### Scaling vertically [task-manager-scaling-vertically] + +Other times it, might be preferable to increase the throughput of individual {{kib}} instances. + +Tweak the capacity with the [`xpack.task_manager.capacity`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting, which enables each {{kib}} instance to pull a higher number of tasks per interval. This setting can impact the performance of each instance as the workload will be higher. + +Tweak the poll interval with the [`xpack.task_manager.poll_interval`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) setting, which enables each {{kib}} instance to pull scheduled tasks at a higher rate. This setting can impact the performance of the {{es}} cluster as the workload will be higher. + + +### Choosing a scaling strategy [task-manager-choosing-scaling-strategy] + +Each scaling strategy comes with its own considerations, and the appropriate strategy largely depends on your use case. + +Scaling {{kib}} instances vertically causes higher resource usage in each {{kib}} instance, as it will perform more concurrent work. Scaling {{kib}} instances horizontally requires a higher degree of coordination, which can impact overall performance. + +A recommended strategy is to follow these steps: + +1. Produce a [rough throughput estimate](../distributed-architecture/kibana-tasks-management.md#task-manager-rough-throughput-estimation) as a guide to provisioning as many {{kib}} instances as needed. Include any growth in tasks that you predict experiencing in the near future, and a buffer to better address ad-hoc tasks. +2. After provisioning a deployment, assess whether the provisioned {{kib}} instances achieve the required throughput by evaluating the [Health monitoring](../monitor/kibana-task-manager-health-monitoring.md) as described in [Insufficient throughput to handle the scheduled workload](../../troubleshoot/kibana/task-manager.md#task-manager-theory-insufficient-throughput). +3. If the throughput is insufficient, and {{kib}} instances exhibit low resource usage, incrementally scale vertically while [monitoring](../monitor/monitoring-data/kibana-page.md) the impact of these changes. +4. If the throughput is insufficient, and {{kib}} instances are exhibiting high resource usage, incrementally scale horizontally by provisioning new {{kib}} instances and reassess. + +Task Manager, like the rest of the Elastic Stack, is designed to scale horizontally. Take advantage of this ability to ensure mission critical services, such as Alerting, Actions, and Reporting, always have the capacity they need. + +Scaling horizontally requires a higher degree of coordination between {{kib}} instances. One way Task Manager coordinates with other instances is by delaying its polling schedule to avoid conflicts with other instances. By using [health monitoring](../monitor/kibana-task-manager-health-monitoring.md) to evaluate the [date of the `last_polling_delay`](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-runtime) across a deployment, you can estimate the frequency at which Task Manager resets its delay mechanism. A higher frequency suggests {{kib}} instances conflict at a high rate, which you can address by scaling vertically rather than horizontally, reducing the required coordination. + + +### Rough throughput estimation [task-manager-rough-throughput-estimation] + +Predicting the required throughput a deployment might need to support Task Management is difficult, as features can schedule an unpredictable number of tasks at a variety of scheduled cadences. However, a rough lower bound can be estimated, which is then used as a guide. + +Throughput is best thought of as a measurements in tasks per minute. + +A default {{kib}} instance can support up to `200/tpm`. + + +#### Automatic estimation [_automatic_estimation] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +As demonstrated in [Evaluate your capacity estimation](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-capacity-estimation), the Task Manager [health monitoring](../monitor/kibana-task-manager-health-monitoring.md) performs these estimations automatically. + +These estimates are based on historical data and should not be used as predictions, but can be used as a rough guide when scaling the system. + +We recommend provisioning enough {{kib}} instances to ensure a buffer between the observed maximum throughput (as estimated under `observed.max_throughput_per_minute`) and the average required throughput (as estimated under `observed.avg_required_throughput_per_minute`). Otherwise there might be insufficient capacity to handle spikes of ad-hoc tasks. How much of a buffer is needed largely depends on your use case, but keep in mind that estimated throughput takes into account recent spikes and, as long as they are representative of your system’s behaviour, shouldn’t require much of a buffer. + +We recommend provisioning at least as many {{kib}} instances as proposed by `proposed.provisioned_kibana`, but keep in mind that this number is based on the estimated required throughput, which is based on average historical performance, and cannot accurately predict future requirements. + +::::{warning} +Automatic capacity estimation is performed by each {{kib}} instance independently. This estimation is performed by observing the task throughput in that instance, the number of {{kib}} instances executing tasks at that moment in time, and the recurring workload in {{es}}. + +If a {{kib}} instance is idle at the moment of capacity estimation, the number of active {{kib}} instances might be miscounted and the available throughput miscalculated. + +When evaluating the proposed {{kib}} instance number under `proposed.provisioned_kibana`, we highly recommend verifying that the `observed.observed_kibana_instances` matches the number of provisioned {{kib}} instances. + +:::: + + + +#### Manual estimation [_manual_estimation] + +By [evaluating the workload](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-workload), you can make a rough estimate as to the required throughput as a *tasks per minute* measurement. + +For example, suppose your current workload reveals a required throughput of `440/tpm`. You can address this scale by provisioning 3 {{kib}} instances, with an upper throughput of `600/tpm`. This scale would provide approximately 25% additional capacity to handle ad-hoc non-recurring tasks and potential growth in recurring tasks. + +Given a deployment of 100 recurring tasks, estimating the required throughput depends on the scheduled cadence. Suppose you expect to run 50 tasks at a cadence of `10s`, the other 50 tasks at `20m`. In addition, you expect a couple dozen non-recurring tasks every minute. + +A non-recurring task requires a single execution, which means that a single {{kib}} instance could execute all 100 tasks in less than a minute, using only half of its capacity. As these tasks are only executed once, the {{kib}} instance will sit idle once all tasks are executed. For that reason, don’t include non-recurring tasks in your *tasks per minute* calculation. Instead, include a buffer in the final *lower bound* to incur the cost of ad-hoc non-recurring tasks. + +A recurring task requires as many executions as its cadence can fit in a minute. A recurring task with a `10s` schedule will require `6/tpm`, as it will execute 6 times per minute. A recurring task with a `20m` schedule only executes 3 times per hour and only requires a throughput of `0.05/tpm`, a number so small it that is difficult to take it into account. + +For this reason, we recommend grouping tasks by *tasks per minute* and *tasks per hour*, as demonstrated in [Evaluate your workload](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-workload), averaging the *per hour* measurement across all minutes. + +It is highly recommended that you maintain at least 20% additional capacity, beyond your expected workload, as spikes in ad-hoc tasks is possible at times of high activity (such as a spike in actions in response to an active alert). + +Given the predicted workload, you can estimate a lower bound throughput of `340/tpm` (`6/tpm` * 50 + `3/tph` * 50 + 20% buffer). As a default, a {{kib}} instance provides a throughput of `200/tpm`. A good starting point for your deployment is to provision 2 {{kib}} instances. You could then monitor their performance and reassess as the required throughput becomes clearer. + +Although this is a *rough* estimate, the *tasks per minute* provides the lower bound needed to execute tasks on time. + +Once you estimate *tasks per minute* , add a buffer for non-recurring tasks. How much of a buffer is required largely depends on your use case. Ensure enough of a buffer is provisioned by [evaluating your workload](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-workload) as it grows and tracking the ratio of recurring to non-recurring tasks by [evaluating your runtime](../../troubleshoot/kibana/task-manager.md#task-manager-health-evaluate-the-runtime). + + + diff --git a/deploy-manage/production-guidance/optimize-performance.md b/deploy-manage/production-guidance/optimize-performance.md new file mode 100644 index 000000000..ec2e5c1e6 --- /dev/null +++ b/deploy-manage/production-guidance/optimize-performance.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/how-to.html +--- + +# Elasticsearch performance optimizations [how-to] + +Elasticsearch’s default settings provide a good out-of-box experience for basic operations like full text search, highlighting, aggregations, and indexing. + +However, there are a number of optimizations you can make to improve performance for your use case. + +This section provides recommendations for various use cases. + +* [*General recommendations*](general-recommendations.md) +* [*Tune for indexing speed*](optimize-performance/indexing-speed.md) +* [*Tune for search speed*](optimize-performance/search-speed.md) +* [*Tune approximate kNN search*](optimize-performance/approximate-knn-search.md) +* [*Tune for disk usage*](optimize-performance/disk-usage.md) +* [*Size your shards*](optimize-performance/size-shards.md) +* [*Use {{es}} for time series data*](../../manage-data/use-case-use-elasticsearch-to-manage-time-series-data.md) + diff --git a/deploy-manage/production-guidance/optimize-performance/approximate-knn-search.md b/deploy-manage/production-guidance/optimize-performance/approximate-knn-search.md new file mode 100644 index 000000000..6bfe76b8c --- /dev/null +++ b/deploy-manage/production-guidance/optimize-performance/approximate-knn-search.md @@ -0,0 +1,116 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-knn-search.html +--- + +# Approximate kNN search [tune-knn-search] + +{{es}} supports [approximate k-nearest neighbor search](../../../solutions/search/vector/knn.md#approximate-knn) for efficiently finding the *k* nearest vectors to a query vector. Since approximate kNN search works differently from other queries, there are special considerations around its performance. + +Many of these recommendations help improve search speed. With approximate kNN, the indexing algorithm runs searches under the hood to create the vector index structures. So these same recommendations also help with indexing speed. + + +## Reduce vector memory foot-print [_reduce_vector_memory_foot_print] + +The default [`element_type`](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-element-type) is `float`. But this can be automatically quantized during index time through [`quantization`](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-quantization). Quantization will reduce the required memory by 4x, 8x, or as much as 32x, but it will also reduce the precision of the vectors and increase disk usage for the field (by up to 25%, 12.5%, or 3.125%, respectively). Increased disk usage is a result of {{es}} storing both the quantized and the unquantized vectors. For example, when int8 quantizing 40GB of floating point vectors an extra 10GB of data will be stored for the quantized vectors. The total disk usage amounts to 50GB, but the memory usage for fast search will be reduced to 10GB. + +For `float` vectors with `dim` greater than or equal to `384`, using a [`quantized`](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-quantization) index is highly recommended. + + +## Reduce vector dimensionality [_reduce_vector_dimensionality] + +The speed of kNN search scales linearly with the number of vector dimensions, because each similarity computation considers each element in the two vectors. Whenever possible, it’s better to use vectors with a lower dimension. Some embedding models come in different "sizes", with both lower and higher dimensional options available. You could also experiment with dimensionality reduction techniques like PCA. When experimenting with different approaches, it’s important to measure the impact on relevance to ensure the search quality is still acceptable. + + +## Exclude vector fields from `_source` [_exclude_vector_fields_from_source] + +{{es}} stores the original JSON document that was passed at index time in the [`_source` field](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html). By default, each hit in the search results contains the full document `_source`. When the documents contain high-dimensional `dense_vector` fields, the `_source` can be quite large and expensive to load. This could significantly slow down the speed of kNN search. + +::::{note} +[reindex](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html), [update](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update.html), and [update by query](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html) operations generally require the `_source` field. Disabling `_source` for a field might result in unexpected behavior for these operations. For example, reindex might not actually contain the `dense_vector` field in the new index. +:::: + + +You can disable storing `dense_vector` fields in the `_source` through the [`excludes`](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html#include-exclude) mapping parameter. This prevents loading and returning large vectors during search, and also cuts down on the index size. Vectors that have been omitted from `_source` can still be used in kNN search, since it relies on separate data structures to perform the search. Before using the [`excludes`](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html#include-exclude) parameter, make sure to review the downsides of omitting fields from `_source`. + +Another option is to use [synthetic `_source`](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html#synthetic-source). + + +## Ensure data nodes have enough memory [_ensure_data_nodes_have_enough_memory] + +{{es}} uses the [HNSW](https://arxiv.org/abs/1603.09320) algorithm for approximate kNN search. HNSW is a graph-based algorithm which only works efficiently when most vector data is held in memory. You should ensure that data nodes have at least enough RAM to hold the vector data and index structures. To check the size of the vector data, you can use the [Analyze index disk usage](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-disk-usage.html) API. + +Here are estimates for different element types and quantization levels: + +* `element_type: float`: `num_vectors * num_dimensions * 4` +* `element_type: float` with `quantization: int8`: `num_vectors * (num_dimensions + 4)` +* `element_type: float` with `quantization: int4`: `num_vectors * (num_dimensions/2 + 4)` +* `element_type: float` with `quantization: bbq`: `num_vectors * (num_dimensions/8 + 12)` +* `element_type: byte`: `num_vectors * num_dimensions` +* `element_type: bit`: `num_vectors * (num_dimensions/8)` + +If utilizing HNSW, the graph must also be in memory, to estimate the required bytes use `num_vectors * 4 * HNSW.m`. The default value for `HNSW.m` is 16, so by default `num_vectors * 4 * 16`. + +Note that the required RAM is for the filesystem cache, which is separate from the Java heap. + +The data nodes should also leave a buffer for other ways that RAM is needed. For example your index might also include text fields and numerics, which also benefit from using filesystem cache. It’s recommended to run benchmarks with your specific dataset to ensure there’s a sufficient amount of memory to give good search performance. You can find [here](https://elasticsearch-benchmarks.elastic.co/#tracks/so_vector) and [here](https://elasticsearch-benchmarks.elastic.co/#tracks/dense_vector) some examples of datasets and configurations that we use for our nightly benchmarks. + + +## Warm up the filesystem cache [dense-vector-preloading] + +If the machine running Elasticsearch is restarted, the filesystem cache will be empty, so it will take some time before the operating system loads hot regions of the index into memory so that search operations are fast. You can explicitly tell the operating system which files should be loaded into memory eagerly depending on the file extension using the [`index.store.preload`](https://www.elastic.co/guide/en/elasticsearch/reference/current/preload-data-to-file-system-cache.html) setting. + +::::{warning} +Loading data into the filesystem cache eagerly on too many indices or too many files will make search *slower* if the filesystem cache is not large enough to hold all the data. Use with caution. +:::: + + +The following file extensions are used for the approximate kNN search: Each extension is broken down by the quantization types. + +* `vex` for the HNSW graph +* `vec` for all non-quantized vector values. This includes all element types: `float`, `byte`, and `bit`. +* `veq` for quantized vectors indexed with [`quantization`](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-quantization): `int4` or `int8` +* `veb` for binary vectors indexed with [`quantization`](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-quantization): `bbq` +* `vem`, `vemf`, `vemq`, and `vemb` for metadata, usually small and not a concern for preloading + +Generally, if you are using a quantized index, you should only preload the relevant quantized values and the HNSW graph. Preloading the raw vectors is not necessary and might be counterproductive. + + +## Reduce the number of index segments [_reduce_the_number_of_index_segments] + +{{es}} shards are composed of segments, which are internal storage elements in the index. For approximate kNN search, {{es}} stores the vector values of each segment as a separate HNSW graph, so kNN search must check each segment. The recent parallelization of kNN search made it much faster to search across multiple segments, but still kNN search can be up to several times faster if there are fewer segments. By default, {{es}} periodically merges smaller segments into larger ones through a background [merge process](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-merge.html). If this isn’t sufficient, you can take explicit steps to reduce the number of index segments. + + +### Increase maximum segment size [_increase_maximum_segment_size] + +{{es}} provides many tunable settings for controlling the merge process. One important setting is `index.merge.policy.max_merged_segment`. This controls the maximum size of the segments that are created during the merge process. By increasing the value, you can reduce the number of segments in the index. The default value is `5GB`, but that might be too small for larger dimensional vectors. Consider increasing this value to `10GB` or `20GB` can help reduce the number of segments. + + +### Create large segments during bulk indexing [_create_large_segments_during_bulk_indexing] + +A common pattern is to first perform an initial bulk upload, then make an index available for searches. Instead of force merging, you can adjust the index settings to encourage {{es}} to create larger initial segments: + +* Ensure there are no searches during the bulk upload and disable [`index.refresh_interval`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-refresh-interval-setting) by setting it to `-1`. This prevents refresh operations and avoids creating extra segments. +* Give {{es}} a large indexing buffer so it can accept more documents before flushing. By default, the [`indices.memory.index_buffer_size`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indexing-buffer.html) is set to 10% of the heap size. With a substantial heap size like 32GB, this is often enough. To allow the full indexing buffer to be used, you should also increase the limit [`index.translog.flush_threshold_size`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-translog.html). + + +## Avoid heavy indexing during searches [_avoid_heavy_indexing_during_searches] + +Actively indexing documents can have a negative impact on approximate kNN search performance, since indexing threads steal compute resources from search. When indexing and searching at the same time, {{es}} also refreshes frequently, which creates several small segments. This also hurts search performance, since approximate kNN search is slower when there are more segments. + +When possible, it’s best to avoid heavy indexing during approximate kNN search. If you need to reindex all the data, perhaps because the vector embedding model changed, then it’s better to reindex the new documents into a separate index rather than update them in-place. This helps avoid the slowdown mentioned above, and prevents expensive merge operations due to frequent document updates. + + +## Avoid page cache thrashing by using modest readahead values on Linux [_avoid_page_cache_thrashing_by_using_modest_readahead_values_on_linux_2] + +Search can cause a lot of randomized read I/O. When the underlying block device has a high readahead value, there may be a lot of unnecessary read I/O done, especially when files are accessed using memory mapping (see [storage types](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-store.html#file-system)). + +Most Linux distributions use a sensible readahead value of `128KiB` for a single plain device, however, when using software raid, LVM or dm-crypt the resulting block device (backing Elasticsearch [path.data](../../deploy/self-managed/important-settings-configuration.md#path-settings)) may end up having a very large readahead value (in the range of several MiB). This usually results in severe page (filesystem) cache thrashing adversely affecting search (or [update](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html)) performance. + +You can check the current value in `KiB` using `lsblk -o NAME,RA,MOUNTPOINT,TYPE,SIZE`. Consult the documentation of your distribution on how to alter this value (for example with a `udev` rule to persist across reboots, or via [blockdev --setra](https://man7.org/linux/man-pages/man8/blockdev.8.md) as a transient setting). We recommend a value of `128KiB` for readahead. + +::::{warning} +`blockdev` expects values in 512 byte sectors whereas `lsblk` reports values in `KiB`. As an example, to temporarily set readahead to `128KiB` for `/dev/nvme0n1`, specify `blockdev --setra 256 /dev/nvme0n1`. +:::: + + diff --git a/deploy-manage/production-guidance/optimize-performance/disk-usage.md b/deploy-manage/production-guidance/optimize-performance/disk-usage.md new file mode 100644 index 000000000..1c1ac1094 --- /dev/null +++ b/deploy-manage/production-guidance/optimize-performance/disk-usage.md @@ -0,0 +1,110 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-disk-usage.html +--- + +# Disk usage [tune-for-disk-usage] + + +## Disable the features you do not need [_disable_the_features_you_do_not_need] + +By default, {{es}} indexes and adds doc values to most fields so that they can be searched and aggregated out of the box. For instance, if you have a numeric field called `foo` that you need to run histograms on but that you never need to filter on, you can safely disable indexing on this field in your [mappings](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html#mappings): + +```console +PUT index +{ + "mappings": { + "properties": { + "foo": { + "type": "integer", + "index": false + } + } + } +} +``` + +[`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) fields store normalization factors in the index to facilitate document scoring. If you only need matching capabilities on a `text` field but do not care about the produced scores, you can use the [`match_only_text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html#match-only-text-field-type) type instead. This field type saves significant space by dropping scoring and positional information. + + +## Don’t use default dynamic string mappings [default-dynamic-string-mapping] + +The default [dynamic string mappings](../../../manage-data/data-store/mapping/dynamic-mapping.md) will index string fields both as [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) and [`keyword`](https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html). This is wasteful if you only need one of them. Typically an `id` field will only need to be indexed as a `keyword` while a `body` field will only need to be indexed as a `text` field. + +This can be disabled by either configuring explicit mappings on string fields or setting up dynamic templates that will map string fields as either `text` or `keyword`. + +For instance, here is a template that can be used in order to only map string fields as `keyword`: + +```console +PUT index +{ + "mappings": { + "dynamic_templates": [ + { + "strings": { + "match_mapping_type": "string", + "mapping": { + "type": "keyword" + } + } + } + ] + } +} +``` + + +## Watch your shard size [_watch_your_shard_size] + +Larger shards are going to be more efficient at storing data. To increase the size of your shards, you can decrease the number of primary shards in an index by [creating indices](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html) with fewer primary shards, creating fewer indices (e.g. by leveraging the [Rollover API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-rollover-index.html)), or modifying an existing index using the [Shrink API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html). + +Keep in mind that large shard sizes come with drawbacks, such as long full recovery times. + + +## Disable `_source` [disable-source] + +The [`_source`](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html) field stores the original JSON body of the document. If you don’t need access to it you can disable it. However, APIs that needs access to `_source` such as update, highlight and reindex won’t work. + + +## Use `best_compression` [best-compression] + +The `_source` and stored fields can easily take a non negligible amount of disk space. They can be compressed more aggressively by using the `best_compression` [codec](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-codec). + + +## Force merge [_force_merge] + +Indices in Elasticsearch are stored in one or more shards. Each shard is a Lucene index and made up of one or more segments - the actual files on disk. Larger segments are more efficient for storing data. + +The [force merge API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html) can be used to reduce the number of segments per shard. In many cases, the number of segments can be reduced to one per shard by setting `max_num_segments=1`. + +::::{warning} +**We recommend only force merging a read-only index (meaning the index is no longer receiving writes).** When documents are updated or deleted, the old version is not immediately removed, but instead soft-deleted and marked with a "tombstone". These soft-deleted documents are automatically cleaned up during regular segment merges. But force merge can cause very large (> 5GB) segments to be produced, which are not eligible for regular merges. So the number of soft-deleted documents can then grow rapidly, resulting in higher disk usage and worse search performance. If you regularly force merge an index receiving writes, this can also make snapshots more expensive, since the new documents can’t be backed up incrementally. +:::: + + + +## Shrink index [_shrink_index] + +The [shrink API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html) allows you to reduce the number of shards in an index. Together with the force merge API above, this can significantly reduce the number of shards and segments of an index. + + +## Use the smallest numeric type that is sufficient [_use_the_smallest_numeric_type_that_is_sufficient] + +The type that you pick for [numeric data](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html) can have a significant impact on disk usage. In particular, integers should be stored using an integer type (`byte`, `short`, `integer` or `long`) and floating points should either be stored in a `scaled_float` if appropriate or in the smallest type that fits the use-case: using `float` over `double`, or `half_float` over `float` will help save storage. + + +## Use index sorting to colocate similar documents [_use_index_sorting_to_colocate_similar_documents] + +When Elasticsearch stores `_source`, it compresses multiple documents at once in order to improve the overall compression ratio. For instance it is very common that documents share the same field names, and quite common that they share some field values, especially on fields that have a low cardinality or a [zipfian](https://en.wikipedia.org/wiki/Zipf%27s_law) distribution. + +By default documents are compressed together in the order that they are added to the index. If you enabled [index sorting](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-index-sorting.html) then instead they are compressed in sorted order. Sorting documents with similar structure, fields, and values together should improve the compression ratio. + + +## Put fields in the same order in documents [_put_fields_in_the_same_order_in_documents] + +Due to the fact that multiple documents are compressed together into blocks, it is more likely to find longer duplicate strings in those `_source` documents if fields always occur in the same order. + + +## Roll up historical data [roll-up-historical-data] + +Keeping older data can be useful for later analysis but is often avoided due to storage costs. You can use downsampling to summarize and store historical data at a fraction of the raw data’s storage cost. See [Downsampling a time series data stream](../../../manage-data/data-store/index-types/downsampling-time-series-data-stream.md). diff --git a/deploy-manage/production-guidance/optimize-performance/indexing-speed.md b/deploy-manage/production-guidance/optimize-performance/indexing-speed.md new file mode 100644 index 000000000..8a239091b --- /dev/null +++ b/deploy-manage/production-guidance/optimize-performance/indexing-speed.md @@ -0,0 +1,90 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html +--- + +# Indexing speed [tune-for-indexing-speed] + + +## Use bulk requests [_use_bulk_requests] + +Bulk requests will yield much better performance than single-document index requests. In order to know the optimal size of a bulk request, you should run a benchmark on a single node with a single shard. First try to index 100 documents at once, then 200, then 400, etc. doubling the number of documents in a bulk request in every benchmark run. When the indexing speed starts to plateau then you know you reached the optimal size of a bulk request for your data. In case of tie, it is better to err in the direction of too few rather than too many documents. Beware that too large bulk requests might put the cluster under memory pressure when many of them are sent concurrently, so it is advisable to avoid going beyond a couple tens of megabytes per request even if larger requests seem to perform better. + + +## Use multiple workers/threads to send data to Elasticsearch [multiple-workers-threads] + +A single thread sending bulk requests is unlikely to be able to max out the indexing capacity of an Elasticsearch cluster. In order to use all resources of the cluster, you should send data from multiple threads or processes. In addition to making better use of the resources of the cluster, this should help reduce the cost of each fsync. + +Make sure to watch for `TOO_MANY_REQUESTS (429)` response codes (`EsRejectedExecutionException` with the Java client), which is the way that Elasticsearch tells you that it cannot keep up with the current indexing rate. When it happens, you should pause indexing a bit before trying again, ideally with randomized exponential backoff. + +Similarly to sizing bulk requests, only testing can tell what the optimal number of workers is. This can be tested by progressively increasing the number of workers until either I/O or CPU is saturated on the cluster. + + +## Unset or increase the refresh interval [_unset_or_increase_the_refresh_interval] + +The operation that consists of making changes visible to search - called a [refresh](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html) - is costly, and calling it often while there is ongoing indexing activity can hurt indexing speed. + +By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. + +This is the optimal configuration if you have no or very little search traffic (e.g. less than one search request every 5 minutes) and want to optimize for indexing speed. This behavior aims to automatically optimize bulk indexing in the default case when no searches are performed. In order to opt out of this behavior set the refresh interval explicitly. + +On the other hand, if your index experiences regular search requests, this default behavior means that Elasticsearch will refresh your index every 1 second. If you can afford to increase the amount of time between when a document gets indexed and when it becomes visible, increasing the [`index.refresh_interval`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-refresh-interval-setting) to a larger value, e.g. `30s`, might help improve indexing speed. + + +## Disable replicas for initial loads [_disable_replicas_for_initial_loads] + +If you have a large amount of data that you want to load all at once into Elasticsearch, it may be beneficial to set `index.number_of_replicas` to `0` in order to speed up indexing. Having no replicas means that losing a single node may incur data loss, so it is important that the data lives elsewhere so that this initial load can be retried in case of an issue. Once the initial load is finished, you can set `index.number_of_replicas` back to its original value. + +If `index.refresh_interval` is configured in the index settings, it may further help to unset it during this initial load and setting it back to its original value once the initial load is finished. + + +## Disable swapping [_disable_swapping_2] + +You should make sure that the operating system is not swapping out the java process by [disabling swapping](../../deploy/self-managed/setup-configuration-memory.md). + + +## Give memory to the filesystem cache [_give_memory_to_the_filesystem_cache] + +The filesystem cache will be used in order to buffer I/O operations. You should make sure to give at least half the memory of the machine running Elasticsearch to the filesystem cache. + + +## Use auto-generated ids [_use_auto_generated_ids] + +When indexing a document that has an explicit id, Elasticsearch needs to check whether a document with the same id already exists within the same shard, which is a costly operation and gets even more costly as the index grows. By using auto-generated ids, Elasticsearch can skip this check, which makes indexing faster. + + +## Use faster hardware [indexing-use-faster-hardware] + +If indexing is I/O-bound, consider increasing the size of the filesystem cache (see above) or using faster storage. Elasticsearch generally creates individual files with sequential writes. However, indexing involves writing multiple files concurrently, and a mix of random and sequential reads too, so SSD drives tend to perform better than spinning disks. + +Stripe your index across multiple SSDs by configuring a RAID 0 array. Remember that it will increase the risk of failure since the failure of any one SSD destroys the index. However this is typically the right tradeoff to make: optimize single shards for maximum performance, and then add replicas across different nodes so there’s redundancy for any node failures. You can also use [snapshot and restore](../../tools/snapshot-and-restore.md) to backup the index for further insurance. + + +### Local vs. remote storage [_local_vs_remote_storage] + +Directly-attached (local) storage generally performs better than remote storage because it is simpler to configure well and avoids communications overheads. + +Some remote storage performs very poorly, especially under the kind of load that {{es}} imposes. However, with careful tuning, it is sometimes possible to achieve acceptable performance using remote storage too. Before committing to a particular storage architecture, benchmark your system with a realistic workload to determine the effects of any tuning parameters. If you cannot achieve the performance you expect, work with the vendor of your storage system to identify the problem. + + +## Indexing buffer size [_indexing_buffer_size] + +If your node is doing only heavy indexing, be sure [`indices.memory.index_buffer_size`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indexing-buffer.html) is large enough to give at most 512 MB indexing buffer per shard doing heavy indexing (beyond that indexing performance does not typically improve). Elasticsearch takes that setting (a percentage of the java heap or an absolute byte-size), and uses it as a shared buffer across all active shards. Very active shards will naturally use this buffer more than shards that are performing lightweight indexing. + +The default is `10%` which is often plenty: for example, if you give the JVM 10GB of memory, it will give 1GB to the index buffer, which is enough to host two shards that are heavily indexing. + + +## Use {{ccr}} to prevent searching from stealing resources from indexing [_use_ccr_to_prevent_searching_from_stealing_resources_from_indexing] + +Within a single cluster, indexing and searching can compete for resources. By setting up two clusters, configuring [{{ccr}}](../../tools/cross-cluster-replication.md) to replicate data from one cluster to the other one, and routing all searches to the cluster that has the follower indices, search activity will no longer steal resources from indexing on the cluster that hosts the leader indices. + + +## Avoid hot spotting [_avoid_hot_spotting] + +[Hot Spotting](../../../troubleshoot/elasticsearch/hotspotting.md) can occur when node resources, shards, or requests are not evenly distributed. {{es}} maintains cluster state by syncing it across nodes, so continually hot spotted nodes can cause overall cluster performance degredation. + + +## Additional optimizations [_additional_optimizations] + +Many of the strategies outlined in [*Tune for disk usage*](disk-usage.md) also provide an improvement in the speed of indexing. + diff --git a/deploy-manage/production-guidance/optimize-performance/search-speed.md b/deploy-manage/production-guidance/optimize-performance/search-speed.md new file mode 100644 index 000000000..3b6dd172b --- /dev/null +++ b/deploy-manage/production-guidance/optimize-performance/search-speed.md @@ -0,0 +1,428 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-search-speed.html +--- + +# Search speed [tune-for-search-speed] + + +## Give memory to the filesystem cache [_give_memory_to_the_filesystem_cache_2] + +Elasticsearch heavily relies on the filesystem cache in order to make search fast. In general, you should make sure that at least half the available memory goes to the filesystem cache so that Elasticsearch can keep hot regions of the index in physical memory. + + +## Avoid page cache thrashing by using modest readahead values on Linux [_avoid_page_cache_thrashing_by_using_modest_readahead_values_on_linux] + +Search can cause a lot of randomized read I/O. When the underlying block device has a high readahead value, there may be a lot of unnecessary read I/O done, especially when files are accessed using memory mapping (see [storage types](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-store.html#file-system)). + +Most Linux distributions use a sensible readahead value of `128KiB` for a single plain device, however, when using software raid, LVM or dm-crypt the resulting block device (backing Elasticsearch [path.data](../../deploy/self-managed/important-settings-configuration.md#path-settings)) may end up having a very large readahead value (in the range of several MiB). This usually results in severe page (filesystem) cache thrashing adversely affecting search (or [update](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html)) performance. + +You can check the current value in `KiB` using `lsblk -o NAME,RA,MOUNTPOINT,TYPE,SIZE`. Consult the documentation of your distribution on how to alter this value (for example with a `udev` rule to persist across reboots, or via [blockdev --setra](https://man7.org/linux/man-pages/man8/blockdev.8.md) as a transient setting). We recommend a value of `128KiB` for readahead. + +::::{warning} +`blockdev` expects values in 512 byte sectors whereas `lsblk` reports values in `KiB`. As an example, to temporarily set readahead to `128KiB` for `/dev/nvme0n1`, specify `blockdev --setra 256 /dev/nvme0n1`. +:::: + + + +## Use faster hardware [search-use-faster-hardware] + +If your searches are I/O-bound, consider increasing the size of the filesystem cache (see above) or using faster storage. Each search involves a mix of sequential and random reads across multiple files, and there may be many searches running concurrently on each shard, so SSD drives tend to perform better than spinning disks. + +If your searches are CPU-bound, consider using a larger number of faster CPUs. + + +### Local vs. remote storage [_local_vs_remote_storage_2] + +Directly-attached (local) storage generally performs better than remote storage because it is simpler to configure well and avoids communications overheads. + +Some remote storage performs very poorly, especially under the kind of load that {{es}} imposes. However, with careful tuning, it is sometimes possible to achieve acceptable performance using remote storage too. Before committing to a particular storage architecture, benchmark your system with a realistic workload to determine the effects of any tuning parameters. If you cannot achieve the performance you expect, work with the vendor of your storage system to identify the problem. + + +## Document modeling [_document_modeling] + +Documents should be modeled so that search-time operations are as cheap as possible. + +In particular, joins should be avoided. [`nested`](https://www.elastic.co/guide/en/elasticsearch/reference/current/nested.html) can make queries several times slower and [parent-child](https://www.elastic.co/guide/en/elasticsearch/reference/current/parent-join.html) relations can make queries hundreds of times slower. So if the same questions can be answered without joins by denormalizing documents, significant speedups can be expected. + + +## Search as few fields as possible [search-as-few-fields-as-possible] + +The more fields a [`query_string`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html) or [`multi_match`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html) query targets, the slower it is. A common technique to improve search speed over multiple fields is to copy their values into a single field at index time, and then use this field at search time. This can be automated with the [`copy-to`](https://www.elastic.co/guide/en/elasticsearch/reference/current/copy-to.html) directive of mappings without having to change the source of documents. Here is an example of an index containing movies that optimizes queries that search over both the name and the plot of the movie by indexing both values into the `name_and_plot` field. + +```console +PUT movies +{ + "mappings": { + "properties": { + "name_and_plot": { + "type": "text" + }, + "name": { + "type": "text", + "copy_to": "name_and_plot" + }, + "plot": { + "type": "text", + "copy_to": "name_and_plot" + } + } + } +} +``` + + +## Pre-index data [_pre_index_data] + +You should leverage patterns in your queries to optimize the way data is indexed. For instance, if all your documents have a `price` field and most queries run [`range`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-range-aggregation.html) aggregations on a fixed list of ranges, you could make this aggregation faster by pre-indexing the ranges into the index and using a [`terms`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) aggregations. + +For instance, if documents look like: + +```console +PUT index/_doc/1 +{ + "designation": "spoon", + "price": 13 +} +``` + +and search requests look like: + +```console +GET index/_search +{ + "aggs": { + "price_ranges": { + "range": { + "field": "price", + "ranges": [ + { "to": 10 }, + { "from": 10, "to": 100 }, + { "from": 100 } + ] + } + } + } +} +``` + +Then documents could be enriched by a `price_range` field at index time, which should be mapped as a [`keyword`](https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html): + +```console +PUT index +{ + "mappings": { + "properties": { + "price_range": { + "type": "keyword" + } + } + } +} + +PUT index/_doc/1 +{ + "designation": "spoon", + "price": 13, + "price_range": "10-100" +} +``` + +And then search requests could aggregate this new field rather than running a `range` aggregation on the `price` field. + +```console +GET index/_search +{ + "aggs": { + "price_ranges": { + "terms": { + "field": "price_range" + } + } + } +} +``` + + +## Consider mapping identifiers as `keyword` [map-ids-as-keyword] + +Not all numeric data should be mapped as a [numeric](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html) field data type. {{es}} optimizes numeric fields, such as `integer` or `long`, for [`range`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html) queries. However, [`keyword`](https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html) fields are better for [`term`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-term-query.html) and other [term-level](https://www.elastic.co/guide/en/elasticsearch/reference/current/term-level-queries.html) queries. + +Identifiers, such as an ISBN or a product ID, are rarely used in `range` queries. However, they are often retrieved using term-level queries. + +Consider mapping a numeric identifier as a `keyword` if: + +* You don’t plan to search for the identifier data using [`range`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html) queries. +* Fast retrieval is important. `term` query searches on `keyword` fields are often faster than `term` searches on numeric fields. + +If you’re unsure which to use, you can use a [multi-field](https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-fields.html) to map the data as both a `keyword` *and* a numeric data type. + + +## Avoid scripts [_avoid_scripts] + +If possible, avoid using [script](../../../explore-analyze/scripting.md)-based sorting, scripts in aggregations, and the [`script_score`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-script-score-query.html) query. See [Scripts, caching, and search speed](../../../explore-analyze/scripting/scripts-search-speed.md). + + +## Search rounded dates [_search_rounded_dates] + +Queries on date fields that use `now` are typically not cacheable since the range that is being matched changes all the time. However switching to a rounded date is often acceptable in terms of user experience, and has the benefit of making better use of the query cache. + +For instance the below query: + +```console +PUT index/_doc/1 +{ + "my_date": "2016-05-11T16:30:55.328Z" +} + +GET index/_search +{ + "query": { + "constant_score": { + "filter": { + "range": { + "my_date": { + "gte": "now-1h", + "lte": "now" + } + } + } + } + } +} +``` + +could be replaced with the following query: + +```console +GET index/_search +{ + "query": { + "constant_score": { + "filter": { + "range": { + "my_date": { + "gte": "now-1h/m", + "lte": "now/m" + } + } + } + } + } +} +``` + +In that case we rounded to the minute, so if the current time is `16:31:29`, the range query will match everything whose value of the `my_date` field is between `15:31:00` and `16:31:59`. And if several users run a query that contains this range in the same minute, the query cache could help speed things up a bit. The longer the interval that is used for rounding, the more the query cache can help, but beware that too aggressive rounding might also hurt user experience. + +::::{note} +It might be tempting to split ranges into a large cacheable part and smaller not cacheable parts in order to be able to leverage the query cache, as shown below: +:::: + + +```console +GET index/_search +{ + "query": { + "constant_score": { + "filter": { + "bool": { + "should": [ + { + "range": { + "my_date": { + "gte": "now-1h", + "lte": "now-1h/m" + } + } + }, + { + "range": { + "my_date": { + "gt": "now-1h/m", + "lt": "now/m" + } + } + }, + { + "range": { + "my_date": { + "gte": "now/m", + "lte": "now" + } + } + } + ] + } + } + } + } +} +``` + +However such practice might make the query run slower in some cases since the overhead introduced by the `bool` query may defeat the savings from better leveraging the query cache. + + +## Force-merge read-only indices [_force_merge_read_only_indices] + +Indices that are read-only may benefit from being [merged down to a single segment](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html). This is typically the case with time-based indices: only the index for the current time frame is getting new documents while older indices are read-only. Shards that have been force-merged into a single segment can use simpler and more efficient data structures to perform searches. + +::::{important} +Do not force-merge indices to which you are still writing, or to which you will write again in the future. Instead, rely on the automatic background merge process to perform merges as needed to keep the index running smoothly. If you continue to write to a force-merged index then its performance may become much worse. +:::: + + + +## Warm up global ordinals [_warm_up_global_ordinals] + +[Global ordinals](https://www.elastic.co/guide/en/elasticsearch/reference/current/eager-global-ordinals.html) are a data structure that is used to optimize the performance of aggregations. They are calculated lazily and stored in the JVM heap as part of the [field data cache](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-fielddata.html). For fields that are heavily used for bucketing aggregations, you can tell {{es}} to construct and cache the global ordinals before requests are received. This should be done carefully because it will increase heap usage and can make [refreshes](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html) take longer. The option can be updated dynamically on an existing mapping by setting the [eager global ordinals](https://www.elastic.co/guide/en/elasticsearch/reference/current/eager-global-ordinals.html) mapping parameter: + +```console +PUT index +{ + "mappings": { + "properties": { + "foo": { + "type": "keyword", + "eager_global_ordinals": true + } + } + } +} +``` + + +## Warm up the filesystem cache [_warm_up_the_filesystem_cache] + +If the machine running Elasticsearch is restarted, the filesystem cache will be empty, so it will take some time before the operating system loads hot regions of the index into memory so that search operations are fast. You can explicitly tell the operating system which files should be loaded into memory eagerly depending on the file extension using the [`index.store.preload`](https://www.elastic.co/guide/en/elasticsearch/reference/current/preload-data-to-file-system-cache.html) setting. + +::::{warning} +Loading data into the filesystem cache eagerly on too many indices or too many files will make search *slower* if the filesystem cache is not large enough to hold all the data. Use with caution. +:::: + + + +## Use index sorting to speed up conjunctions [_use_index_sorting_to_speed_up_conjunctions] + +[Index sorting](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-index-sorting.html) can be useful in order to make conjunctions faster at the cost of slightly slower indexing. Read more about it in the [index sorting documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-index-sorting-conjunctions.html). + + +## Use `preference` to optimize cache utilization [preference-cache-optimization] + +There are multiple caches that can help with search performance, such as the [filesystem cache](https://en.wikipedia.org/wiki/Page_cache), the [request cache](https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-request-cache.html) or the [query cache](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-cache.html). Yet all these caches are maintained at the node level, meaning that if you run the same request twice in a row, have 1 replica or more and use [round-robin](https://en.wikipedia.org/wiki/Round-robin_DNS), the default routing algorithm, then those two requests will go to different shard copies, preventing node-level caches from helping. + +Since it is common for users of a search application to run similar requests one after another, for instance in order to analyze a narrower subset of the index, using a preference value that identifies the current user or session could help optimize usage of the caches. + + +## Replicas might help with throughput, but not always [_replicas_might_help_with_throughput_but_not_always] + +In addition to improving resiliency, replicas can help improve throughput. For instance if you have a single-shard index and three nodes, you will need to set the number of replicas to 2 in order to have 3 copies of your shard in total so that all nodes are utilized. + +Now imagine that you have a 2-shards index and two nodes. In one case, the number of replicas is 0, meaning that each node holds a single shard. In the second case the number of replicas is 1, meaning that each node has two shards. Which setup is going to perform best in terms of search performance? Usually, the setup that has fewer shards per node in total will perform better. The reason for that is that it gives a greater share of the available filesystem cache to each shard, and the filesystem cache is probably Elasticsearch’s number 1 performance factor. At the same time, beware that a setup that does not have replicas is subject to failure in case of a single node failure, so there is a trade-off between throughput and availability. + +So what is the right number of replicas? If you have a cluster that has `num_nodes` nodes, `num_primaries` primary shards *in total* and if you want to be able to cope with `max_failures` node failures at once at most, then the right number of replicas for you is `max(max_failures, ceil(num_nodes / num_primaries) - 1)`. + + +## Tune your queries with the Search Profiler [_tune_your_queries_with_the_search_profiler] + +The [Profile API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-profile.html) provides detailed information about how each component of your queries and aggregations impacts the time it takes to process the request. + +The [Search Profiler](../../../explore-analyze/query-filter/tools/search-profiler.md) in {{kib}} makes it easy to navigate and analyze the profile results and give you insight into how to tune your queries to improve performance and reduce load. + +Because the Profile API itself adds significant overhead to the query, this information is best used to understand the relative cost of the various query components. It does not provide a reliable measure of actual processing time. + + +## Faster phrase queries with `index_phrases` [faster-phrase-queries] + +The [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) field has an [`index_phrases`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-phrases.html) option that indexes 2-shingles and is automatically leveraged by query parsers to run phrase queries that don’t have a slop. If your use-case involves running lots of phrase queries, this can speed up queries significantly. + + +## Faster prefix queries with `index_prefixes` [faster-prefix-queries] + +The [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) field has an [`index_prefixes`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-prefixes.html) option that indexes prefixes of all terms and is automatically leveraged by query parsers to run prefix queries. If your use-case involves running lots of prefix queries, this can speed up queries significantly. + + +## Use `constant_keyword` to speed up filtering [faster-filtering-with-constant-keyword] + +There is a general rule that the cost of a filter is mostly a function of the number of matched documents. Imagine that you have an index containing cycles. There are a large number of bicycles and many searches perform a filter on `cycle_type: bicycle`. This very common filter is unfortunately also very costly since it matches most documents. There is a simple way to avoid running this filter: move bicycles to their own index and filter bicycles by searching this index instead of adding a filter to the query. + +Unfortunately this can make client-side logic tricky, which is where `constant_keyword` helps. By mapping `cycle_type` as a `constant_keyword` with value `bicycle` on the index that contains bicycles, clients can keep running the exact same queries as they used to run on the monolithic index and Elasticsearch will do the right thing on the bicycles index by ignoring filters on `cycle_type` if the value is `bicycle` and returning no hits otherwise. + +Here is what mappings could look like: + +```console +PUT bicycles +{ + "mappings": { + "properties": { + "cycle_type": { + "type": "constant_keyword", + "value": "bicycle" + }, + "name": { + "type": "text" + } + } + } +} + +PUT other_cycles +{ + "mappings": { + "properties": { + "cycle_type": { + "type": "keyword" + }, + "name": { + "type": "text" + } + } + } +} +``` + +We are splitting our index in two: one that will contain only bicycles, and another one that contains other cycles: unicycles, tricycles, etc. Then at search time, we need to search both indices, but we don’t need to modify queries. + +```console +GET bicycles,other_cycles/_search +{ + "query": { + "bool": { + "must": { + "match": { + "description": "dutch" + } + }, + "filter": { + "term": { + "cycle_type": "bicycle" + } + } + } + } +} +``` + +On the `bicycles` index, Elasticsearch will simply ignore the `cycle_type` filter and rewrite the search request to the one below: + +```console +GET bicycles,other_cycles/_search +{ + "query": { + "match": { + "description": "dutch" + } + } +} +``` + +On the `other_cycles` index, Elasticsearch will quickly figure out that `bicycle` doesn’t exist in the terms dictionary of the `cycle_type` field and return a search response with no hits. + +This is a powerful way of making queries cheaper by putting common values in a dedicated index. This idea can also be combined across multiple fields: for instance if you track the color of each cycle and your `bicycles` index ends up having a majority of black bikes, you could split it into a `bicycles-black` and a `bicycles-other-colors` indices. + +The `constant_keyword` is not strictly required for this optimization: it is also possible to update the client-side logic in order to route queries to the relevant indices based on filters. However `constant_keyword` makes it transparently and allows to decouple search requests from the index topology in exchange of very little overhead. + + +## Default search timeout [_default_search_timeout] + +By default, search requests don’t time out. You can set a timeout using the [`search.default_search_timeout`](../../../solutions/search/querying-for-search-searching-with-the-search-api.md#search-timeout) setting. + diff --git a/deploy-manage/production-guidance/optimize-performance/size-shards.md b/deploy-manage/production-guidance/optimize-performance/size-shards.md new file mode 100644 index 000000000..96e4030c9 --- /dev/null +++ b/deploy-manage/production-guidance/optimize-performance/size-shards.md @@ -0,0 +1,371 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html +--- + +# Size your shards [size-your-shards] + +Each index in {{es}} is divided into one or more shards, each of which may be replicated across multiple nodes to protect against hardware failures. If you are using [Data streams](../../../manage-data/data-store/index-types/data-streams.md) then each data stream is backed by a sequence of indices. There is a limit to the amount of data you can store on a single node so you can increase the capacity of your cluster by adding nodes and increasing the number of indices and shards to match. However, each index and shard has some overhead and if you divide your data across too many shards then the overhead can become overwhelming. A cluster with too many indices or shards is said to suffer from *oversharding*. An oversharded cluster will be less efficient at responding to searches and in extreme cases it may even become unstable. + + +## Create a sharding strategy [create-a-sharding-strategy] + +The best way to prevent oversharding and other shard-related issues is to create a sharding strategy. A sharding strategy helps you determine and maintain the optimal number of shards for your cluster while limiting the size of those shards. + +Unfortunately, there is no one-size-fits-all sharding strategy. A strategy that works in one environment may not scale in another. A good sharding strategy must account for your infrastructure, use case, and performance expectations. + +The best way to create a sharding strategy is to benchmark your production data on production hardware using the same queries and indexing loads you’d see in production. For our recommended methodology, watch the [quantitative cluster sizing video](https://www.elastic.co/elasticon/conf/2016/sf/quantitative-cluster-sizing). As you test different shard configurations, use {{kib}}'s [{{es}} monitoring tools](../../monitor/monitoring-data/elasticsearch-metrics.md) to track your cluster’s stability and performance. + +The performance of an {{es}} node is often limited by the performance of the underlying storage. Review our recommendations for optimizing your storage for [indexing](indexing-speed.md#indexing-use-faster-hardware) and [search](search-speed.md#search-use-faster-hardware). + +The following sections provide some reminders and guidelines you should consider when designing your sharding strategy. If your cluster is already oversharded, see [Reduce a cluster’s shard count](#reduce-cluster-shard-count). + + +## Sizing considerations [shard-sizing-considerations] + +Keep the following things in mind when building your sharding strategy. + + +### Searches run on a single thread per shard [single-thread-per-shard] + +Most searches hit multiple shards. Each shard runs the search on a single CPU thread. While a shard can run multiple concurrent searches, searches across a large number of shards can deplete a node’s [search thread pool](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-threadpool.html). This can result in low throughput and slow search speeds. + + +### Each index, shard, segment and field has overhead [each-shard-has-overhead] + +Every index and every shard requires some memory and CPU resources. In most cases, a small set of large shards uses fewer resources than many small shards. + +Segments play a big role in a shard’s resource usage. Most shards contain several segments, which store its index data. {{es}} keeps some segment metadata in heap memory so it can be quickly retrieved for searches. As a shard grows, its segments are [merged](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-merge.html) into fewer, larger segments. This decreases the number of segments, which means less metadata is kept in heap memory. + +Every mapped field also carries some overhead in terms of memory usage and disk space. By default {{es}} will automatically create a mapping for every field in every document it indexes, but you can switch off this behaviour to [take control of your mappings](../../../manage-data/data-store/mapping/explicit-mapping.md). + +Moreover every segment requires a small amount of heap memory for each mapped field. This per-segment-per-field heap overhead includes a copy of the field name, encoded using ISO-8859-1 if applicable or UTF-16 otherwise. Usually this is not noticeable, but you may need to account for this overhead if your shards have high segment counts and the corresponding mappings contain high field counts and/or very long field names. + + +### {{es}} automatically balances shards within a data tier [shard-auto-balance] + +A cluster’s nodes are grouped into [data tiers](../../../manage-data/lifecycle/data-tiers.md). Within each tier, {{es}} attempts to spread an index’s shards across as many nodes as possible. When you add a new node or a node fails, {{es}} automatically rebalances the index’s shards across the tier’s remaining nodes. + + +## Best practices [shard-size-best-practices] + +Where applicable, use the following best practices as starting points for your sharding strategy. + + +### Delete indices, not documents [delete-indices-not-documents] + +Deleted documents aren’t immediately removed from {{es}}'s file system. Instead, {{es}} marks the document as deleted on each related shard. The marked document will continue to use resources until it’s removed during a periodic [segment merge](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-merge.html). + +When possible, delete entire indices instead. {{es}} can immediately remove deleted indices directly from the file system and free up resources. + + +### Use data streams and {{ilm-init}} for time series data [use-ds-ilm-for-time-series] + +[Data streams](../../../manage-data/data-store/index-types/data-streams.md) let you store time series data across multiple, time-based backing indices. You can use [{{ilm}} ({{ilm-init}})](../../../manage-data/lifecycle/index-lifecycle-management.md) to automatically manage these backing indices. + +One advantage of this setup is [automatic rollover](../../../manage-data/lifecycle/index-lifecycle-management.md), which creates a new write index when the current one meets a defined `max_primary_shard_size`, `max_age`, `max_docs`, or `max_size` threshold. When an index is no longer needed, you can use {{ilm-init}} to automatically delete it and free up resources. + +{{ilm-init}} also makes it easy to change your sharding strategy over time: + +* **Want to decrease the shard count for new indices?**
Change the [`index.number_of_shards`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-number-of-shards) setting in the data stream’s [matching index template](../../../manage-data/data-store/index-types/modify-data-stream.md#data-streams-change-mappings-and-settings). +* **Want larger shards or fewer backing indices?**
Increase your {{ilm-init}} policy’s [rollover threshold](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-rollover.html). +* **Need indices that span shorter intervals?**
Offset the increased shard count by deleting older indices sooner. You can do this by lowering the `min_age` threshold for your policy’s [delete phase](../../../manage-data/lifecycle/index-lifecycle-management/index-lifecycle.md). + +Every new backing index is an opportunity to further tune your strategy. + + +### Aim for shards of up to 200M documents, or with sizes between 10GB and 50GB [shard-size-recommendation] + +There is some overhead associated with each shard, both in terms of cluster management and search performance. Searching a thousand 50MB shards will be substantially more expensive than searching a single 50GB shard containing the same data. However, very large shards can also cause slower searches and will take longer to recover after a failure. + +There is no hard limit on the physical size of a shard, and each shard can in theory contain up to [just over two billion documents](#troubleshooting-max-docs-limit). However, experience shows that shards between 10GB and 50GB typically work well for many use cases, as long as the per-shard document count is kept below 200 million. + +You may be able to use larger shards depending on your network and use case, and smaller shards may be appropriate for [Enterprise Search](https://www.elastic.co/guide/en/enterprise-search/current/index.html) and similar use cases. + +If you use {{ilm-init}}, set the [rollover action](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-rollover.html)'s `max_primary_shard_size` threshold to `50gb` to avoid shards larger than 50GB and `min_primary_shard_size` threshold to `10gb` to avoid shards smaller than 10GB. + +To see the current size of your shards, use the [cat shards API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-shards.html). + +```console +GET _cat/shards?v=true&h=index,prirep,shard,store&s=prirep,store&bytes=gb +``` + +The `pri.store.size` value shows the combined size of all primary shards for the index. + +```txt +index prirep shard store +.ds-my-data-stream-2099.05.06-000001 p 0 50gb +... +``` + +If an index’s shard is experiencing degraded performance from surpassing the recommended 50GB size, you may consider fixing the index’s shards' sizing. Shards are immutable and therefore their size is fixed in place, so indices must be copied with corrected settings. This requires first ensuring sufficient disk to copy the data. Afterwards, you can copy the index’s data with corrected settings via one of the following options: + +* running [Split Index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) to increase number of primary shards +* creating a destination index with corrected settings and then running [Reindex](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) + +Kindly note performing a [Restore Snapshot](https://www.elastic.co/guide/en/elasticsearch/reference/current/restore-snapshot-api.html) and/or [Clone Index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-clone-index.html) would be insufficient to resolve shards' sizing. + +Once a source index’s data is copied into its destination index, the source index can be [removed](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-delete-index.html). You may then consider setting [Create Alias](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-add-alias.html) against the destination index for the source index’s name to point to it for continuity. + +See this [fixing shard sizes video](https://www.youtube.com/watch?v=sHyNYnwbYro) for an example troubleshooting walkthrough. + + +### Master-eligible nodes should have at least 1GB of heap per 3000 indices [shard-count-recommendation] + +The number of indices a master node can manage is proportional to its heap size. The exact amount of heap memory needed for each index depends on various factors such as the size of the mapping and the number of shards per index. + +As a general rule of thumb, you should have fewer than 3000 indices per GB of heap on master nodes. For example, if your cluster has dedicated master nodes with 4GB of heap each then you should have fewer than 12000 indices. If your master nodes are not dedicated master nodes then the same sizing guidance applies: you should reserve at least 1GB of heap on each master-eligible node for every 3000 indices in your cluster. + +Note that this rule defines the absolute maximum number of indices that a master node can manage, but does not guarantee the performance of searches or indexing involving this many indices. You must also ensure that your data nodes have adequate resources for your workload and that your overall sharding strategy meets all your performance requirements. See also [Searches run on a single thread per shard](#single-thread-per-shard) and [Each index, shard, segment and field has overhead](#each-shard-has-overhead). + +To check the configured size of each node’s heap, use the [cat nodes API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-nodes.html). + +```console +GET _cat/nodes?v=true&h=heap.max +``` + +You can use the [cat shards API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-shards.html) to check the number of shards per node. + +```console +GET _cat/shards?v=true +``` + + +### Add enough nodes to stay within the cluster shard limits [shard-count-per-node-recommendation] + +[Cluster shard limits](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-shard-limit) prevent creation of more than 1000 non-frozen shards per node, and 3000 frozen shards per dedicated frozen node. Make sure you have enough nodes of each type in your cluster to handle the number of shards you need. + + +### Allow enough heap for field mappers and overheads [field-count-recommendation] + +Mapped fields consume some heap memory on each node, and require extra heap on data nodes. Ensure each node has enough heap for mappings, and also allow extra space for overheads associated with its workload. The following sections show how to determine these heap requirements. + + +#### Mapping metadata in the cluster state [_mapping_metadata_in_the_cluster_state] + +Each node in the cluster has a copy of the [cluster state](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state.html#cluster-state-api-desc). The cluster state includes information about the field mappings for each index. This information has heap overhead. You can use the [Cluster stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-stats.html) to get the heap overhead of the total size of all mappings after deduplication and compression. + +```console +GET _cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size* +``` + +This will show you information like in this example output: + +```console-result +{ + "indices": { + "mappings": { + "total_deduplicated_mapping_size": "1gb", + "total_deduplicated_mapping_size_in_bytes": 1073741824 + } + } +} +``` + + +#### Retrieving heap size and field mapper overheads [_retrieving_heap_size_and_field_mapper_overheads] + +You can use the [Nodes stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-stats.html) to get two relevant metrics for each node: + +* The size of the heap on each node. +* Any additional estimated heap overhead for the fields per node. This is specific to data nodes, where apart from the cluster state field information mentioned above, there is additional heap overhead for each mapped field of an index held by the data node. For nodes which are not data nodes, this field may be zero. + +```console +GET _nodes/stats?human&filter_path=nodes.*.name,nodes.*.indices.mappings.total_estimated_overhead*,nodes.*.jvm.mem.heap_max* +``` + +For each node, this will show you information like in this example output: + +```console-result +{ + "nodes": { + "USpTGYaBSIKbgSUJR2Z9lg": { + "name": "node-0", + "indices": { + "mappings": { + "total_estimated_overhead": "1gb", + "total_estimated_overhead_in_bytes": 1073741824 + } + }, + "jvm": { + "mem": { + "heap_max": "4gb", + "heap_max_in_bytes": 4294967296 + } + } + } + } +} +``` + + +#### Consider additional heap overheads [_consider_additional_heap_overheads] + +Apart from the two field overhead metrics above, you must additionally allow enough heap for {{es}}'s baseline usage as well as your workload such as indexing, searches and aggregations. 0.5GB of extra heap will suffice for many reasonable workloads, and you may need even less if your workload is very light while heavy workloads may require more. + + +#### Example [_example_10] + +As an example, consider the outputs above for a data node. The heap of the node will need at least: + +* 1 GB for the cluster state field information. +* 1 GB for the additional estimated heap overhead for the fields of the data node. +* 0.5 GB of extra heap for other overheads. + +Since the node has a 4GB heap max size in the example, it is thus sufficient for the total required heap of 2.5GB. + +If the heap max size for a node is not sufficient, consider [avoiding unnecessary fields](#avoid-unnecessary-fields), or scaling up the cluster, or redistributing index shards. + +Note that the above rules do not necessarily guarantee the performance of searches or indexing involving a very high number of indices. You must also ensure that your data nodes have adequate resources for your workload and that your overall sharding strategy meets all your performance requirements. See also [Searches run on a single thread per shard](#single-thread-per-shard) and [Each index, shard, segment and field has overhead](#each-shard-has-overhead). + + +### Avoid node hotspots [avoid-node-hotspots] + +If too many shards are allocated to a specific node, the node can become a hotspot. For example, if a single node contains too many shards for an index with a high indexing volume, the node is likely to have issues. + +To prevent hotspots, use the [`index.routing.allocation.total_shards_per_node`](https://www.elastic.co/guide/en/elasticsearch/reference/current/allocation-total-shards.html#total-shards-per-node) index setting to explicitly limit the number of shards on a single node. You can configure `index.routing.allocation.total_shards_per_node` using the [update index settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-update-settings.html). + +```console +PUT my-index-000001/_settings +{ + "index" : { + "routing.allocation.total_shards_per_node" : 5 + } +} +``` + + +### Avoid unnecessary mapped fields [avoid-unnecessary-fields] + +By default {{es}} [automatically creates a mapping](../../../manage-data/data-store/mapping/dynamic-mapping.md) for every field in every document it indexes. Every mapped field corresponds to some data structures on disk which are needed for efficient search, retrieval, and aggregations on this field. Details about each mapped field are also held in memory. In many cases this overhead is unnecessary because a field is not used in any searches or aggregations. Use [*Explicit mapping*](../../../manage-data/data-store/mapping/explicit-mapping.md) instead of dynamic mapping to avoid creating fields that are never used. If a collection of fields are typically used together, consider using [`copy_to`](https://www.elastic.co/guide/en/elasticsearch/reference/current/copy-to.html) to consolidate them at index time. If a field is only rarely used, it may be better to make it a [Runtime field](../../../manage-data/data-store/mapping/runtime-fields.md) instead. + +You can get information about which fields are being used with the [Field usage stats](https://www.elastic.co/guide/en/elasticsearch/reference/current/field-usage-stats.html) API, and you can analyze the disk usage of mapped fields using the [Analyze index disk usage](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-disk-usage.html) API. Note however that unnecessary mapped fields also carry some memory overhead as well as their disk usage. + + +## Reduce a cluster’s shard count [reduce-cluster-shard-count] + +If your cluster is already oversharded, you can use one or more of the following methods to reduce its shard count. + + +### Create indices that cover longer time periods [create-indices-that-cover-longer-time-periods] + +If you use {{ilm-init}} and your retention policy allows it, avoid using a `max_age` threshold for the rollover action. Instead, use `max_primary_shard_size` to avoid creating empty indices or many small shards. + +If your retention policy requires a `max_age` threshold, increase it to create indices that cover longer time intervals. For example, instead of creating daily indices, you can create indices on a weekly or monthly basis. + + +### Delete empty or unneeded indices [delete-empty-indices] + +If you’re using {{ilm-init}} and roll over indices based on a `max_age` threshold, you can inadvertently create indices with no documents. These empty indices provide no benefit but still consume resources. + +You can find these empty indices using the [cat count API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-count.html). + +```console +GET _cat/count/my-index-000001?v=true +``` + +Once you have a list of empty indices, you can delete them using the [delete index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-delete-index.html). You can also delete any other unneeded indices. + +```console +DELETE my-index-000001 +``` + + +### Force merge during off-peak hours [force-merge-during-off-peak-hours] + +If you no longer write to an index, you can use the [force merge API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html) to [merge](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-merge.html) smaller segments into larger ones. This can reduce shard overhead and improve search speeds. However, force merges are resource-intensive. If possible, run the force merge during off-peak hours. + +```console +POST my-index-000001/_forcemerge +``` + + +### Shrink an existing index to fewer shards [shrink-existing-index-to-fewer-shards] + +If you no longer write to an index, you can use the [shrink index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html) to reduce its shard count. + +{{ilm-init}} also has a [shrink action](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-shrink.html) for indices in the warm phase. + + +### Combine smaller indices [combine-smaller-indices] + +You can also use the [reindex API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) to combine indices with similar mappings into a single large index. For time series data, you could reindex indices for short time periods into a new index covering a longer period. For example, you could reindex daily indices from October with a shared index pattern, such as `my-index-2099.10.11`, into a monthly `my-index-2099.10` index. After the reindex, delete the smaller indices. + +```console +POST _reindex +{ + "source": { + "index": "my-index-2099.10.*" + }, + "dest": { + "index": "my-index-2099.10" + } +} +``` + + +## Troubleshoot shard-related errors [troubleshoot-shard-related-errors] + +Here’s how to resolve common shard-related errors. + + +### this action would add [x] total shards, but this cluster currently has [y]/[z] maximum shards open; [troubleshooting-max-shards-open] + +The [`cluster.max_shards_per_node`](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-max-shards-per-node) cluster setting limits the maximum number of open shards for a cluster. This error indicates an action would exceed this limit. + +If you’re confident your changes won’t destabilize the cluster, you can temporarily increase the limit using the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) and retry the action. + +```console +PUT _cluster/settings +{ + "persistent" : { + "cluster.max_shards_per_node": 1200 + } +} +``` + +This increase should only be temporary. As a long-term solution, we recommend you add nodes to the oversharded data tier or [reduce your cluster’s shard count](#reduce-cluster-shard-count). To get a cluster’s current shard count after making changes, use the [cluster stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-stats.html). + +```console +GET _cluster/stats?filter_path=indices.shards.total +``` + +When a long-term solution is in place, we recommend you reset the `cluster.max_shards_per_node` limit. + +```console +PUT _cluster/settings +{ + "persistent" : { + "cluster.max_shards_per_node": null + } +} +``` + +See this [fixing "max shards open" video](https://www.youtube.com/watch?v=tZKbDegt4-M) for an example troubleshooting walkthrough. For more information, see [Troubleshooting shards capacity](../../../troubleshoot/elasticsearch/troubleshooting-shards-capacity-issues.md). + + +### Number of documents in the shard cannot exceed [2147483519] [troubleshooting-max-docs-limit] + +Each {{es}} shard is a separate Lucene index, so it shares Lucene’s [`MAX_DOC` limit](https://github.com/apache/lucene/issues/5176) of having at most 2,147,483,519 (`(2^31)-129`) documents. This per-shard limit applies to the sum of `docs.count` plus `docs.deleted` as reported by the [Index stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-stats.html). Exceeding this limit will result in errors like the following: + +```txt +Elasticsearch exception [type=illegal_argument_exception, reason=Number of documents in the shard cannot exceed [2147483519]] +``` + +::::{tip} +This calculation may differ from the [Count API’s](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html) calculation, because the Count API does not include nested documents and does not count deleted documents. +:::: + + +This limit is much higher than the [recommended maximum document count](#shard-size-recommendation) of approximately 200M documents per shard. + +If you encounter this problem, try to mitigate it by using the [Force Merge API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html) to merge away some deleted docs. For example: + +```console +POST my-index-000001/_forcemerge?only_expunge_deletes=true +``` + +This will launch an asynchronous task which can be monitored via the [Task Management API](https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html). + +It may also be helpful to [delete unneeded documents](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html), or to [split](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) or [reindex](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) the index into one with a larger number of shards. + diff --git a/deploy-manage/production-guidance/plan-for-production-elastic-cloud.md b/deploy-manage/production-guidance/plan-for-production-elastic-cloud.md new file mode 100644 index 000000000..90c090354 --- /dev/null +++ b/deploy-manage/production-guidance/plan-for-production-elastic-cloud.md @@ -0,0 +1,26 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-planning.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-planning.html +--- + +# Plan for production (Elastic Cloud) + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/341 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-planning.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-planning.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ech-ha$$$ + +$$$ec-ha$$$ + +$$$ec-workloads$$$ + +$$$ech-workloads$$$ \ No newline at end of file diff --git a/deploy-manage/reference-architectures.md b/deploy-manage/reference-architectures.md new file mode 100644 index 000000000..aa8bbcd92 --- /dev/null +++ b/deploy-manage/reference-architectures.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/reference-architectures/current/reference-architectures-overview.html +--- + +# Reference architectures [reference-architectures-overview] + +Elasticsearch reference architectures are blueprints for deploying Elasticsearch clusters tailored to different use cases. Whether you’re handling logs or metrics these reference architectures focus on scalability, reliability, and cost efficiency. Use these guidelines to deploy Elasticsearch for your use case. + +These architectures are designed by architects and engineers to provide standardized, proven solutions that help you to follow best practices when deploying {{es}}. + +::::{tip} +These architectures are specific to running your deployment on-premises or on cloud. If you are using Elastic serverless your {{es}} clusters are autoscaled and fully managed by Elastic. For all the deployment options, refer to [Run Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro-deploy.md). +:::: + + +These reference architectures are recommendations and should be adapted to fit your specific environment and needs. Each solution can vary based on the unique requirements and conditions of your deployment. In these architectures we discuss about how to deploy cluster components. For information about designing ingest architectures to feed content into your cluster, refer to [Ingest architectures](https://www.elastic.co/guide/en/ingest/current/use-case-arch.md) + + +## Architectures [reference-architectures-time-series-2] + +| | | +| --- | --- | +| **Architecture** | **When to use** | +| [*Hot/Frozen - High Availability*](https://www.elastic.co/guide/en/reference-architectures/current/hot-frozen-architecture.html)
A high availability architecture that is cost optimized for large time-series datasets. | * Have a requirement for cost effective long term data storage (many months or years).
* Provide insights and alerts using logs, metrics, traces, or various event types to ensure optimal performance and quick issue resolution for applications.
* Apply Machine Learning and Search AI to assist in dealing with the large amount of data.
* Deploy an architecture model that allows for maximum flexibility between storage cost and performance.
| +| Additional architectures are on the way.
Stay tuned for updates. | | + diff --git a/deploy-manage/reference-architectures/hotfrozen-high-availability.md b/deploy-manage/reference-architectures/hotfrozen-high-availability.md new file mode 100644 index 000000000..f5378a9d9 --- /dev/null +++ b/deploy-manage/reference-architectures/hotfrozen-high-availability.md @@ -0,0 +1,109 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/reference-architectures/current/hot-frozen-architecture.html +--- + +# Hot/Frozen - High Availability [hot-frozen-architecture] + +The Hot/Frozen High Availability architecture is cost optimized for large time-series datasets. In this architecture, the hot tier is primarily used for indexing, searching, and continuity for automated processes. [Searchable snapshots](https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html) are taken from hot into a repository, such as a cloud object store or an on-premises shared filesystem, and then cached to any desired volume on the local disks of the frozen tier. Data in the repository is indexed for fast retrieval and accessed on-demand from the frozen nodes. Index and snapshot lifecycle management are used to automate this process. + +This architecture is ideal for time-series use cases, such as Observability or Security, that do not require updating. All the necessary components of the {{stack}} are included. This is not intended for sizing workloads, but rather as a basis to ensure that your cluster is ready to handle any desired workload with resiliency. A very high level representation of data flow is included, and for more detail around ingest architecture see our [ingest architectures](../../manage-data/ingest/ingest-reference-architectures/use-case-arch.md) documentation. + + +## Hot/Frozen use case [hot-frozen-use-case] + +This Hot/Frozen – High Availability architecture is intended for organizations that: + +* Have a requirement for cost effective long term data storage (many months or years). +* Provide insights and alerts using logs, metrics, traces, or various event types to ensure optimal performance and quick issue resolution for applications. +* Apply [machine learning anomaly detection](https://www.elastic.co/guide/en/kibana/current/xpack-ml-anomalies.html) to help detect patterns in time series data to find root cause and resolve problems faster. +* Use an AI assistant ([Observability](https://www.elastic.co/guide/en/observability/current/obs-ai-assistant.html), [Security](https://www.elastic.co/guide/en/security/current/security-assistant.html), or [Playground](https://www.elastic.co/guide/en/kibana/current/playground.html)) for investigation, incident response, reporting, query generation, or query conversion from other languages using natural language. +* Deploy an architecture model that allows for maximum flexibility between storage cost and performance. + +::::{important} +**Automated operations that frequently read large data volumes require both high availability (replicas) and predictable low latency (hot, warm or cold tier).** + +* Common examples of these tasks include look-back windows on security detection/alert rules, transforms, machine learning jobs, or watches; and long running scroll queries or external extract processes. +* These operations should be completed before moving the data into a frozen tier. + +:::: + + + +## Architecture [hot-frozen-architecture-diagram] + +:::{image} ../../images/reference-architectures-hot-frozen.png +:alt: A Hot/Frozen Highly available architecture +::: + +::::{tip} +We use an Availability Zone (AZ) concept in the architecture above. When running in your own Data Center (DC) you can equate AZs to failure zones within a datacenter, racks, or even separate physical machines depending on your constraints. +:::: + + +The diagram illustrates an {{es}} cluster deployed across 3 availability zones (AZ). For production we recommend a minimum of 2 availability zones and 3 availability zones for mission critical applications. See [Plan for production](https://www.elastic.co/guide/en/cloud/current/ec-planning.html) for more details. A cluster that is running in {{ecloud}} that has data nodes in only two AZs will create a third master-eligible node in a third AZ. High availability cannot be achieved without three zones for any distributed computing technology. + +The number of data nodes shown for each tier (hot and frozen) is illustrative and would be scaled up depending on ingest volume and retention period. Hot nodes contain both primary and replica shards. By default, primary and replica shards are always guaranteed to be in different availability zones in {{ess}}, but when self-deploying [shard allocation awareness](../distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md) would need to be configured. Frozen nodes act as a large high-speed cache and retrieve data from the snapshot store as needed. + +Machine learning nodes are optional but highly recommended for large scale time series use cases since the amount of data quickly becomes too difficult to analyze. Applying techniques such as machine learning based anomaly detection or Search AI with large language models helps to dramatically speed up problem identification and resolution. + + +## Recommended hardware specifications [hot-frozen-hardware] + +With {{ecloud}} you can deploy clusters in AWS, Azure, and Google Cloud. Available hardware types and configurations vary across all three cloud providers but each provides instance types that meet our recommendations for the node types used in this architecture. For more details on these instance types, see our documentation on {{ecloud}} hardware for [AWS](https://www.elastic.co/guide/en/cloud/current/ec-default-aws-configurations.html), [Azure](https://www.elastic.co/guide/en/cloud/current/ec-default-azure-configurations.html), and [GCP](https://www.elastic.co/guide/en/cloud/current/ec-default-gcp-configurations.html). The **Physical** column below is guidance, based on the cloud node types, when self-deploying {{es}} in your own data center. + +In the links provided above, Elastic has performance tested hardware for each of the cloud providers to find the optimal hardware for each node type. We use ratios to represent the best mix of CPU, RAM, and disk for each type. In some cases the CPU to RAM ratio is key, in others the disk to memory ratio and type of disk is critical. Significantly deviating from these ratios may seem like a way to save on hardware costs, but may result in an {{es}} cluster that does not scale and perform well. + +This table shows our specific recommendations for nodes in a Hot/Frozen architecture. + +| | | | | | +| --- | --- | --- | --- | --- | +| **Type** | **AWS*** | ***Azure*** | ***GCP** | **Physical** | +| ![Hot data node](../../images/reference-architectures-hot.png "") | c6gd | f32sv2 | N2 | 16-32 vCPU
64 GB RAM
2-6 TB NVMe SSD | +| ![Frozen data node](../../images/reference-architectures-frozen.png "") | i3en | e8dsv4 | N2 | 8 vCPU
64 GB RAM
6-20+ TB NVMe SSD
Depending on days cached | +| ![Machine learning node](../../images/reference-architectures-machine-learning.png "") | m6gd | f16sv2 | N2 | 16 vCPU
64 GB RAM
256 GB SSD | +| ![Master node](../../images/reference-architectures-master.png "") | c5d | f16sv2 | N2 | 8 vCPU
16 GB RAM
256 GB SSD | +| ![Kibana node](../../images/reference-architectures-kibana.png "") | c6gd | f16sv2 | N2 | 8-16 vCPU
8 GB RAM
256 GB SSD | + + +## Important considerations [hot-frozen-considerations] + +**Updating data:** + +* Typically, time series logging use cases are append-only and there is rarely a need to update documents. The frozen tier is read-only. + +**Multi-AZ frozen tier:** + +* Three availability zones is ideal, but at least two availability zones are recommended to ensure that there will be data nodes available in the event of an AZ failure. + +**Shard management:** + +* The most important foundational step to maintaining performance as you scale is proper shard management. This includes even shard distribution amongst nodes, shard size, and shard count. For a complete understanding of what shards are and how they should be used, refer to [Size your shards](https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html). + +**Snapshots:** + +* If auditable or business critical events are being logged, a backup is necessary. The choice to back up data will depend on each individual business’s needs and requirements. Refer to our [snapshot repository](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html) documentation to learn more. +* To automate snapshots and attach to Index lifecycle management policies, refer to [SLM (Snapshot lifecycle management)](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html#automate-snapshots-slm). + +**Kibana:** + +* If self-deploying outside of {{ess}}, ensure that {{kib}} is configured for [high availability](https://www.elastic.co/guide/en/kibana/current/production.html#high-availability). + + +## How many nodes of each do you need? [hot-frozen-estimate] + +It depends on: + +* The type of data being ingested (such as logs, metrics, traces) +* The retention period of searchable data (such as 30 days, 90 days, 1 year) +* The amount of data you need to ingest each day +* The number of dashboards, queries, query types and how frequent they are run. + +You can [contact us](https://www.elastic.co/contact) for an estimate and recommended configuration based on your specific scenario. + + +## Resources and references [hot-frozen-resources] + +* [{{es}} - Get ready for production](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html) +* [{{ess}} - Preparing a deployment for production](https://www.elastic.co/guide/en/cloud/current/ec-prepare-production.html) +* [Size your shards](https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html) diff --git a/deploy-manage/remote-clusters.md b/deploy-manage/remote-clusters.md new file mode 100644 index 000000000..d4ca57e75 --- /dev/null +++ b/deploy-manage/remote-clusters.md @@ -0,0 +1,9 @@ +# Remote clusters + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/345 + +% Scope notes: "Landing page for cross cluster comms, used by CCS and CCR. +We will cover here the raw configuration at Elasticsearch level and the docs to enable remote clusters in ESS / ECE / ECK. +We can include links to the use cases of remote clusters, such as CCR and CCS." diff --git a/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment.md b/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment.md new file mode 100644 index 000000000..9e818b88d --- /dev/null +++ b/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-edit-remove-trusted-environment.html +--- + +# Edit or remove a trusted environment [ec-edit-remove-trusted-environment] + +From a deployment’s **Security** page, you can manage trusted environments that were created previously. This can happen when: + +* You no longer need a trusted environment and want to remove it. +* You want to refresh the certificate, or add or remove trusted deployments of an existing trusted environment relying on certificates as a security model. +* You want to remove or update the access level granted by a cross-cluster API key. + + +## Remove a trusted environment [ec_remove_a_trusted_environment] + +By removing a trusted environment, this deployment will no longer be able to establish remote connections using certificate trust to clusters of that environment. The remote environment will also no longer be able to connect to this deployment using certificate trust. + +::::{note} +With this method, you can only remove trusted environments relying exclusively on certificates. To remove remote connections that use API keys for authentication, refer to [Update the access level of a remote cluster connection relying on a cross-cluster API key](#ec-edit-remove-trusted-environment-api-key). +:::: + + +1. Go to the deployment’s **Security** page. +2. In the list of trusted environments, locate the one you want to remove. +3. Remove it using the corresponding `delete` icon. + + :::{image} ../../images/cloud-delete-trust-environment.png + :alt: button for deleting a trusted environment + ::: + +4. In Kibana, go to **Stack Management** > **Remote Clusters**. +5. In the list of existing remote clusters, delete the ones corresponding to the trusted environment you removed earlier. + + +## Update a certificate-based trusted environment [ec_update_a_certificate_based_trusted_environment] + +1. Go to the deployment’s **Security** page. +2. In the list of trusted environments, locate the one you want to edit. +3. Open its details by selecting the `Edit` icon. + + :::{image} ../../images/cloud-edit-trust-environment.png + :alt: button for editing a trusted environment + ::: + +4. Edit the trust configuration for that environment: + + * From the **Trust level** tab, you can add or remove trusted deployments. + * From the **Environment settings** tab, you can manage the certificates and the label of the environment. + +5. Save your changes. + + +## Change a cross-cluster API key used for a remote connection [ec-edit-remove-trusted-environment-api-key] + +This section describes the steps to change the API key used for an existing remote connection. For example, if the previous key expired and you need to rotate it with a new one. + +::::{note} +If you need to update the permissions granted by a cross-cluster API key for a remote connection, you only need to update the privileges granted by the API key directly in Kibana. +:::: + + +1. On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key with the appropriate permissions. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +2. Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next steps. +3. Go to the **Security** page of the local deployment and locate the **Remote connections** section. +4. Locate the API key currently used for connecting to the remote cluster, copy its current alias, and delete it. +5. Add the new API key by selecting **Add an API key**. + + * For the **Setting name**, enter the same alias that was used for the previous key. + + ::::{note} + If you use a different alias, you also need to re-create the remote cluster in Kibana with a **Name** that matches the new alias. + :::: + + * For the **Secret**, paste the encoded cross-cluster API key. + + 1. Click **Add** to save the API key to the keystore. + +6. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: diff --git a/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md b/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md new file mode 100644 index 000000000..428215328 --- /dev/null +++ b/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md @@ -0,0 +1,88 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-enable-ccs-for-eck.html +--- + +# Enabling CCS/R between Elasticsearch Service and ECK [ec-enable-ccs-for-eck] + +These steps describe how to configure remote clusters between an {{es}} cluster in Elasticsearch Service and an {{es}} cluster running within [Elastic Cloud on Kubernetes (ECK)](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-overview.html). Once that’s done, you’ll be able to [run CCS queries from {{es}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html) or [set up CCR](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-getting-started.html). + + +## Establish trust between two clusters [ec_establish_trust_between_two_clusters] + +The first step is to establish trust between the two clusters. + + +### Establish trust in the Elasticsearch Service cluster [ec_establish_trust_in_the_elasticsearch_service_cluster] + +1. Save the ECK CA certificate to a file. For a cluster named `quickstart`, run: + + ```sh + kubectl get secret quickstart-es-transport-certs-public -o go-template='{{index .data "ca.crt" | base64decode}}' > eck.ca.crt + ``` + + +1. Update the trust settings for the Elasticsearch Service deployment. Follow the steps provided in [Access clusters of a self-managed environment](ec-remote-cluster-self-managed.md), and specifically the first three steps in **Specify the deployments trusted to be used as remote clusters** using TLS certificate as security model. + + * Use the certificate file saved in the first step. + * Select the {{ecloud}} pattern and enter `default.es.local` for the `Scope ID`. + +2. Select `Save` and then download the CA Certificate and `trust.yml` file. These files can also be retrieved in the `Security` page of the deployment. You will use these files in the next set of steps. + + +### Establish trust in the ECK cluster [ec_establish_trust_in_the_eck_cluster] + +1. Upload the Elasticsearch Service certificate (that you downloaded in the last step of the previous section) as a Kubernetes secret. + + ```sh + kubectl create secret generic ce-aws-cert --from-file= + ``` + +2. Upload the `trust.yml` file (that you downloaded in the last step of the previous section) as a Kubernetes config map. + + ```sh + kubectl create configmap quickstart-trust --from-file= + ``` + +3. Edit the {{es}} kubernetes resource to ensure the following sections are included. This assumes the {{es}} deployment is named `quickstart`. Make sure to replace the `CA-Certificate-Filename` placeholder with the correct value. Note that these configuration changes are required for all `nodeSets`. Applying this change requires all pods in all `nodeSets` to be deleted and recreated, which might take quite a while to complete. + + ```yaml + spec: + nodeSets: + - config: + xpack.security.transport.ssl.certificate_authorities: + - /usr/share/elasticsearch/config/other/ + xpack.security.transport.ssl.trust_restrictions.path: /usr/share/elasticsearch/config/trust-filter/trust.yml + podTemplate: + spec: + containers: + - name: elasticsearch + volumeMounts: + - mountPath: /usr/share/elasticsearch/config/other + name: ce-aws-cert + - mountPath: /usr/share/elasticsearch/config/trust-filter + name: quickstart-trust + volumes: + - name: ce-aws-cert + secret: + secretName: ce-aws-cert + - configMap: + name: quickstart-trust + name: quickstart-trust + ``` + + + +## Setup CCS/R [ec_setup_ccsr] + +Now that trust has been established, you can set up CCS/R from the ECK cluster to the Elasticsearch Service cluster or from the Elasticsearch Service cluster to the ECK cluster. + + +### ECK Cluster to Elasticsearch Service cluster [ec_eck_cluster_to_elasticsearch_service_cluster] + +Configure the ECK cluster [using certificate based authentication](ec-remote-cluster-self-managed.md). + + +### Elasticsearch Service cluster to ECK Cluster [ec_elasticsearch_service_cluster_to_eck_cluster] + +Follow the steps outlined in the [ECK documentation](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html#k8s_configure_the_remote_cluster_connection_through_the_elasticsearch_rest_api). diff --git a/deploy-manage/remote-clusters/ec-enable-ccs.md b/deploy-manage/remote-clusters/ec-enable-ccs.md new file mode 100644 index 000000000..8fd299ad2 --- /dev/null +++ b/deploy-manage/remote-clusters/ec-enable-ccs.md @@ -0,0 +1,73 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-enable-ccs.html +--- + +# Enable cross-cluster search and cross-cluster replication [ec-enable-ccs] + +[Cross-cluster search (CCS)](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html) allows you to configure multiple remote clusters across different locations and to enable federated search queries across all of the configured remote clusters. + +[Cross-cluster replication (CCR)](https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html) allows you to replicate indices across multiple remote clusters regardless of where they’re located. This provides tremendous benefit in scenarios of disaster recovery or data locality. + +These remote clusters could be: + +* Another {{es}} cluster of your {{ecloud}} organization across any region or cloud provider (AWS, GCP, Azure…​) +* An {{es}} cluster of another {{ecloud}} organization +* An {{es}} cluster in an {{ece}} installation +* Any other self-managed {{es}} cluster + + +## Prerequisites [ec-ccs-ccr-prerequisites] + +To use CCS or CCR, your deployments must meet the following criteria: + +* Local and remote clusters must be in compatible versions. Review the [{{es}} version compatibility](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-prerequisites-cert) table. + +The steps, information, and authentication method required to configure CCS and CCR can vary depending on where the clusters you want to use as remote are hosted. + +* Connect remotely to other clusters from your Elasticsearch Service deployments + + * [Access other deployments of the same Elasticsearch Service organization](ec-remote-cluster-same-ess.md) + * [Access deployments of a different Elasticsearch Service organization](ec-remote-cluster-other-ess.md) + * [Access deployments of an {{ECE}} environment](ec-remote-cluster-ece.md) + * [Access clusters of a self-managed environment](ec-remote-cluster-self-managed.md) + * [Access deployments of an ECK environment](ec-enable-ccs-for-eck.md) + +* Use clusters from your Elasticsearch Service deployments as remote + + * [From another deployment of your Elasticsearch Service organization](ec-remote-cluster-same-ess.md) + * [From a deployment of another Elasticsearch Service organization](ec-remote-cluster-other-ess.md) + * [From an ECE deployment](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/ece-enable-ccs.html) + * [From a self-managed cluster](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html) + + + +## Enable CCR and the Remote Clusters UI in Kibana [ec-enable-ccr] + +If your deployment was created before February 2021, CCR won’t be enabled by default and you won’t find the Remote Clusters UI in Kibana even though your deployment meets all the [criteria](#ec-ccs-ccr-prerequisites). + +To enable these features, go to the **Security** page of your deployment and under **Trust management** select **Enable CCR**. + +::::{note} +CCR is not supported for indices used by Enterprise Search. +:::: + + + +## Remote clusters and traffic filtering [ec-ccs-ccr-traffic-filtering] + +::::{note} +Traffic filtering isn’t supported for cross-cluster operations initiated from an {{ece}} environment to a remote {{ess}} deployment. +:::: + + +For remote clusters configured using TLS certificate authentication, [traffic filtering](../security/traffic-filtering.md) can be enabled to restrict access to deployments that are used as a local or remote cluster without any impact to cross-cluster search or cross-cluster replication. + +Traffic filtering for remote clusters supports 2 methods: + +* [Filtering by IP addresses and Classless Inter-Domain Routing (CIDR) masks](../security/ip-traffic-filtering.md) +* Filtering by Organization or Elasticsearch cluster ID with a Remote cluster type filter. You can configure this type of filter from the **Features** > **Traffic filters** page of your organization or using the [Elasticsearch Service API](https://www.elastic.co/docs/api/doc/cloud) and apply it from each deployment’s **Security** page. + +::::{note} +When setting up traffic filters for a remote connection to an {{ece}} environment, you also need to upload the region’s TLS certificate of the local cluster to the {{ece}} environment’s proxy. You can find that region’s TLS certificate in the Security page of any deployment of the environment initiating the remote connection. +:::: diff --git a/deploy-manage/remote-clusters/ec-migrate-ccs.md b/deploy-manage/remote-clusters/ec-migrate-ccs.md new file mode 100644 index 000000000..5eca7158f --- /dev/null +++ b/deploy-manage/remote-clusters/ec-migrate-ccs.md @@ -0,0 +1,275 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-migrate-ccs.html +--- + +# Migrate the cross-cluster search deployment template [ec-migrate-ccs] + +The cross-cluster search deployment template is now deprecated and has been removed from the Elasticsearch Service user console. You no longer need to use the dedicated cross-cluster template to search across deployments. Instead, you can now use any template to [configure remote clusters](ec-enable-ccs.md) and search across them. Existing deployments created using this template are not affected, but they are required to migrate to another template before upgrading to version 8.x. + +There are two different approaches to do this migration: + +* [Migrate using the API](#ec-migrate-ccs-deployment-using-api) +* [Migrate using a snapshot](#ec-migrate-ccs-deployment-using-snapshot) + + +## Use the API to migrate deployments that use the cross-cluster search template [ec-migrate-ccs-deployment-using-api] + +You can use a PUT request to update your deployment, changing both the deployment template ID and the instances required by the new template. + +1. First, choose the new template you want to use and obtain its ID. This template ID can be obtained from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) **Create Deployment** page by selecting **Equivalent API request** and inspecting the result for the field `deployment_template`. For example, we are going to use the "Storage optimized" deployment template, and in our GCP region the id is `gcp-storage-optimized-v5`. + + You can also find the template in the [list of templates available for each region](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html). + + :::{image} images/cloud-ec-migrate-deployment-template(2).png + :alt: Deployment Template ID + :class: screenshot + ::: + +2. Make a request to update your deployment with two changes: + + 1. Under `deployment_template`, set `id` to the value obtained in the previous step. + 2. Change the cluster topology to match the new template that your deployment will migrate to. + + +```sh +curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID -d "{ + "resources": { + "integrations_server": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-central1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.integrationsserver.n2.68x32x45.2", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "integrations_server": { + "version": "8.7.1" + } + }, + "ref_id": "main-integrations_server" + } + ], + "elasticsearch": [ + { + "region": "gcp-us-central1", + "settings": { + "dedicated_masters_threshold": 6 + }, + "plan": { + "cluster_topology": [ + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "hot" + } + }, + "instance_configuration_id": "gcp.es.datahot.n2.68x10x45", + "node_roles": [ + "master", + "ingest", + "transform", + "data_hot", + "remote_cluster_client", + "data_content" + ], + "id": "hot_content", + "size": { + "resource": "memory", + "value": 8192 + } + }, + { + "zone_count": 2, + "elasticsearch": { + "node_attributes": { + "data": "warm" + } + }, + "instance_configuration_id": "gcp.es.datawarm.n2.68x10x190", + "node_roles": [ + "data_warm", + "remote_cluster_client" + ], + "id": "warm", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "cold" + } + }, + "instance_configuration_id": "gcp.es.datacold.n2.68x10x190", + "node_roles": [ + "data_cold", + "remote_cluster_client" + ], + "id": "cold", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "elasticsearch": { + "node_attributes": { + "data": "frozen" + } + }, + "instance_configuration_id": "gcp.es.datafrozen.n2.68x10x95", + "node_roles": [ + "data_frozen" + ], + "id": "frozen", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 3, + "instance_configuration_id": "gcp.es.master.n2.68x32x45.2", + "node_roles": [ + "master", + "remote_cluster_client" + ], + "id": "master", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 2, + "instance_configuration_id": "gcp.es.coordinating.n2.68x16x45.2", + "node_roles": [ + "ingest", + "remote_cluster_client" + ], + "id": "coordinating", + "size": { + "resource": "memory", + "value": 0 + } + }, + { + "zone_count": 1, + "instance_configuration_id": "gcp.es.ml.n2.68x32x45", + "node_roles": [ + "ml", + "remote_cluster_client" + ], + "id": "ml", + "size": { + "resource": "memory", + "value": 0 + } + } + ], + "elasticsearch": { + "version": "8.7.1", + "enabled_built_in_plugins": [] + }, + "deployment_template": { + "id": "gcp-storage-optimized-v5" + } + }, + "ref_id": "main-elasticsearch" + } + ], + "enterprise_search": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-central1", + "plan": { + "cluster_topology": [ + { + "node_type": { + "connector": true, + "appserver": true, + "worker": true + }, + "instance_configuration_id": "gcp.enterprisesearch.n2.68x32x45", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 2048 + } + } + ], + "enterprise_search": { + "version": "8.7.1" + } + }, + "ref_id": "main-enterprise_search" + } + ], + "kibana": [ + { + "elasticsearch_cluster_ref_id": "main-elasticsearch", + "region": "gcp-us-central1", + "plan": { + "cluster_topology": [ + { + "instance_configuration_id": "gcp.kibana.n2.68x32x45", + "zone_count": 1, + "size": { + "resource": "memory", + "value": 1024 + } + } + ], + "kibana": { + "version": "8.7.1" + } + }, + "ref_id": "main-kibana" + } + ] + }, + "settings": { + "autoscaling_enabled": false + }, + "name": "My deployment", + "metadata": { + "system_owned": false + } +}" +``` + +`DEPLOYMENT_ID` +: The ID of your deployment, as shown in the Cloud UI or obtained through the API. + +`REGION` +: The region of your deployment, as shown in the Cloud UI or obtained through the API. + +Note that the `ref_id` and version numbers for your resources may not be the same as shown in this example. Make sure to use the ones your deployment has. + + +## Use a snapshot to migrate deployments that use the cross-cluster search deployment template [ec-migrate-ccs-deployment-using-snapshot] + +You can make this change in the user [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). The only drawback of this method is that it changes the URL used to access the {{es}} cluster and Kibana. + +1. From the deployment menu, open the **Snapshots** page and click **Take Snapshot now**. Wait for the snapshot to finish. +2. From the main **Deployments** page, click **Create deployment**. Next to **Settings** toggle on **Restore snapshot data**, and then select your deployment and the snapshot that you created. + + :::{image} ../../images/cloud-ec-create-from-snapshot-updated.png + :alt: Create a Deployment using a snapshot + :class: screenshot + ::: + + diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md new file mode 100644 index 000000000..0bf685680 --- /dev/null +++ b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md @@ -0,0 +1,337 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-ece.html +--- + +# Access deployments of an Elastic Cloud Enterprise environment [ec-remote-cluster-ece] + +This section explains how to configure a deployment to connect remotely to clusters belonging to an {{ECE}} (ECE) environment. + +## Allow the remote connection [ec_allow_the_remote_connection_3] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +#### Configuring trust with clusters of an {{ece}} environment [ec-trust-ece] + +A deployment can be configured to trust all or specific deployments in a remote ECE environment: + +1. Access the **Security** page of the deployment you want to use for cross-cluster operations. +2. Select **Remote Connections > Add trusted environment** and choose **{{ece}}**. Then click **Next**. +3. Select **Certificates** as authentication mechanism and click **Next**. +4. Enter the environment ID of the ECE environment. You can find it under Platform > Trust Management in your ECE administration UI. +5. Upload the Certificate Authority of the ECE environment. You can download it from Platform > Trust Management in your ECE administration UI. +6. Choose one of following options to configure the level of trust with the ECE environment: + + * All deployments - This deployment trusts all deployments in the ECE environment, including new deployments when they are created. + * Specific deployments - Specify which of the existing deployments you want to trust in the ECE environment. The full Elasticsearch cluster ID must be entered for each remote cluster. The Elasticsearch `Cluster ID` can be found in the deployment overview page under **Applications**. + +7. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +8. Select **Create trust** to complete the configuration. +9. Configure the corresponding deployments of the ECE environment to [trust this deployment](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/ece-enable-ccs.html). You will only be able to connect 2 deployments successfully when both of them trust each other. + +Note that the environment ID and cluster IDs must be entered fully and correctly. For security reasons, no verification of the IDs is possible. If cross-environment trust does not appear to be working, double-checking the IDs is a good place to start. + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +In order to trust a deployment with cluster id `cf659f7fe6164d9691b284ae36811be1` (NOTE: use the {{es}} cluster ID, not the deployment ID) in an ECE environment with environment ID `1053523734`, you need to update the trust settings with an additional direct trust relationship like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":true + } + ], + "direct": [ + { + "type" : "ECE", + "name" : "My ECE environment", + "scope_id" : "1053523734", + "certificates" : [ + { + "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----" + } + ], + "trust_all":false, + "trust_allowlist":[ + "cf659f7fe6164d9691b284ae36811be1" + ] + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +#### Prerequisites and limitations [ec_prerequisites_and_limitations_3] + +* The local and remote deployments must be on version 8.12 or later. +* API key authentication can’t be used in combination with traffic filters. +* Contrary to the certificate security model, the API key security model does not require that both local and remote clusters trust each other. + + +#### Create a cross-cluster API key on the remote deployment [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_3] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +#### Configure the local deployment [ec_configure_the_local_deployment] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +The steps to follow depend on whether the Certificate Authority (CA) of the remote ECE environment’s proxy or load balancing infrastructure is public or private. + +**The CA is public** + +::::{dropdown} +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Add a setting: + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key). + +:::: + + +**The CA is private** + +::::{dropdown} +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. Access the **Security** page of the deployment. +4. Select **Remote Connections > Add trusted environment** and choose **{{ece}}**. Then click **Next**. +5. Select **API keys** as authentication mechanism and click **Next**. +6. Add a the API key: + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + 3. Repeat these steps for each API key you want to add. For example, if you want to use several deployments of the remote environment for CCR or CCS. + +7. Add the CA certificate of the private proxy or load balancing infrastructure of the remote environment. To find this certificate: + + 1. In the remote {{ece}} environment, go to **Platform > Settings > TLS certificates**. + 2. Select **Show certificate chain** under **Proxy**. + 3. Click **Copy root certificate** and paste it into a new file. The root certificate is the last certificate shown in the chain. + 4. Save that file as `.crt`. It is now ready to be uploaded. + + :::{image} ../../images/cloud-remote-clusters-proxy-certificate.png + :alt: Certificate to copy from the chain + ::: + +8. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +9. Select **Create trust** to complete the configuration. +10. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key). + +:::: +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ec_connect_to_the_remote_cluster_3] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ec_using_kibana_3] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. + + :::{image} ../../images/cloud-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + + +### Using the Elasticsearch API [ec_using_the_elasticsearch_api_3] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the {{es}} deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elasticsearch Service RESTful API [ec_using_the_elasticsearch_service_restful_api_3] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same organization (for other scenarios,the Elasticsearch API should be used instead): +:::: + + +```sh +curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elasticsearch Service RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -X GET -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response will include just the remote clusters from the same organization in Elasticsearch Service. In order to obtain the whole list of remote clusters, use Kibana or the Elasticsearch API [Elasticsearch API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ec_configure_roles_and_users_3] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md new file mode 100644 index 000000000..6071029e5 --- /dev/null +++ b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md @@ -0,0 +1,273 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-other-ess.html +--- + +# Access deployments of another Elasticsearch Service organization [ec-remote-cluster-other-ess] + +This section explains how to configure a deployment to connect remotely to clusters belonging to a different Elasticsearch Service organization. + +## Allow the remote connection [ec_allow_the_remote_connection_2] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +#### Specify the deployments trusted to be used as remote clusters [ec-trust-other-organization] + +A deployment can be configured to trust all or specific deployments in another Elasticsearch Service [organizations](../users-roles/cloud-organization.md). To add cross-organization trust: + +1. From the **Security** menu, select **Remote Connections > Add trusted environment** and select **{{ecloud}}**. Then click **Next**. +2. Select **Certificates** as authentication mechanism and click **Next**. +3. Enter the ID of the deployment’s organization which you want to establish trust with. You can find that ID on the Organization page. It is usually made of 10 digits. +4. Choose one of following options to configure the level of trust with the other organization: + + * All deployments - This deployment trusts all deployments in the other organization, including new deployments when they are created. + * Specific deployments - Specify which of the existing deployments you want to trust in the other organization. The full Elasticsearch cluster ID must be entered for each remote cluster. The Elasticsearch `Cluster ID` can be found in the deployment overview page under **Applications**. + +5. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +6. Select **Create trust** to complete the configuration. +7. Repeat these steps from each of the deployments you want to use for CCS or CCR in both organizations. You will only be able to connect 2 deployments successfully when both of them trust each other. + +Note that the organization ID and cluster IDs must be entered fully and correctly. For security reasons, no verification of the IDs is possible. If cross-organization trust does not appear to be working, double-checking the IDs is a good place to start. + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +In order to trust a deployment with cluster id `cf659f7fe6164d9691b284ae36811be1` (NOTE: use the {{es}} cluster ID, not the deployment ID) in another organization with Organization ID `1053523734`, you need to update the trust settings with an additional account like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":true + }, + { + "account_id":"1053523734", + "trust_all":false, + "trust_allowlist":[ + "cf659f7fe6164d9691b284ae36811be1" + ] + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +#### Prerequisites and limitations [ec_prerequisites_and_limitations_2] + +* The local and remote deployments must be on version 8.12 or later. +* API key authentication can’t be used in combination with traffic filters. +* Contrary to the certificate security model, the API key security model does not require that both local and remote clusters trust each other. + + +#### Create a cross-cluster API key on the remote deployment [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_2] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +#### Add the cross-cluster API key to the keystore of the local deployment [ec_add_the_cross_cluster_api_key_to_the_keystore_of_the_local_deployment_2] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key). +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ec_connect_to_the_remote_cluster_2] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ec_using_kibana_2] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. + + :::{image} ../../images/cloud-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + + +### Using the Elasticsearch API [ec_using_the_elasticsearch_api_2] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the {{es}} deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elasticsearch Service RESTful API [ec_using_the_elasticsearch_service_restful_api_2] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same organization (for other scenarios,the Elasticsearch API should be used instead): +:::: + + +```sh +curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elasticsearch Service RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -X GET -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response will include just the remote clusters from the same organization in Elasticsearch Service. In order to obtain the whole list of remote clusters, use Kibana or the Elasticsearch API [Elasticsearch API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ec_configure_roles_and_users_2] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md new file mode 100644 index 000000000..c2490808d --- /dev/null +++ b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md @@ -0,0 +1,310 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-same-ess.html +--- + +# Access other deployments of the same Elasticsearch Service organization [ec-remote-cluster-same-ess] + +This section explains how to configure a deployment to connect remotely to clusters belonging to the same Elasticsearch Service organization. + +## Allow the remote connection [ec_allow_the_remote_connection] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +#### Set the default trust with other clusters in the same Elasticsearch Service organization [ec_set_the_default_trust_with_other_clusters_in_the_same_elasticsearch_service_organization] + +By default, any deployment that you create trusts all other deployments in the same organization. You can change this behavior in the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) under **Features** > **Trust**, so that when a new deployment is created it does not automatically trust any other deployment. You can choose one of the following options: + +* Trust all my deployments - All of your organization’s deployments created while this option is selected already trust each other. If you keep this option, that includes any deployments you’ll create in the future. You can directly jump to [Connect to the remote cluster](https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-same-ess.html#ec_connect_to_the_remote_cluster) to finalize the CCS or CCR configuration. +* Trust no deployment - New deployments won’t trust any other deployment when they are created. You can instead configure trust individually for each of them in their security settings, as described in the next section. + +:::{image} ../../images/cloud-ec-account-trust-management.png +:alt: Trust management at the account Level +:class: screenshot +::: + +::::{note} +* The level of trust of existing deployments is not modified when you change this setting. You must instead update the trust settings individually for each deployment you wish to change. +* Deployments created before the Elasticsearch Service February 2021 release trust only themselves. You have to update the trust setting for each deployment that you want to either use as a remote cluster or configure to work with a remote cluster. + +:::: + + + +#### Specify the deployments trusted to be used as remote clusters [ec_specify_the_deployments_trusted_to_be_used_as_remote_clusters] + +If your organization’s deployments already trust each other by default, you can skip this section. If that’s not the case, follow these steps to configure which are the specific deployments that should be trusted. + +1. Go to the **Security** page of your deployment. +2. From the list of existing trust configurations, edit the one labeled as your organization. +3. Choose one of following options to configure the level of trust on each of your deployments: + + * Trust all deployments - This deployment trusts all other deployments in this environment, including new deployments when they are created. + * Trust specific deployments - Choose which of the existing deployments from your environment you want to trust. + * Trust no deployment - No deployment in this Elasticsearch Service environment is trusted. + + +::::{note} +When trusting specific deployments, the more restrictive [CCS](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) version policy is used (even if you only want to use [CCR](https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html)). To work around this restriction for CCR-only trust, it is necessary to use the API as described below. +:::: + + +1. Repeat these steps from each of the deployments you want to use for CCS or CCR. You will only be able to connect 2 deployments successfully when both of them trust each other. + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +The current trust settings can be found in the path `.resources.elasticsearch[0].info.settings.trust` when calling: + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID?show_settings=true +``` + +For example: + +```json +{ + "accounts": [ + { + "account_id": "ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all": true + } + ] +} +``` + +The `account_id` above represents the only account in an {{es}} environment, and therefore is the one used to update the trust level with deployments in the current {{es}} environment. For example, to update the trust level to trust only the deployment with cluster ID `cf659f7fe6164d9691b284ae36811be1` (NOTE: use the {{es}} cluster ID, not the deployment ID), the trust settings in the body would look like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":false, + "trust_allowlist":[ + "cf659f7fe6164d9691b284ae36811be1" + ] + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +#### Prerequisites and limitations [ec_prerequisites_and_limitations] + +* The local and remote deployments must be on version 8.12 or later. +* API key authentication can’t be used in combination with traffic filters. +* Contrary to the certificate security model, the API key security model does not require that both local and remote clusters trust each other. + + +#### Create a cross-cluster API key on the remote deployment [ec_create_a_cross_cluster_api_key_on_the_remote_deployment] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +#### Add the cross-cluster API key to the keystore of the local deployment [ec_add_the_cross_cluster_api_key_to_the_keystore_of_the_local_deployment] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key). +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ec_connect_to_the_remote_cluster] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ec_using_kibana] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. + + :::{image} ../../images/cloud-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + + +### Using the Elasticsearch API [ec_using_the_elasticsearch_api] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the {{es}} deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elasticsearch Service RESTful API [ec_using_the_elasticsearch_service_restful_api] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same organization (for other scenarios,the Elasticsearch API should be used instead): +:::: + + +```sh +curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elasticsearch Service RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -X GET -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response will include just the remote clusters from the same organization in Elasticsearch Service. In order to obtain the whole list of remote clusters, use Kibana or the Elasticsearch API [Elasticsearch API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ec_configure_roles_and_users] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md new file mode 100644 index 000000000..ebe78098e --- /dev/null +++ b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md @@ -0,0 +1,364 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-self-managed.html +--- + +# Access clusters of a self-managed environment [ec-remote-cluster-self-managed] + +This section explains how to configure a deployment to connect remotely to self-managed clusters. + +## Allow the remote connection [ec_allow_the_remote_connection_4] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +#### Specify the deployments trusted to be used as remote clusters [ec-trust-self-managed] + +A deployment can be configured to trust all or specific deployments in any environment: + +1. From the **Security** menu, select **Remote Connections > Add trusted environment** and choose **Self-managed**, then click **Next**. +2. Select **Certificates** as authentication mechanism and click **Next**. +3. Upload the public certificate for the Certificate Authority of the self-managed environment (the one used to sign all the cluster certificates). The certificate needs to be in PEM format and should not contain the private key. If you only have the key in p12 format, then you can create the necessary file like this: `openssl pkcs12 -in elastic-stack-ca.p12 -out newfile.crt.pem -clcerts -nokeys` +4. Select the clusters to trust. There are two options here depending on the subject name of the certificates presented by the nodes in your self managed cluster: + + * Following the {{ecloud}} pattern. In {{ecloud}}, the certificates of all Elasticsearch nodes follow this convention: `CN = {{node_id}}.node.{{cluster_id}}.cluster.{{scope_id}}`. If you follow the same convention in your self-managed environment, then choose this option and you will be able to select all or specific clusters to trust. + * If your clusters don’t follow the previous convention for the certificates subject name of your nodes, you can still specify the node name of each of the nodes that should be trusted by this deployment. (Keep in mind that following this convention will simplify the management of this cluster since otherwise this configuration will need to be updated every time the topology of your self-managed cluster changes along with the trust restriction file. For this reason, it is recommended migrating your cluster certificates to follow the previous convention). + + ::::{note} + Trust management will not work properly in clusters without an `otherName` value specified, as is the case by default in an out-of-the-box [Elasticsearch installation](../deploy/self-managed/installing-elasticsearch.md). To have the Elasticsearch certutil generate new certificates with the `otherName` attribute, use the file input with the `cn` attribute as in the example below. + :::: + +5. . Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +6. Select **Create trust** to complete the configuration. +7. Configure the self-managed cluster to trust this deployment, so that both deployments are configured to trust each other: + + * Download the Certificate Authority used to sign the certificates of your deployment nodes (it can be found in the Security page of your deployment) + * Trust this CA either using the [setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html) `xpack.security.transport.ssl.certificate_authorities` in `elasticsearch.yml` or by [adding it to the trust store](../security/different-ca.md). + +8. Generate certificates with an `otherName` attribute using the Elasticsearch certutil. Create a file called `instances.yaml` with all the details of the nodes in your on-premise cluster like below. The `dns` and `ip` settings are optional, but `cn` is mandatory for use with the `trust_restrictions` path setting in the next step. Next, run `./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 -in instances.yaml` to create new certificates for all the nodes at once. You can then copy the resulting files into each node. + + ```yaml + instances: + - name: "node1" + dns: ["node1.mydomain.com"] + ip: ["192.168.1.1"] + cn: ["node1.node.1234567abcd.cluster.myscope.account"] + - name: "node2" + dns: ["node2.mydomain.com"] + ip: ["192.168.1.2"] + cn: ["node2.node.1234567abcd.cluster.myscope.account"] + ``` + +9. Restrict the trusted clusters to allow only the ones which your self-managed cluster should trust. + + * All the clusters in an {{ecloud}} region are signed by the same certificate authority. Therefore, adding this CA would make the self-managed cluster trust all the clusters in that region, including clusters from other organizations. This can be limited using the setting `xpack.security.transport.ssl.trust_restrictions.path` which points to a file that limits the certificates to trust based on their `otherName`-attribute. + * For example, the following file would trust: + + * two specific clusters with the cluster IDs `aaaabbbbaaaabbbb`<1> and `xxxxyyyyxxxxyyyy`<2> from an organization with organization ID `1053523734` + * <3> any cluster from an organization with organization ID `83988631` + * <4> The nodes from its own cluster (whose certificates follow a different convention: `CN = node1.example.com`, `CN = node2.example.com` and `CN = node3.example.com`) + + +``` + trust.subject_name: + - *.node.aaaabbbbaaaabbbb.cluster.1053523734.account + - *.node.xxxxyyyyxxxxyyyy.cluster.1053523734.account + - *.node.*.cluster.83988631.account + - node*.example.com +``` + +::::{tip} +Generate new node certificates for an entire cluster using the file input mode of the certutil. +:::: + + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +In order to trust a cluster whose nodes present certificates with the subject names: "CN = node1.example.com", "CN = node2.example.com" and "CN = node3.example.com" in a self-managed environment, you could update the trust settings with an additional direct trust relationship like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":true + } + ], + "direct": [ + { + "type" : "generic", + "name" : "My Self-managed environment", + "additional_node_names" : ["node1.example.com", "node2.example.com", "node3.example.com",], + "certificates" : [ + { + "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----" + } + ], + "trust_all":false + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +#### Prerequisites and limitations [ec_prerequisites_and_limitations_4] + +* The local and remote deployments must be on version 8.12 or later. +* API key authentication can’t be used in combination with traffic filters. +* Contrary to the certificate security model, the API key security model does not require that both local and remote clusters trust each other. + + +#### Create a cross-cluster API key on the remote deployment [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_4] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +#### Configure the local deployment [ec_configure_the_local_deployment_2] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s Elasticsearch HTTPS server, proxy or, load balancing infrastructure is public or private. + +**The CA is public** + +::::{dropdown} +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Add a setting: + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key). + +:::: + + +**The CA is private** + +::::{dropdown} +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments. + + On the deployments page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list. + +3. Access the **Security** page of the deployment. +4. Select **Remote Connections > Add trusted environment** and choose **Self-managed**. Then click **Next**. +5. Select **API keys** as authentication mechanism and click **Next**. +6. Add a the API key: + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + 3. Repeat these steps for each API key you want to add. For example, if you want to use several clusters of the remote environment for CCR or CCS. + +7. Add the CA certificate of the remote self-managed environment. +8. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +9. Select **Create trust** to complete the configuration. +10. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key). + +:::: +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ec_connect_to_the_remote_cluster_4] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ec_using_kibana_4] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. + + :::{image} ../../images/cloud-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + + +### Using the Elasticsearch API [ec_using_the_elasticsearch_api_4] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elasticsearch Service deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the {{es}} deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elasticsearch Service RESTful API [ec_using_the_elasticsearch_service_restful_api_4] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same organization (for other scenarios,the Elasticsearch API should be used instead): +:::: + + +```sh +curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elasticsearch Service RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -X GET -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response will include just the remote clusters from the same organization in Elasticsearch Service. In order to obtain the whole list of remote clusters, use Kibana or the Elasticsearch API [Elasticsearch API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ec_configure_roles_and_users_4] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment.md b/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment.md new file mode 100644 index 000000000..bf8228436 --- /dev/null +++ b/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-edit-remove-trusted-environment.html +--- + +# Edit or remove a trusted environment [ece-edit-remove-trusted-environment] + +From a deployment’s **Security** page, you can manage trusted environments that were created previously. This can happen when: + +* You no longer need a trusted environment and want to remove it. +* You want to refresh the certificate, or add or remove trusted deployments of an existing trusted environment relying on certificates as a security model. +* You want to remove or update the access level granted by a cross-cluster API key. + + +## Remove a trusted environment [ece_remove_a_trusted_environment] + +By removing a trusted environment, this deployment will no longer be able to establish remote connections using certificate trust to clusters of that environment. The remote environment will also no longer be able to connect to this deployment using certificate trust. + +::::{note} +With this method, you can only remove trusted environments relying exclusively on certificates. To remove remote connections that use API keys for authentication, refer to [Update the access level of a remote cluster connection relying on a cross-cluster API key](#ece-edit-remove-trusted-environment-api-key). +:::: + + +1. Go to the deployment’s **Security** page. +2. In the list of trusted environments, locate the one you want to remove. +3. Remove it using the corresponding `delete` icon. + + :::{image} ../../images/cloud-enterprise-delete-trust-environment.png + :alt: button for deleting a trusted environment + ::: + +4. In Kibana, go to **Stack Management** > **Remote Clusters**. +5. In the list of existing remote clusters, delete the ones corresponding to the trusted environment you removed earlier. + + +## Update a certificate-based trusted environment [ece_update_a_certificate_based_trusted_environment] + +1. Go to the deployment’s **Security** page. +2. In the list of trusted environments, locate the one you want to edit. +3. Open its details by selecting the `Edit` icon. + + :::{image} ../../images/cloud-enterprise-edit-trust-environment.png + :alt: button for editing a trusted environment + ::: + +4. Edit the trust configuration for that environment: + + * From the **Trust level** tab, you can add or remove trusted deployments. + * From the **Environment settings** tab, you can manage the certificates and the label of the environment. + +5. Save your changes. + + +## Change a cross-cluster API key used for a remote connection [ece-edit-remove-trusted-environment-api-key] + +This section describes the steps to change the API key used for an existing remote connection. For example, if the previous key expired and you need to rotate it with a new one. + +::::{note} +If you need to update the permissions granted by a cross-cluster API key for a remote connection, you only need to update the privileges granted by the API key directly in Kibana. +:::: + + +1. On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key with the appropriate permissions. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +2. Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next steps. +3. Go to the **Security** page of the local deployment and locate the **Remote connections** section. +4. Locate the API key currently used for connecting to the remote cluster, copy its current alias, and delete it. +5. Add the new API key by selecting **Add an API key**. + + * For the **Setting name**, enter the same alias that was used for the previous key. + + ::::{note} + If you use a different alias, you also need to re-create the remote cluster in Kibana with a **Name** that matches the new alias. + :::: + + * For the **Secret**, paste the encoded cross-cluster API key. + + 1. Click **Add** to save the API key to the keystore. + +6. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: diff --git a/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md b/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md new file mode 100644 index 000000000..21806f3a4 --- /dev/null +++ b/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md @@ -0,0 +1,88 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-enable-ccs-for-eck.html +--- + +# Enabling CCS/R between Elastic Cloud Enterprise and ECK [ece-enable-ccs-for-eck] + +These steps describe how to configure remote clusters between an {{es}} cluster in Elastic Cloud Enterprise and an {{es}} cluster running within [Elastic Cloud on Kubernetes (ECK)](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-overview.html). Once that’s done, you’ll be able to [run CCS queries from {{es}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html) or [set up CCR](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-getting-started.html). + + +## Establish trust between two clusters [ece_establish_trust_between_two_clusters] + +The first step is to establish trust between the two clusters. + + +### Establish trust in the Elastic Cloud Enterprise cluster [ece_establish_trust_in_the_elastic_cloud_enterprise_cluster] + +1. Save the ECK CA certificate to a file. For a cluster named `quickstart`, run: + + ```sh + kubectl get secret quickstart-es-transport-certs-public -o go-template='{{index .data "ca.crt" | base64decode}}' > eck.ca.crt + ``` + + +1. Update the trust settings for the Elastic Cloud Enterprise deployment. Follow the steps provided in [Access clusters of a self-managed environment](ece-remote-cluster-self-managed.md), and specifically the first three steps in **Specify the deployments trusted to be used as remote clusters** using TLS certificate as security model. + + * Use the certificate file saved in the first step. + * Select the {{ecloud}} pattern and enter `default.es.local` for the `Scope ID`. + +2. Select `Save` and then download the CA Certificate and `trust.yml` file. These files can also be retrieved in the `Security` page of the deployment. You will use these files in the next set of steps. + + +### Establish trust in the ECK cluster [ece_establish_trust_in_the_eck_cluster] + +1. Upload the Elastic Cloud Enterprise certificate (that you downloaded in the last step of the previous section) as a Kubernetes secret. + + ```sh + kubectl create secret generic ce-aws-cert --from-file= + ``` + +2. Upload the `trust.yml` file (that you downloaded in the last step of the previous section) as a Kubernetes config map. + + ```sh + kubectl create configmap quickstart-trust --from-file= + ``` + +3. Edit the {{es}} kubernetes resource to ensure the following sections are included. This assumes the {{es}} deployment is named `quickstart`. Make sure to replace the `CA-Certificate-Filename` placeholder with the correct value. Note that these configuration changes are required for all `nodeSets`. Applying this change requires all pods in all `nodeSets` to be deleted and recreated, which might take quite a while to complete. + + ```yaml + spec: + nodeSets: + - config: + xpack.security.transport.ssl.certificate_authorities: + - /usr/share/elasticsearch/config/other/ + xpack.security.transport.ssl.trust_restrictions.path: /usr/share/elasticsearch/config/trust-filter/trust.yml + podTemplate: + spec: + containers: + - name: elasticsearch + volumeMounts: + - mountPath: /usr/share/elasticsearch/config/other + name: ce-aws-cert + - mountPath: /usr/share/elasticsearch/config/trust-filter + name: quickstart-trust + volumes: + - name: ce-aws-cert + secret: + secretName: ce-aws-cert + - configMap: + name: quickstart-trust + name: quickstart-trust + ``` + + + +## Setup CCS/R [ece_setup_ccsr] + +Now that trust has been established, you can set up CCS/R from the ECK cluster to the Elastic Cloud Enterprise cluster or from the Elastic Cloud Enterprise cluster to the ECK cluster. + + +### ECK Cluster to Elastic Cloud Enterprise cluster [ece_eck_cluster_to_elastic_cloud_enterprise_cluster] + +Configure the ECK cluster [using certificate based authentication](ece-remote-cluster-self-managed.md). + + +### Elastic Cloud Enterprise cluster to ECK Cluster [ece_elastic_cloud_enterprise_cluster_to_eck_cluster] + +Follow the steps outlined in the [ECK documentation](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html#k8s_configure_the_remote_cluster_connection_through_the_elasticsearch_rest_api). diff --git a/deploy-manage/remote-clusters/ece-enable-ccs.md b/deploy-manage/remote-clusters/ece-enable-ccs.md new file mode 100644 index 000000000..05c64717a --- /dev/null +++ b/deploy-manage/remote-clusters/ece-enable-ccs.md @@ -0,0 +1,78 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-enable-ccs.html +--- + +# Enable cross-cluster search and cross-cluster replication [ece-enable-ccs] + +[Cross-cluster search (CCS)](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html) allows you to configure multiple remote clusters across different locations and to enable federated search queries across all of the configured remote clusters. + +[Cross-cluster replication (CCR)](https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html) allows you to replicate indices across multiple remote clusters regardless of where they’re located. This provides tremendous benefit in scenarios of disaster recovery or data locality. + +These remote clusters could be: + +* Another {{es}} cluster of your ECE installation +* An {{es}} cluster in a remote ECE installation +* An {{es}} cluster hosted on {ecloud} +* Any other self-managed {{es}} cluster + + +## Prerequisites [ece-ccs-ccr-prerequisites] + +To use CCS or CCR, your environment must meet the following criteria: + +* Local and remote clusters must be in compatible versions. Review the [{{es}} version compatibility](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-prerequisites-cert) table. + + * System deployments cannot be used as remote clusters or have remote clusters. + +* Proxies must answer TCP requests on the port 9400. Check the [prerequisites for the ports that must permit outbound or inbound traffic](../deploy/cloud-enterprise/ece-networking-prereq.md). +* Load balancers must pass-through TCP requests on port 9400. Check the [configuration details](../deploy/cloud-enterprise/ece-load-balancers.md). + +The steps, information, and authentication method required to configure CCS and CCR can vary depending on where the clusters you want to use as remote are hosted. + +* Connect remotely to other clusters from your Elastic Cloud Enterprise deployments + + * [Access other deployments of the same Elastic Cloud Enterprise environment](ece-remote-cluster-same-ece.md) + * [Access deployments of a different Elastic Cloud Enterprise environment](ece-remote-cluster-other-ece.md) + * [Access deployments of an {{ess}} environment](ece-remote-cluster-ece-ess.md) + * [Access clusters of a self-managed environment](ece-remote-cluster-self-managed.md) + * [Access deployments of an ECK environment](ece-enable-ccs-for-eck.md) + +* Use clusters from your Elastic Cloud Enterprise deployments as remote + + * [From another deployment of the same Elastic Cloud Enterprise environment](ece-remote-cluster-same-ece.md) + * [From a deployment of another Elastic Cloud Enterprise environment](ece-remote-cluster-other-ece.md) + * [From an {{ess}} deployment](https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-ece.html) + * [From a self-managed cluster](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html) + + + +## Enable CCR and the Remote Clusters UI in Kibana [ece-enable-ccr] + +If your deployment was created before ECE version `2.9.0`, CCR won’t be enabled by default and you won’t find the Remote Clusters UI in Kibana even though your deployment meets all the [criteria](#ece-ccs-ccr-prerequisites). + +To enable these features, go to the **Security** page of your deployment and under **Trust management** select **Enable CCR**. + +::::{note} +CCR is not supported for indices used by Enterprise Search. +:::: + + + +## Remote clusters and traffic filtering [ece-ccs-ccr-traffic-filtering] + +::::{note} +Traffic filtering isn’t supported for cross-cluster operations initiated from an {{ece}} environment to a remote {{ess}} deployment. +:::: + + +For remote clusters configured using TLS certificate authentication, [traffic filtering](../security/traffic-filtering.md) can be enabled to restrict access to deployments that are used as a local or remote cluster without any impact to cross-cluster search or cross-cluster replication. + +Traffic filtering for remote clusters supports 2 methods: + +* [Filtering by IP addresses and Classless Inter-Domain Routing (CIDR) masks](../security/ip-traffic-filtering.md) +* Filtering by Organization or Elasticsearch cluster ID with a Remote cluster type filter. You can configure this type of filter from the **Platform** > **Security** page of your environment or using the [Elastic Cloud Enterprise API](https://www.elastic.co/docs/api/doc/cloud-enterprise) and apply it from each deployment’s **Security** page. + +::::{note} +When setting up traffic filters for a remote connection to an {{ece}} environment, you also need to upload the region’s TLS certificate of the local cluster to the {{ece}} environment’s proxy. You can find that region’s TLS certificate in the Security page of any deployment of the environment initiating the remote connection. +:::: diff --git a/deploy-manage/remote-clusters/ece-migrate-ccs.md b/deploy-manage/remote-clusters/ece-migrate-ccs.md new file mode 100644 index 000000000..0107d1023 --- /dev/null +++ b/deploy-manage/remote-clusters/ece-migrate-ccs.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-migrate-ccs.html +--- + +# Migrate the cross-cluster search deployment template [ece-migrate-ccs] + +The cross-cluster search deployment template is now deprecated was removed in 3.0. You no longer need to use the dedicated cross-cluster template to search across deployments. Instead, you can now use any template to [configure remote clusters](ece-enable-ccs.md) and search across them. Existing deployments created using this template are not affected, but they are required to migrate to another template before upgrading to version 8.x. + +In order to migrate your existing CCS deployment using the CCS Deployment template to the new mechanism which supports CCR and cross-environment remote clusters you will need to migrate your data a new deployment [following these steps](#ece-migrate-ccs-deployment-using-snapshot). + + +## Use a snapshot to migrate deployments that use the cross-cluster search deployment template [ece-migrate-ccs-deployment-using-snapshot] + +You can make this change in the user Cloud UI. The only drawback of this method is that it changes the URL used to access the {{es}} cluster and Kibana. + +1. The first step for any approach is to remove the remote clusters from your deployment. You will need to add them back later. +2. From the deployment menu, open the **Snapshots** page and click **Take Snapshot now**. Wait for the snapshot to finish. +3. From the main **Deployments** page, click **Create deployment**. Next to **Settings** toggle on **Restore snapshot data**, and then select your deployment and the snapshot that you created. + + :::{image} ../../images/cloud-enterprise-ce-create-from-snapshot-updated.png + :alt: Create a Deployment using a snapshot + :class: screenshot + ::: + +4. Finally, [configure the remote clusters](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/ece-remote-cluster-other-ece.html). + diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md new file mode 100644 index 000000000..f83c69341 --- /dev/null +++ b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md @@ -0,0 +1,284 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-remote-cluster-ece-ess.html +--- + +# Access deployments of an Elasticsearch Service organization [ece-remote-cluster-ece-ess] + +This section explains how to configure a deployment to connect remotely to clusters belonging to an {{ess}} organization. + + +## Allow the remote connection [ece_allow_the_remote_connection_3] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +### Configuring trust with clusters in {{ecloud}} [ece-trust-ec] + +A deployment can be configured to trust all or specific deployments from an organization in [{{ecloud}}](https://www.elastic.co/guide/en/cloud/current): + +1. From the **Security** menu, select **Remote Connections > Add trusted environment** and select **{{ecloud}} Organization**. +2. Enter the organization ID (which can be found near the organization name). +3. Upload the Certificate Authorities of the deployments you want to trust. These can be downloaded from the Security page of each deployment (not only the current CA, but also future certificates in case they are expiring soon since they are periodically rotated). Deployments from the same region are signed by the same CA, so you will only need to upload one for each region. +4. Choose one of following options to configure the level of trust with the Organization: + + * All deployments - This deployment trusts all deployments in the organization in the regions whose certificate authorities have been uploaded, including new deployments when they are created. + * Specific deployments - Specify which of the existing deployments you want to trust from this organization. The full Elasticsearch cluster ID must be entered for each remote cluster. The Elasticsearch `Cluster ID` can be found in the deployment overview page under **Applications**. + +5. Configure the deployment in {{ecloud}} to [trust this deployment](https://www.elastic.co/guide/en/cloud/current/ec-remote-cluster-ece.html#ec-trust-ece), so that both deployments are configured to trust each other. + +Note that the organization ID and cluster IDs must be entered fully and correctly. For security reasons, no verification of the IDs is possible. If cross-environment trust does not appear to be working, double-checking the IDs is a good place to start. + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +In order to trust a deployment with cluster id `cf659f7fe6164d9691b284ae36811be1` (NOTE: use the {{es}} cluster ID, not the deployment ID) in an organization with organization ID `803289842`, you need to update the trust settings with an additional direct trust relationship like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":true + } + ], + "direct": [ + { + "type" : "ESS", + "name" : "My Organization", + "scope_id" : "803289842", + "certificates" : [ + { + "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----" + } + ], + "trust_all":false, + "trust_allowlist":[ + "cf659f7fe6164d9691b284ae36811be1" + ] + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +### Prerequisites and limitations [ece_prerequisites_and_limitations_3] + +* The local and remote deployments must be on version 8.12 or later. + + +### Create a cross-cluster API key on the remote deployment [ece_create_a_cross_cluster_api_key_on_the_remote_deployment_3] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +### Add the cross-cluster API key to the keystore of the local deployment [ece_add_the_cross_cluster_api_key_to_the_keystore_of_the_local_deployment_2] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key). +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ece_connect_to_the_remote_cluster_3] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ece_using_kibana_3] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. + + :::{image} ../../images/cloud-enterprise-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + +::::{note} +This configuration of remote clusters uses the [Proxy mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#proxy-mode) and it requires that the allocators can communicate via http with the proxies. +:::: + + + +### Using the Elasticsearch API [ece_using_the_elasticsearch_api_3] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9300` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9300", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the ECE deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elastic Cloud Enterprise RESTful API [ece_using_the_elastic_cloud_enterprise_restful_api_3] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same ECE environment (for other scenarios, the {{es}} API should be used instead): +:::: + + +```sh +curl -k -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elastic Cloud Enterprise RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response includes just the remote clusters from the same ECE environment. In order to obtain the whole list of remote clusters, use Kibana or the {{es}} API [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ece_configure_roles_and_users_3] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md new file mode 100644 index 000000000..09ff5af1c --- /dev/null +++ b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md @@ -0,0 +1,362 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-remote-cluster-other-ece.html +--- + +# Access deployments of another Elastic Cloud Enterprise environment [ece-remote-cluster-other-ece] + +This section explains how to configure a deployment to connect remotely to clusters belonging to a different Elastic Cloud Enterprise environment. + + +## Allow the remote connection [ece_allow_the_remote_connection_2] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +### Configuring platform level trust [ece-trust-remote-environments] + +In order to configure remote clusters in other ECE environments, you first need to establish a bi-directional trust relationship between both ECE environment’s platform: + +1. Download the certificate and copy the environment ID from your first ECE environment under **Platform** > **Trust Management** > **Trust parameters**. +2. Create a new trust relationship in the other ECE environment under **Platform** > **Trust Management** > **Trusted environments** using the certificate and environment ID from the previous step. +3. Download the certificate and copy the environment ID from your second ECE environment and create a new trust relationship with those in the first ECE environment. + +Now, deployments in those environments will be able to configure trust with deployments in the other environment. Trust must always be bi-directional (local cluster must trust remote cluster and vice versa) and it can be configured in each deployment’s security settings. + + +### Configuring trust with clusters of an {{ece}} environment [ece-trust-ece] + +1. Access the **Security** page of the deployment you want to use for cross-cluster operations. +2. Select **Remote Connections > Add trusted environment** and choose **{{ece}}**. Then click **Next**. +3. Select **Certificates** as authentication mechanism and click **Next**. +4. From the dropdown, select one of the environments configured in [Configuring platform level trust](#ece-trust-remote-environments). +5. Choose one of following options to configure the level of trust with the ECE environment: + + * All deployments - This deployment trusts all deployments in the ECE environment, including new deployments when they are created. + * Specific deployments - Specify which of the existing deployments you want to trust in the ECE environment. The full Elasticsearch cluster ID must be entered for each remote cluster. The Elasticsearch `Cluster ID` can be found in the deployment overview page under **Applications**. + +6. Select **Create trust** to complete the configuration. +7. Configure the corresponding deployments of the ECE environment to [trust this deployment](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/ece-enable-ccs.html). You will only be able to connect 2 deployments successfully when both of them trust each other. + +Note that the environment ID and cluster IDs must be entered fully and correctly. For security reasons, no verification of the IDs is possible. If cross-environment trust does not appear to be working, double-checking the IDs is a good place to start. + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +Establishing the trust between the two {{ece}} environments can be done using the [trust relationships API](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/Platform_-_Configuration_-_Trust_relationships.html). For example, the list of trusted environments can be obtained calling the [list trust relationships endpoint](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/get-trust-relationships.html): + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443//api/v1/regions/ece-region/platform/configuration/trust-relationships?include_certificate=false +``` + +For each remote ECE environment, it will return something like this: + +```json +{ + "id":"83a7b03f2a4343fe99f09bd27ca3d9ec", + "name":"ECE2", + "trust_by_default":false, + "account_ids":[ + "651598b101e54ccab1bfdcd8b6e3b8be" + ], + "local":false, + "last_modified":"2022-01-9T14:33:20.465Z" +} +``` + +In order to trust a deployment with cluster id `cf659f7fe6164d9691b284ae36811be1` (NOTE: use the {{es}} cluster ID, not the deployment ID) in this environment named `ECE2`, you need to update the trust settings with an external trust relationship like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":true + } + ], + "external":[ + { + "trust_relationship_id":"83a7b03f2a4343fe99f09bd27ca3d9ec", + "trust_all":false, + "trust_allowlist":[ + "cf659f7fe6164d9691b284ae36811be1" + ] + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +### Prerequisites and limitations [ece_prerequisites_and_limitations_2] + +* The local and remote deployments must be on version 8.12 or later. + + +### Create a cross-cluster API key on the remote deployment [ece_create_a_cross_cluster_api_key_on_the_remote_deployment_2] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +### Configure the local deployment [ece_configure_the_local_deployment] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +The steps to follow depend on whether the Certificate Authority (CA) of the remote ECE environment’s proxy or load balancing infrastructure is public or private. + +**The CA is public** + +::::{dropdown} +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Add a setting: + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key). + +:::: + + +**The CA is private** + +::::{dropdown} +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. Access the **Security** page of the deployment. +4. Select **Remote Connections > Add trusted environment** and choose **{{ece}}**. Then click **Next**. +5. Select **API keys** as authentication mechanism and click **Next**. +6. Add a the API key: + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + 3. Repeat these steps for each API key you want to add. For example, if you want to use several deployments of the remote environment for CCR or CCS. + +7. Add the CA certificate of the private proxy or load balancing infrastructure of the remote environment. To find this certificate: + + 1. In the remote {{ece}} environment, go to **Platform > Settings > TLS certificates**. + 2. Select **Show certificate chain** under **Proxy**. + 3. Click **Copy root certificate** and paste it into a new file. The root certificate is the last certificate shown in the chain. + 4. Save that file as `.crt`. It is now ready to be uploaded. + + :::{image} ../../images/cloud-enterprise-remote-clusters-proxy-certificate.png + :alt: Certificate to copy from the chain + ::: + +8. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +9. Select **Create trust** to complete the configuration. +10. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key). + +:::: +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ece_connect_to_the_remote_cluster_2] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ece_using_kibana_2] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. + + :::{image} ../../images/cloud-enterprise-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + +::::{note} +This configuration of remote clusters uses the [Proxy mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#proxy-mode) and it requires that the allocators can communicate via http with the proxies. +:::: + + + +### Using the Elasticsearch API [ece_using_the_elasticsearch_api_2] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9300` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9300", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the ECE deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elastic Cloud Enterprise RESTful API [ece_using_the_elastic_cloud_enterprise_restful_api_2] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same ECE environment (for other scenarios, the {{es}} API should be used instead): +:::: + + +```sh +curl -k -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elastic Cloud Enterprise RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response includes just the remote clusters from the same ECE environment. In order to obtain the whole list of remote clusters, use Kibana or the {{es}} API [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ece_configure_roles_and_users_2] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md new file mode 100644 index 000000000..66938e8b0 --- /dev/null +++ b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md @@ -0,0 +1,314 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-remote-cluster-same-ece.html +--- + +# Access other deployments of the same Elastic Cloud Enterprise environment [ece-remote-cluster-same-ece] + +This section explains how to configure a deployment to connect remotely to clusters belonging to the same Elastic Cloud Enterprise environment. + + +## Allow the remote connection [ece_allow_the_remote_connection] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +### Default trust with other clusters in the same ECE environment [ece_default_trust_with_other_clusters_in_the_same_ece_environment] + +By default, any deployment that you or your users create trusts all other deployments in the same Elastic Cloud Enterprise environment. You can change this behavior in the Cloud UI under **Platform** > **Trust Management**, so that when a new deployment is created it does not automatically trust any other deployment. You can choose one of the following options: + +* Trust all my deployments - All of your organization’s deployments created while this option is selected already trust each other. If you keep this option, that includes any deployments you’ll create in the future. You can directly jump to [Connect to the remote cluster](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}/ece-remote-cluster-same-ece.html#ece_connect_to_the_remote_cluster) to finalize the CCS or CCR configuration. +* Trust no deployment - New deployments won’t trust any other deployment when they are created. You can instead configure trust individually for each of them in their security settings, as described in the next section. + +:::{image} ../../images/cloud-enterprise-ce-environment-trust-management.png +:alt: Trust management at the environment Level +:class: screenshot +::: + +::::{note} +* The level of trust of existing deployments is not modified when you change this setting. You must instead update the trust settings individually for each deployment you wish to change. +* Deployments created before Elastic Cloud Enterprise version `2.9.0` trust only themselves. You have to update the trust setting for each deployment that you want to either use as a remote cluster or configure to work with a remote cluster. + +:::: + + + +### Specify the deployments trusted to be used as remote clusters [ece_specify_the_deployments_trusted_to_be_used_as_remote_clusters] + +If your organization’s deployments already trust each other by default, you can skip this section. If that’s not the case, follow these steps to configure which are the specific deployments that should be trusted. + +1. Go to the **Security** page of your deployment. +2. From the list of existing trust configurations, edit the one labeled as your organization. +3. Choose one of following options to configure the level of trust on each of your deployments: + + * Trust all deployments - This deployment trusts all other deployments in this environment, including new deployments when they are created. + * Trust specific deployments - Choose which of the existing deployments from your environment you want to trust. + * Trust no deployment - No deployment in this Elastic Cloud Enterprise environment is trusted. + + +::::{note} +When trusting specific deployments, the more restrictive [CCS](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) version policy is used (even if you only want to use [CCR](https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html)). To work around this restriction for CCR-only trust, it is necessary to use the API as described below. +:::: + + +1. Repeat these steps from each of the deployments you want to use for CCS or CCR. You will only be able to connect 2 deployments successfully when both of them trust each other. + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +The current trust settings can be found in the path `.resources.elasticsearch[0].info.settings.trust` when calling: + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID?show_settings=true +``` + +For example: + +```json +{ + "accounts": [ + { + "account_id": "ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all": true + } + ] +} +``` + +The `account_id` above represents the only account in an ECE environment, and therefore is the one used to update the trust level with deployments in the current ECE environment. For example, to update the trust level to trust only the deployment with cluster ID `cf659f7fe6164d9691b284ae36811be1` (NOTE: use the {{es}} cluster ID, not the deployment ID), the trust settings in the body would look like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":false, + "trust_allowlist":[ + "cf659f7fe6164d9691b284ae36811be1" + ] + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +### Prerequisites and limitations [ece_prerequisites_and_limitations] + +* The local and remote deployments must be on version 8.12 or later. + + +### Create a cross-cluster API key on the remote deployment [ece_create_a_cross_cluster_api_key_on_the_remote_deployment] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +### Add the cross-cluster API key to the keystore of the local deployment [ece_add_the_cross_cluster_api_key_to_the_keystore_of_the_local_deployment] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key). +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ece_connect_to_the_remote_cluster] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ece_using_kibana] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. + + :::{image} ../../images/cloud-enterprise-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + +::::{note} +This configuration of remote clusters uses the [Proxy mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#proxy-mode) and it requires that the allocators can communicate via http with the proxies. +:::: + + + +### Using the Elasticsearch API [ece_using_the_elasticsearch_api] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9300` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9300", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the ECE deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elastic Cloud Enterprise RESTful API [ece_using_the_elastic_cloud_enterprise_restful_api] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same ECE environment (for other scenarios, the {{es}} API should be used instead): +:::: + + +```sh +curl -k -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elastic Cloud Enterprise RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response includes just the remote clusters from the same ECE environment. In order to obtain the whole list of remote clusters, use Kibana or the {{es}} API [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ece_configure_roles_and_users] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md new file mode 100644 index 000000000..ca4d1e91a --- /dev/null +++ b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md @@ -0,0 +1,367 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-remote-cluster-self-managed.html +--- + +# Access clusters of a self-managed environment [ece-remote-cluster-self-managed] + +This section explains how to configure a deployment to connect remotely to self-managed clusters. + + +## Allow the remote connection [ece_allow_the_remote_connection_4] + +Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. + +API key +: For deployments based on {{stack}} version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. + +TLS certificate +: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. + +:::::::{tab-set} + +::::::{tab-item} TLS certificate +### Specify the deployments trusted to be used as remote clusters [ece-trust-self-managed] + +A deployment can be configured to trust all or specific deployments in any environment: + +1. From the **Security** menu, select **Remote Connections > Add trusted environment** and choose **Self-managed**, then click **Next**. +2. Select **Certificates** as authentication mechanism and click **Next**. +3. Upload the public certificate for the Certificate Authority of the self-managed environment (the one used to sign all the cluster certificates). The certificate needs to be in PEM format and should not contain the private key. If you only have the key in p12 format, then you can create the necessary file like this: `openssl pkcs12 -in elastic-stack-ca.p12 -out newfile.crt.pem -clcerts -nokeys` +4. Select the clusters to trust. There are two options here depending on the subject name of the certificates presented by the nodes in your self managed cluster: + + * Following the {{ecloud}} pattern. In {{ecloud}}, the certificates of all Elasticsearch nodes follow this convention: `CN = {{node_id}}.node.{{cluster_id}}.cluster.{{scope_id}}`. If you follow the same convention in your self-managed environment, then choose this option and you will be able to select all or specific clusters to trust. + * If your clusters don’t follow the previous convention for the certificates subject name of your nodes, you can still specify the node name of each of the nodes that should be trusted by this deployment. (Keep in mind that following this convention will simplify the management of this cluster since otherwise this configuration will need to be updated every time the topology of your self-managed cluster changes along with the trust restriction file. For this reason, it is recommended migrating your cluster certificates to follow the previous convention). + + ::::{note} + Trust management will not work properly in clusters without an `otherName` value specified, as is the case by default in an out-of-the-box [Elasticsearch installation](../deploy/self-managed/installing-elasticsearch.md). To have the Elasticsearch certutil generate new certificates with the `otherName` attribute, use the file input with the `cn` attribute as in the example below. + :::: + +5. . Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +6. Select **Create trust** to complete the configuration. +7. Configure the self-managed cluster to trust this deployment, so that both deployments are configured to trust each other: + + * Download the Certificate Authority used to sign the certificates of your deployment nodes (it can be found in the Security page of your deployment) + * Trust this CA either using the [setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html) `xpack.security.transport.ssl.certificate_authorities` in `elasticsearch.yml` or by [adding it to the trust store](../security/different-ca.md). + +8. Generate certificates with an `otherName` attribute using the Elasticsearch certutil. Create a file called `instances.yaml` with all the details of the nodes in your on-premise cluster like below. The `dns` and `ip` settings are optional, but `cn` is mandatory for use with the `trust_restrictions` path setting in the next step. Next, run `./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 -in instances.yaml` to create new certificates for all the nodes at once. You can then copy the resulting files into each node. + + ```yaml + instances: + - name: "node1" + dns: ["node1.mydomain.com"] + ip: ["192.168.1.1"] + cn: ["node1.node.1234567abcd.cluster.myscope.account"] + - name: "node2" + dns: ["node2.mydomain.com"] + ip: ["192.168.1.2"] + cn: ["node2.node.1234567abcd.cluster.myscope.account"] + ``` + +9. Restrict the trusted clusters to allow only the ones which your self-managed cluster should trust. + + * All the clusters in your Elastic Cloud Enterprise environment are signed by the same certificate authority. Therefore, adding this CA would make the self-managed cluster trust all your clusters in your ECE environment. This should be limited using the setting `xpack.security.transport.ssl.trust_restrictions.path` in `elasticsearch.yml`, which points to a file that limits the certificates to trust based on their `otherName`-attribute. + * For example, the following file would trust: + + ``` + trust.subject_name: + - *.node.aaaabbbbaaaabbbb.cluster.1053523734.account <1> + - *.node.xxxxyyyyxxxxyyyy.cluster.1053523734.account <1> + - *.node.*.cluster.83988631.account <2> + - node*.example.com <4> + ``` + + 1. two specific clusters with cluster ids `aaaabbbbaaaabbbb` and `xxxxyyyyxxxxyyyy` in an ECE environment with Environment ID `1053523734` + 2. any cluster from an ECE environment with Environment ID `83988631` + 3. the nodes from its own cluster (whose certificates follow a different convention: `CN = node1.example.com`, `CN = node2.example.com` and `CN = node3.example.com`) + +::::{tip} +Generate new node certificates for an entire cluster using the file input mode of the certutil. +:::: + + +::::{dropdown} **Using the API** +You can update a deployment using the appropriate trust settings for the {{es}} payload. + +In order to trust a cluster whose nodes present certificates with the subject names: "CN = node1.example.com", "CN = node2.example.com" and "CN = node3.example.com" in a self-managed environment, you could update the trust settings with an additional direct trust relationship like this: + +```json +{ + "trust":{ + "accounts":[ + { + "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", + "trust_all":true + } + ], + "direct": [ + { + "type" : "generic", + "name" : "My Self-managed environment", + "additional_node_names" : ["node1.example.com", "node2.example.com", "node3.example.com",], + "certificates" : [ + { + "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----" + } + ], + "trust_all":false + } + ] + } +} +``` + +:::: +:::::: + +::::::{tab-item} API key +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + + +### Prerequisites and limitations [ece_prerequisites_and_limitations_4] + +* The local and remote deployments must be on version 8.12 or later. + + +### Create a cross-cluster API key on the remote deployment [ece_create_a_cross_cluster_api_key_on_the_remote_deployment_4] + +* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) or [Kibana](../api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. +* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. + + +### Configure the local deployment [ece_configure_the_local_deployment_2] + +The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore. + +The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s Elasticsearch HTTPS server, proxy or, load balancing infrastructure is public or private. + +**The CA is public** + +::::{dropdown} +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. From the deployment menu, select **Security**. +4. Locate **Remote connections** and select **Add an API key**. + + 1. Add a setting: + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + +5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key). + +:::: + + +**The CA is private** + +::::{dropdown} +1. [Log into the Cloud UI](../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. On the deployments page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +3. Access the **Security** page of the deployment. +4. Select **Remote Connections > Add trusted environment** and choose **Self-managed**. Then click **Next**. +5. Select **API keys** as authentication mechanism and click **Next**. +6. Add a the API key: + + 1. Fill both fields. + + * For the **Setting name**, enter the the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores. + * For the **Secret**, paste the encoded cross-cluster API key. + + 2. Click **Add** to save the API key to the keystore. + 3. Repeat these steps for each API key you want to add. For example, if you want to use several clusters of the remote environment for CCR or CCS. + +7. Add the CA certificate of the remote self-managed environment. +8. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page. +9. Select **Create trust** to complete the configuration. +10. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment’s main page (named after your deployment’s name), locate the **Actions** menu, and select **Restart Elasticsearch**.
+ + ::::{note} + If the local deployment runs on version 8.13 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys. + :::: + + +If you later need to update the remote connection with different permissions, you can replace the API key as detailed in [Update the access level of a remote cluster connection relying on a cross-cluster API key](ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key). + +:::: +:::::: + +::::::: +You can now connect remotely to the trusted clusters. + + +## Connect to the remote cluster [ece_connect_to_the_remote_cluster_4] + +On the local cluster, add the remote cluster using Kibana or the {{es}} API. + + +### Using Kibana [ece_using_kibana_4] + +1. Open the {{kib}} main menu, and select **Stack Management > Data > Remote Clusters > Add a remote cluster**. +2. Enable **Manually enter proxy address and server name**. +3. Fill in the following fields: + + * **Name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + * **Proxy address**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote.
+ + ::::{tip} + If you’re using API keys as security model, change the port into `9443`. + :::: + + * **Server name**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. + + :::{image} ../../images/cloud-enterprise-ce-copy-remote-cluster-parameters.png + :alt: Remote Cluster Parameters in Deployment + :class: screenshot + ::: + + ::::{note} + If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-administering-endpoints.html). + :::: + +4. Click **Next**. +5. Click **Add remote cluster** (you have already established trust in a previous step). + +::::{note} +This configuration of remote clusters uses the [Proxy mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#proxy-mode) and it requires that the allocators can communicate via http with the proxies. +:::: + + + +### Using the Elasticsearch API [ece_using_the_elasticsearch_api_4] + +To configure a deployment as a remote cluster, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Configure the following fields: + +* `mode`: `proxy` +* `proxy_address`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9300` using a semicolon. + +::::{tip} +If you’re using API keys as security model, change the port into `9443`. +:::: + + +* `server_name`: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`. + +This is an example of the API call to `_cluster/settings`: + +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { + "mode":"proxy", + "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9300", + "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io" + } + } + } + } +} +``` + +:::::{dropdown} **Stack Version above 6.7.0 and below 7.6.0** +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model. +:::: + + +When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) with the proxy field. For each remote cluster you need to pass the following fields: + +* **Proxy**: This value can be found on the **Security** page of the deployment you want to use as a remote under the name `Proxy Address`. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields `metadata.endpoint` and `metadata.ports.transport_passthrough` using a semicolon. +* **Seeds**: This field is an array that must contain only one value, which is the `server name` that can be found on the **Security** page of the ECE deployment you want to use as a remote concatenated with `:1`. Also, using the API, this can be obtained from the {{es}} resource info, concatenating the fields `metadata.endpoint` and `1` with a semicolon. +* **Mode**: sniff (or empty, since sniff is the default value) + +This is an example of the API call to `_cluster/settings`: + +```json +{ + "persistent": { + "cluster": { + "remote": { + "my-remote-cluster-1": { + "seeds": [ + "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1" + ], + "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400" + } + } + } + } +} +``` + +::::: + + + +### Using the Elastic Cloud Enterprise RESTful API [ece_using_the_elastic_cloud_enterprise_restful_api_4] + +::::{note} +This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same ECE environment (for other scenarios, the {{es}} API should be used instead): +:::: + + +```sh +curl -k -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d ' +{ + "resources" : [ + { + "deployment_id": "$DEPLOYMENT_ID_REMOTE", + "elasticsearch_ref_id": "$REF_ID_REMOTE", + "alias": "alias-your-remote", + "skip_unavailable" : true + } + ] +}' +``` + +`DEPLOYMENT_ID_REMOTE` +: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API. + +`REF_ID_REMOTE` +: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API). + +Note the following when using the Elastic Cloud Enterprise RESTful API: + +1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_). +2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters). +3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters. + +The following API request retrieves the remote clusters configuration: + +```sh +curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters +``` + +::::{note} +The response includes just the remote clusters from the same ECE environment. In order to obtain the whole list of remote clusters, use Kibana or the {{es}} API [{{es}} API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) directly. +:::: + + + +## Configure roles and users [ece_configure_roles_and_users_4] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/eck-remote-clusters.md b/deploy-manage/remote-clusters/eck-remote-clusters.md new file mode 100644 index 000000000..f5c2f6c13 --- /dev/null +++ b/deploy-manage/remote-clusters/eck-remote-clusters.md @@ -0,0 +1,224 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html +--- + +# ECK remote clusters [k8s-remote-clusters] + +The [remote clusters module](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-remote-clusters.html) in Elasticsearch enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication and cross-cluster search. + +When using remote cluster connections with ECK, the setup process depends on where the remote cluster is deployed. + +## Connect from an Elasticsearch cluster running in the same Kubernetes cluster [k8s-remote-clusters-connect-internal] + +::::{note} +The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +To create a remote cluster connection to another Elasticsearch cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your Elasticsearch spec. + +### Security Models [k8s_security_models] + +ECK supports two different security models: the API key based security model, and the certificate security model. These two security models are described in the [Remote clusters](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#remote-clusters-security-models) section of the {{es}} documentation. + + +### Using the API key security model [k8s_using_the_api_key_security_model] + +To enable the API key security model you must first enable the remote cluster server on the remote {{es}} cluster: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: cluster-two + namespace: ns-two +spec: + version: 8.16.1 + remoteClusterServer: + enabled: true + nodeSets: + - name: default + count: 3 +``` + +::::{note} +Enabling the remote cluster server triggers a restart of the {{es}} cluster. +:::: + + +Once the remote cluster server is enabled and started on the remote cluster you can configure the Elasticsearch reference on the local cluster to include the desired permissions for cross-cluster search, and cross-cluster replication. + +Permissions have to be included under the `apiKey` field. The API model of the Elasticsearch resource is compatible with the [{{es}} Cross-Cluster API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html#security-api-create-cross-cluster-api-key-request-body) model. Fine-grained permissions can therefore be configured in both the `search` and `replication` fields: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: cluster-one + namespace: ns-one +spec: + nodeSets: + - count: 3 + name: default + remoteClusters: + - name: cluster-two + elasticsearchRef: + name: cluster-two + namespace: ns-two + apiKey: + access: + search: + names: + - kibana_sample_data_ecommerce <1> + replication: + names: + - kibana_sample_data_ecommerce <1> + version: 8.16.1 +``` + +1. This requires the sample data: [https://www.elastic.co/guide/en/kibana/current/get-started.html#gs-get-data-into-kibana](https://www.elastic.co/guide/en/kibana/current/get-started.html#gs-get-data-into-kibana) + + +You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/2.16/config/recipes/remoteclusters). + + +### Using the certificate security model [k8s_using_the_certificate_security_model] + +The following example describes how to configure `cluster-two` as a remote cluster in `cluster-one` using the certificate security model: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: cluster-one + namespace: ns-one +spec: + nodeSets: + - count: 3 + name: default + remoteClusters: + - name: cluster-two + elasticsearchRef: + name: cluster-two + namespace: ns-two <1> + version: 8.16.1 +``` + +1. The namespace declaration can be omitted if both clusters reside in the same namespace. + + + + +## Connect from an Elasticsearch cluster running outside the Kubernetes cluster [k8s-remote-clusters-connect-external] + +::::{note} +While it is technically possible to configure remote cluster connections using older versions of Elasticsearch, this guide only covers the setup for Elasticsearch 7.6 and later. The setup process is significantly simplified in Elasticsearch 7.6 due to improved support for the indirection of Kubernetes services. +:::: + + +You can configure a remote cluster connection to an ECK-managed Elasticsearch cluster from another cluster running outside the Kubernetes cluster as follows: + +1. Make sure that both clusters trust each other’s certificate authority. +2. Configure the remote cluster connection through the Elasticsearch REST API. + +Consider the following example: + +* `cluster-one` resides inside Kubernetes and is managed by ECK +* `cluster-two` is not hosted inside the same Kubernetes cluster as `cluster-one` and may not even be managed by ECK + +To configure `cluster-one` as a remote cluster in `cluster-two`: + +### Make sure both clusters trust each other’s certificate authority [k8s_make_sure_both_clusters_trust_each_others_certificate_authority] + +The certificate authority (CA) used by ECK to issue certificates for the Elasticsearch transport layer is stored in a secret named `-es-transport-certs-public`. Extract the certificate for `cluster-one` as follows: + +```sh +kubectl get secret cluster-one-es-transport-certs-public \ +-o go-template='{{index .data "ca.crt" | base64decode}}' > remote.ca.crt +``` + +You then need to configure the CA as one of the trusted CAs in `cluster-two`. If that cluster is hosted outside of Kubernetes, take the CA certificate that you have just extracted and add it to the list of CAs in [`xpack.security.transport.ssl.certificate_authorities`](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#_pem_encoded_files_3). + +::::{note} +Beware of copying the source Secret as-is into a different namespace. Check [Common Problems: Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. +:::: + + +::::{note} +CA certificates are automatically rotated after one year by default. You can [configure](../deploy/cloud-on-k8s/configure-eck.md) this period. Make sure to keep the copy of the certificates Secret up-to-date. +:::: + + +If `cluster-two` is also managed by an ECK instance, proceed as follows: + +1. Create a config map with the CA certificate you just extracted: + + ```sh + kubectl create configmap remote-certs --from-file=ca.crt=remote.ca.crt + ``` + +2. Use this config map to configure `cluster-one`'s CA as a trusted CA in `cluster-two`: + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: cluster-two + spec: + transport: + tls: + certificateAuthorities: + configMapName: remote-certs + nodeSets: + - count: 3 + name: default + version: 8.16.1 + ``` + +3. Repeat steps 1 and 2 to add the CA of `cluster-two` to `cluster-one` as well. + + +### Configure the remote cluster connection through the Elasticsearch REST API [k8s_configure_the_remote_cluster_connection_through_the_elasticsearch_rest_api] + +Expose the transport layer of `cluster-one`. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: cluster-one +spec: + transport: + service: + spec: + type: LoadBalancer <1> +``` + +1. On cloud providers which support external load balancers, setting the type field to LoadBalancer provisions a load balancer for your Service. Alternatively, expose the service through one of the Kubernetes Ingress controllers that support TCP services. + + +Finally, configure `cluster-one` as a remote cluster in `cluster-two` using the Elasticsearch REST API: + +```sh +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster-one": { + "mode": "proxy", <1> + "proxy_address": "${LOADBALANCER_IP}:9300" <2> + } + } + } + } +} +``` + +1. Use "proxy" mode as `cluster-two` will be connecting to `cluster-one` through the Kubernetes service abstraction. +2. Replace `${LOADBALANCER_IP}` with the IP address assigned to the `LoadBalancer` configured in the previous code sample. If you have configured a DNS entry for the service, you can use the DNS name instead of the IP address as well. + + + + diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md new file mode 100644 index 000000000..f04e5eff5 --- /dev/null +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -0,0 +1,402 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-api-key.html +--- + +# Add remote clusters using API key authentication [remote-clusters-api-key] + +API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. + +All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. + +On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. + +In this model, cross-cluster operations use [a dedicated server port](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote_cluster.port) (remote cluster interface) for communication between clusters. A remote cluster must enable this port for local clusters to connect. Configure Transport Layer Security (TLS) for this port to maximize security (as explained in [Establish trust with a remote cluster](#remote-clusters-security-api-key)). + +The local cluster must trust the remote cluster on the remote cluster interface. This means that the local cluster trusts the remote cluster’s certificate authority (CA) that signs the server certificate used by the remote cluster interface. When establishing a connection, all nodes from the local cluster that participate in cross-cluster communication verify certificates from nodes on the other side, based on the TLS trust configuration. + +To add a remote cluster using API key authentication: + +1. [Review the prerequisites](#remote-clusters-prerequisites-api-key) +2. [Establish trust with a remote cluster](#remote-clusters-security-api-key) +3. [Connect to a remote cluster](#remote-clusters-connect-api-key) +4. [Configure roles and users](#remote-clusters-privileges-api-key) + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + +## Prerequisites [remote-clusters-prerequisites-api-key] + +* The {{es}} security features need to be enabled on both clusters, on every node. Security is enabled by default. If it’s disabled, set `xpack.security.enabled` to `true` in `elasticsearch.yml`. Refer to [General security settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#general-security-settings). +* The nodes of the local and remote clusters must be on version 8.10 or later. +* The local and remote clusters must have an appropriate license. For more information, refer to [https://www.elastic.co/subscriptions](https://www.elastic.co/subscriptions). + + +## Establish trust with a remote cluster [remote-clusters-security-api-key] + +::::{note} +If a remote cluster is part of an {{ess}} deployment, it has a valid certificate by default. You can therefore skip steps related to certificates in these instructions. +:::: + + +### On the remote cluster [remote-clusters-security-api-key-remote-action] + +1. Enable the remote cluster server on every node of the remote cluster. In `elasticsearch.yml`: + + 1. Set [`remote_cluster_server.enabled`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote-cluster-network-settings) to `true`. + 2. Configure the bind and publish address for remote cluster server traffic, for example using [`remote_cluster.host`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote-cluster-network-settings). Without configuring the address, remote cluster traffic may be bound to the local interface, and remote clusters running on other machines can’t connect. + 3. Optionally, configure the remote server port using [`remote_cluster.port`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote_cluster.port) (defaults to `9443`). + +2. Next, generate a certificate authority (CA) and a server certificate/key pair. On one of the nodes of the remote cluster, from the directory where {{es}} has been installed: + + 1. Create a CA, if you don’t have a CA already: + + ```sh + ./bin/elasticsearch-certutil ca --pem --out=cross-cluster-ca.zip --pass CA_PASSWORD + ``` + + Replace `CA_PASSWORD` with the password you want to use for the CA. You can remove the `--pass` option and its argument if you are not deploying to a production environment. + + 2. Unzip the generated `cross-cluster-ca.zip` file. This compressed file contains the following content: + + ```txt + /ca + |_ ca.crt + |_ ca.key + ``` + + 3. Generate a certificate and private key pair for the nodes in the remote cluster: + + ```sh + ./bin/elasticsearch-certutil cert --out=cross-cluster.p12 --pass=CERT_PASSWORD --ca-cert=ca/ca.crt --ca-key=ca/ca.key --ca-pass=CA_PASSWORD --dns=example.com --ip=127.0.0.1 + ``` + + * Replace `CA_PASSWORD` with the CA password from the previous step. + * Replace `CERT_PASSWORD` with the password you want to use for the generated private key. + * Use the `--dns` option to specify the relevant DNS name for the certificate. You can specify it multiple times for multiple DNS. + * Use the `--ip` option to specify the relevant IP address for the certificate. You can specify it multiple times for multiple IP addresses. + + 4. If the remote cluster has multiple nodes, you can either: + + * create a single wildcard certificate for all nodes; + * or, create separate certificates for each node either manually or in batch with the [silent mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/certutil.html#certutil-silent). + +3. On every node of the remote cluster: + + 1. Copy the `cross-cluster.p12` file from the earlier step to the `config` directory. If you didn’t create a wildcard certificate, make sure you copy the correct node-specific p12 file. + 2. Add following configuration to `elasticsearch.yml`: + + ```yaml + xpack.security.remote_cluster_server.ssl.enabled: true + xpack.security.remote_cluster_server.ssl.keystore.path: cross-cluster.p12 + ``` + + 3. Add the SSL keystore password to the {{es}} keystore: + + ```sh + ./bin/elasticsearch-keystore add xpack.security.remote_cluster_server.ssl.keystore.secure_password + ``` + + When prompted, enter the `CERT_PASSWORD` from the earlier step. + +4. Restart the remote cluster. +5. On the remote cluster, generate a cross-cluster API key that provides access to the indices you want to use for {{ccs}} or {{ccr}}. You can use the [Create Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) API or [Kibana](../api-keys/elasticsearch-api-keys.md). +6. Copy the encoded key (`encoded` in the response) to a safe location. You will need it to connect to the remote cluster later. + + +### On the local cluster [remote-clusters-security-api-key-local-actions] + +1. On every node of the local cluster: + + 1. Copy the `ca.crt` file generated on the remote cluster earlier into the `config` directory, renaming the file `remote-cluster-ca.crt`. + 2. Add following configuration to `elasticsearch.yml`: + + ```yaml + xpack.security.remote_cluster_client.ssl.enabled: true + xpack.security.remote_cluster_client.ssl.certificate_authorities: [ "remote-cluster-ca.crt" ] + ``` + + 3. Add the cross-cluster API key, created on the remote cluster earlier, to the keystore: + + ```sh + ./bin/elasticsearch-keystore add cluster.remote.ALIAS.credentials + ``` + + Replace `ALIAS` with the same name that you will use to create the remote cluster entry later. When prompted, enter the encoded cross-cluster API key created on the remote cluster earlier. + +2. Restart the local cluster to load changes to the keystore and settings. + +**Note:** If you are configuring only the cross-cluster API key, you can call the [Nodes reload secure settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) API, instead of restarting the cluster. Configuring the `remote_cluster_client` settings in `elasticsearch.yml` still requires a restart. + + + +## Connect to a remote cluster [remote-clusters-connect-api-key] + +::::{note} +You must have the `manage` cluster privilege to connect remote clusters. +:::: + + +The local cluster uses the [remote cluster interface](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html) to establish communication with remote clusters. The coordinating nodes in the local cluster establish [long-lived](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#long-lived-connections) TCP connections with specific nodes in the remote cluster. {{es}} requires these connections to remain open, even if the connections are idle for an extended period. + +To add a remote cluster from Stack Management in {{kib}}: + +1. Select **Remote Clusters** from the side navigation. +2. Enter a name (*cluster alias*) for the remote cluster. +3. Specify the {{es}} endpoint URL, or the IP address or host name of the remote cluster followed by the remote cluster port (defaults to `9443`). For example, `cluster.es.eastus2.staging.azure.foundit.no:9443` or `192.168.1.1:9443`. + +Alternatively, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) to add a remote cluster. You can also use this API to dynamically configure remote clusters for *every* node in the local cluster. To configure remote clusters on individual nodes in the local cluster, define static settings in `elasticsearch.yml` for each node. + +The following request adds a remote cluster with an alias of `cluster_one`. This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + +```console +PUT /_cluster/settings +{ + "persistent" : { + "cluster" : { + "remote" : { + "cluster_one" : { <1> + "seeds" : [ + "127.0.0.1:9443" <2> + ] + } + } + } + } +} +``` + +1. The cluster alias of this remote cluster is `cluster_one`. +2. Specifies the hostname and remote cluster port of a seed node in the remote cluster. + + +You can use the [remote cluster info API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) to verify that the local cluster is successfully connected to the remote cluster: + +```console +GET /_remote/info +``` + +The API response indicates that the local cluster is connected to the remote cluster with the cluster alias `cluster_one`: + +```console-result +{ + "cluster_one" : { + "seeds" : [ + "127.0.0.1:9443" + ], + "connected" : true, + "num_nodes_connected" : 1, <1> + "max_connections_per_cluster" : 3, + "initial_connect_timeout" : "30s", + "skip_unavailable" : true, <2> + "cluster_credentials": "::es_redacted::", <3> + "mode" : "sniff" + } +} +``` + +1. The number of nodes in the remote cluster the local cluster is connected to. +2. Indicates whether to skip the remote cluster if searched through {{ccs}} but no nodes are available. +3. If present, indicates the remote cluster has connected using API key authentication. + + +### Dynamically configure remote clusters [_dynamically_configure_remote_clusters] + +Use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) to dynamically configure remote settings on every node in the cluster. The following request adds three remote clusters: `cluster_one`, `cluster_two`, and `cluster_three`. + +The `seeds` parameter specifies the hostname and [remote cluster port](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html) (default `9443`) of a seed node in the remote cluster. + +The `mode` parameter determines the configured connection mode, which defaults to [`sniff`](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode). Because `cluster_one` doesn’t specify a `mode`, it uses the default. Both `cluster_two` and `cluster_three` explicitly use different modes. + +```console +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_one": { + "seeds": [ + "127.0.0.1:9443" + ] + }, + "cluster_two": { + "mode": "sniff", + "seeds": [ + "127.0.0.1:9444" + ], + "transport.compress": true, + "skip_unavailable": true + }, + "cluster_three": { + "mode": "proxy", + "proxy_address": "127.0.0.1:9445" + } + } + } + } +} +``` + +You can dynamically update settings for a remote cluster after the initial configuration. The following request updates the compression settings for `cluster_two`, and the compression and ping schedule settings for `cluster_three`. + +::::{note} +When the compression or ping schedule settings change, all existing node connections must close and re-open, which can cause in-flight requests to fail. +:::: + + +```console +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_two": { + "transport.compress": false + }, + "cluster_three": { + "transport.compress": true, + "transport.ping_schedule": "60s" + } + } + } + } +} +``` + +You can delete a remote cluster from the cluster settings by passing `null` values for each remote cluster setting. The following request removes `cluster_two` from the cluster settings, leaving `cluster_one` and `cluster_three` intact: + +```console +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_two": { + "mode": null, + "seeds": null, + "skip_unavailable": null, + "transport.compress": null + } + } + } + } +} +``` + + +### Statically configure remote clusters [_statically_configure_remote_clusters] + +If you specify settings in `elasticsearch.yml`, only the nodes with those settings can connect to the remote cluster and serve remote cluster requests. + +::::{note} +Remote cluster settings that are specified using the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) take precedence over settings that you specify in `elasticsearch.yml` for individual nodes. +:::: + + +In the following example, `cluster_one`, `cluster_two`, and `cluster_three` are arbitrary cluster aliases representing the connection to each cluster. These names are subsequently used to distinguish between local and remote indices. + +```yaml +cluster: + remote: + cluster_one: + seeds: 127.0.0.1:9443 + cluster_two: + mode: sniff + seeds: 127.0.0.1:9444 + transport.compress: true <1> + skip_unavailable: true <2> + cluster_three: + mode: proxy + proxy_address: 127.0.0.1:9445 <3> +``` + +1. Compression is explicitly enabled for requests to `cluster_two`. +2. Disconnected remote clusters are optional for `cluster_two`. +3. The address for the proxy endpoint used to connect to `cluster_three`. + + + + +## Configure roles and users [remote-clusters-privileges-api-key] + +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) or [remote cluster privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-cluster-priv) on the local cluster. + +You can manage users and roles from Stack Management in {{kib}} by selecting **Security > Roles** from the side navigation. You can also use the [role management APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html#security-role-apis) to add, update, remove, and retrieve roles dynamically. + +The following examples use the [Create or update roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html) API. You must have at least the `manage_security` cluster privilege to use this API. + +::::{note} +The cross-cluster API key used by the local cluster to connect the remote cluster must have sufficient privileges to cover all remote indices privileges required by individual users. +:::: + + +### Configure privileges for {{ccr}} [_configure_privileges_for_ccr] + +Assuming the remote cluster is connected under the name of `my_remote_cluster`, the following request creates a role called `remote-replication` on the local cluster that allows replicating the remote `leader-index` index: + +```console +POST /_security/role/remote-replication +{ + "cluster": [ + "manage_ccr" + ], + "remote_indices": [ + { + "clusters": [ "my_remote_cluster" ], + "names": [ + "leader-index" + ], + "privileges": [ + "cross_cluster_replication" + ] + } + ] +} +``` + +After creating the local `remote-replication` role, use the [Create or update users](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html) API to create a user on the local cluster cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: + +```console +POST /_security/user/cross-cluster-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-replication" ] +} +``` + +Note that you only need to create this user on the local cluster. + + +### Configure privileges for {{ccs}} [_configure_privileges_for_ccs] + +Assuming the remote cluster is connected under the name of `my_remote_cluster`, the following request creates a `remote-search` role on the local cluster that allows searching the remote `target-index` index: + +```console +POST /_security/role/remote-search +{ + "remote_indices": [ + { + "clusters": [ "my_remote_cluster" ], + "names": [ + "target-index" + ], + "privileges": [ + "read", + "read_cross_cluster", + "view_index_metadata" + ] + } + ] +} +``` + +After creating the `remote-search` role, use the [Create or update users](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html) API to create a user on the local cluster and assign the `remote-search` role. For example, the following request assigns the `remote-search` role to a user named `cross-search-user`: + +```console +POST /_security/user/cross-search-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-search" ] +} +``` + +Note that you only need to create this user on the local cluster. diff --git a/deploy-manage/remote-clusters/remote-clusters-cert.md b/deploy-manage/remote-clusters/remote-clusters-cert.md new file mode 100644 index 000000000..66f9c5d0d --- /dev/null +++ b/deploy-manage/remote-clusters/remote-clusters-cert.md @@ -0,0 +1,508 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html +--- + +# Add remote clusters using TLS certificate authentication [remote-clusters-cert] + +::::{admonition} Deprecated in 9.0.0. +:class: warning + +Certificate based authentication is deprecated. Configure [API key authentication](remote-clusters-api-key.md) instead or follow a guide on how to [migrate remote clusters from certificate to API key authentication](remote-clusters-migrate.md). +:::: + + +To add a remote cluster using TLS certificate authentication: + +1. [Review the prerequisites](#remote-clusters-prerequisites-cert) +2. [Establish trust with a remote cluster](#remote-clusters-security-cert) +3. [Connect to a remote cluster](#remote-clusters-connect-cert) +4. [Configure roles and users for remote clusters](#remote-clusters-privileges-cert) + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + +## Prerequisites [remote-clusters-prerequisites-cert] + +1. The {{es}} security features need to be enabled on both clusters, on every node. Security is enabled by default. If it’s disabled, set `xpack.security.enabled` to `true` in `elasticsearch.yml`. Refer to [General security settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#general-security-settings). +2. The local and remote clusters versions must be compatible. + + * Any node can communicate with another node on the same major version. For example, 7.0 can talk to any 7.x node. + * Only nodes on the last minor version of a certain major version can communicate with nodes on the following major version. In the 6.x series, 6.8 can communicate with any 7.x node, while 6.7 can only communicate with 7.0. + * Version compatibility is symmetric, meaning that if 6.7 can communicate with 7.0, 7.0 can also communicate with 6.7. The following table depicts version compatibility between local and remote nodes. + + :::::{dropdown} Version compatibility table + | | | + | --- | --- | + | | Local cluster | + | Remote cluster | 5.0–5.5 | 5.6 | 6.0–6.6 | 6.7 | 6.8 | 7.0 | 7.1–7.16 | 7.17 | 8.0–9.0 | + | 5.0–5.5 | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 5.6 | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 6.0–6.6 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 6.7 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 6.8 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 7.0 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 7.1–7.16 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | + | 7.17 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | + | 8.0–9.0 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | + + ::::{note} + This documentation is for {{es}} version 9.0.0-beta1, which is not yet released. The above compatibility table applies if both clusters are running a released version of {{es}}, or if one of the clusters is running a released version and the other is running a pre-release build with a later build date. A cluster running a pre-release build of {{es}} can also communicate with remote clusters running the same pre-release build. Running a mix of pre-release builds is unsupported and typically will not work, even if the builds have the same version number. + :::: + + + ::::: + + + ::::{important} + Elastic only supports {{ccs}} on a subset of these configurations. See [Supported {{ccs}} configurations](../../solutions/search/cross-cluster-search.md#ccs-supported-configurations). + :::: + + + +## Establish trust with a remote cluster [remote-clusters-security-cert] + +To use {{ccr}} or {{ccs}} safely with remote clusters, enable security on all connected clusters and configure Transport Layer Security (TLS) on every node. Configuring TLS security on the transport interface is minimally required for remote clusters. For additional security, configure TLS on the [HTTP interface](../security/secure-http-communications.md) as well. + +All connected clusters must trust one another and be mutually authenticated with TLS on the transport interface. This means that the local cluster trusts the certificate authority (CA) of the remote cluster, and the remote cluster trusts the CA of the local cluster. When establishing a connection, all nodes will verify certificates from nodes on the other side. This mutual trust is required to securely connect a remote cluster, because all connected nodes effectively form a single security domain. + +User authentication is performed on the local cluster and the user and user’s roles names are passed to the remote clusters. A remote cluster checks the user’s role names against its local role definitions to determine which indices the user is allowed to access. + +Before using {{ccr}} or {{ccs}} with secured {{es}} clusters, complete the following configuration task: + +1. Configure Transport Layer Security (TLS) on every node to encrypt internode traffic and authenticate nodes in the local cluster with nodes in all remote clusters. Refer to [set up basic security for the {{stack}}](../security/secure-cluster-communications.md) for the required steps to configure security. + + ::::{note} + This procedure uses the same CA to generate certificates for all nodes. Alternatively, you can add the certificates from the local cluster as a trusted CA in each remote cluster. You must also add the certificates from remote clusters as a trusted CA on the local cluster. Using the same CA to generate certificates for all nodes simplifies this task. + :::: + + + +## Connect to a remote cluster [remote-clusters-connect-cert] + +::::{note} +You must have the `manage` cluster privilege to connect remote clusters. +:::: + + +The local cluster uses the [transport interface](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html) to establish communication with remote clusters. The coordinating nodes in the local cluster establish [long-lived](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#long-lived-connections) TCP connections with specific nodes in the remote cluster. {{es}} requires these connections to remain open, even if the connections are idle for an extended period. + +To add a remote cluster from Stack Management in {{kib}}: + +1. Select **Remote Clusters** from the side navigation. +2. Enter a name (*cluster alias*) for the remote cluster. +3. Specify the {{es}} endpoint URL, or the IP address or host name of the remote cluster followed by the transport port (defaults to `9300`). For example, `cluster.es.eastus2.staging.azure.foundit.no:9300` or `192.168.1.1:9300`. + +Alternatively, use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) to add a remote cluster. You can also use this API to dynamically configure remote clusters for *every* node in the local cluster. To configure remote clusters on individual nodes in the local cluster, define static settings in `elasticsearch.yml` for each node. + +The following request adds a remote cluster with an alias of `cluster_one`. This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices. + +```console +PUT /_cluster/settings +{ + "persistent" : { + "cluster" : { + "remote" : { + "cluster_one" : { <1> + "seeds" : [ + "127.0.0.1:9300" <2> + ] + } + } + } + } +} +``` + +1. The cluster alias of this remote cluster is `cluster_one`. +2. Specifies the hostname and transport port of a seed node in the remote cluster. + + +You can use the [remote cluster info API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) to verify that the local cluster is successfully connected to the remote cluster: + +```console +GET /_remote/info +``` + +The API response indicates that the local cluster is connected to the remote cluster with the cluster alias `cluster_one`: + +```console-result +{ + "cluster_one" : { + "seeds" : [ + "127.0.0.1:9300" + ], + "connected" : true, + "num_nodes_connected" : 1, <1> + "max_connections_per_cluster" : 3, + "initial_connect_timeout" : "30s", + "skip_unavailable" : true, <2> + "mode" : "sniff" + } +} +``` + +1. The number of nodes in the remote cluster the local cluster is connected to. +2. Indicates whether to skip the remote cluster if searched through {{ccs}} but no nodes are available. + + +### Dynamically configure remote clusters [_dynamically_configure_remote_clusters_2] + +Use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) to dynamically configure remote settings on every node in the cluster. The following request adds three remote clusters: `cluster_one`, `cluster_two`, and `cluster_three`. + +The `seeds` parameter specifies the hostname and [transport port](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html) (default `9300`) of a seed node in the remote cluster. + +The `mode` parameter determines the configured connection mode, which defaults to [`sniff`](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode). Because `cluster_one` doesn’t specify a `mode`, it uses the default. Both `cluster_two` and `cluster_three` explicitly use different modes. + +```console +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_one": { + "seeds": [ + "127.0.0.1:9300" + ] + }, + "cluster_two": { + "mode": "sniff", + "seeds": [ + "127.0.0.1:9301" + ], + "transport.compress": true, + "skip_unavailable": true + }, + "cluster_three": { + "mode": "proxy", + "proxy_address": "127.0.0.1:9302" + } + } + } + } +} +``` + +You can dynamically update settings for a remote cluster after the initial configuration. The following request updates the compression settings for `cluster_two`, and the compression and ping schedule settings for `cluster_three`. + +::::{note} +When the compression or ping schedule settings change, all existing node connections must close and re-open, which can cause in-flight requests to fail. +:::: + + +```console +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_two": { + "transport.compress": false + }, + "cluster_three": { + "transport.compress": true, + "transport.ping_schedule": "60s" + } + } + } + } +} +``` + +You can delete a remote cluster from the cluster settings by passing `null` values for each remote cluster setting. The following request removes `cluster_two` from the cluster settings, leaving `cluster_one` and `cluster_three` intact: + +```console +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster_two": { + "mode": null, + "seeds": null, + "skip_unavailable": null, + "transport.compress": null + } + } + } + } +} +``` + + +### Statically configure remote clusters [_statically_configure_remote_clusters_2] + +If you specify settings in `elasticsearch.yml`, only the nodes with those settings can connect to the remote cluster and serve remote cluster requests. + +::::{note} +Remote cluster settings that are specified using the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) take precedence over settings that you specify in `elasticsearch.yml` for individual nodes. +:::: + + +In the following example, `cluster_one`, `cluster_two`, and `cluster_three` are arbitrary cluster aliases representing the connection to each cluster. These names are subsequently used to distinguish between local and remote indices. + +```yaml +cluster: + remote: + cluster_one: + seeds: 127.0.0.1:9300 + cluster_two: + mode: sniff + seeds: 127.0.0.1:9301 + transport.compress: true <1> + skip_unavailable: true <2> + cluster_three: + mode: proxy + proxy_address: 127.0.0.1:9302 <3> +``` + +1. Compression is explicitly enabled for requests to `cluster_two`. +2. Disconnected remote clusters are optional for `cluster_two`. +3. The address for the proxy endpoint used to connect to `cluster_three`. + + + + +## Configure roles and users for remote clusters [remote-clusters-privileges-cert] + +After [connecting remote clusters](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-connect.html), you create a user role on both the local and remote clusters and assign necessary privileges. These roles are required to use {{ccr}} and {{ccs}}. + +::::{important} +You must use the same role names on both the local and remote clusters. For example, the following configuration for {{ccr}} uses the `remote-replication` role name on both the local and remote clusters. However, you can specify different role definitions on each cluster. +:::: + + +You can manage users and roles from Stack Management in {{kib}} by selecting **Security > Roles** from the side navigation. You can also use the [role management APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html#security-role-mapping-apis) to add, update, remove, and retrieve roles dynamically. When you use the APIs to manage roles in the `native` realm, the roles are stored in an internal {{es}} index. + +The following requests use the [create or update roles API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html). You must have at least the `manage_security` cluster privilege to use this API. + +### Configure privileges for {{ccr}} [remote-clusters-privileges-ccr] + +The {{ccr}} user requires different cluster and index privileges on the remote cluster and local cluster. Use the following requests to create separate roles on the local and remote clusters, and then create a user with the required roles. + + +##### Remote cluster [_remote_cluster] + +On the remote cluster that contains the leader index, the {{ccr}} role requires the `read_ccr` cluster privilege, and `monitor` and `read` privileges on the leader index. + +::::{note} +If requests are authenticated with an [API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), the API key requires the above privileges on the **local** cluster, instead of the remote. +:::: + + +::::{note} +If requests are issued [on behalf of other users](../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the `run_as` privilege on the remote cluster. +:::: + + +The following request creates a `remote-replication` role on the remote cluster: + +```console +POST /_security/role/remote-replication +{ + "cluster": [ + "read_ccr" + ], + "indices": [ + { + "names": [ + "leader-index-name" + ], + "privileges": [ + "monitor", + "read" + ] + } + ] +} +``` + + +##### Local cluster [_local_cluster] + +On the local cluster that contains the follower index, the `remote-replication` role requires the `manage_ccr` cluster privilege, and `monitor`, `read`, `write`, and `manage_follow_index` privileges on the follower index. + +The following request creates a `remote-replication` role on the local cluster: + +```console +POST /_security/role/remote-replication +{ + "cluster": [ + "manage_ccr" + ], + "indices": [ + { + "names": [ + "follower-index-name" + ], + "privileges": [ + "monitor", + "read", + "write", + "manage_follow_index" + ] + } + ] +} +``` + +After creating the `remote-replication` role on each cluster, use the [create or update users API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html) to create a user on the local cluster cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: + +```console +POST /_security/user/cross-cluster-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-replication" ] +} +``` + +::::{note} +You only need to create this user on the **local** cluster. +:::: + + +You can then [configure {{ccr}}](../tools/cross-cluster-replication/set-up-cross-cluster-replication.md) to replicate your data across datacenters. + + +### Configure privileges for {{ccs}} [remote-clusters-privileges-ccs] + +The {{ccs}} user requires different cluster and index privileges on the remote cluster and local cluster. The following requests create separate roles on the local and remote clusters, and then create a user with the required roles. + + +##### Remote cluster [_remote_cluster_2] + +On the remote cluster, the {{ccs}} role requires the `read` and `read_cross_cluster` privileges for the target indices. + +::::{note} +If requests are authenticated with an [API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), the API key requires the above privileges on the **local** cluster, instead of the remote. +:::: + + +::::{note} +If requests are issued [on behalf of other users](../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the `run_as` privilege on the remote cluster. +:::: + + +The following request creates a `remote-search` role on the remote cluster: + +```console +POST /_security/role/remote-search +{ + "indices": [ + { + "names": [ + "target-indices" + ], + "privileges": [ + "read", + "read_cross_cluster" + ] + } + ] +} +``` + + +##### Local cluster [_local_cluster_2] + +On the local cluster, which is the cluster used to initiate cross cluster search, a user only needs the `remote-search` role. The role privileges can be empty. + +The following request creates a `remote-search` role on the local cluster: + +```console +POST /_security/role/remote-search +{} +``` + +After creating the `remote-search` role on each cluster, use the [create or update users API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html) to create a user on the local cluster and assign the `remote-search` role. For example, the following request assigns the `remote-search` role to a user named `cross-search-user`: + +```console +POST /_security/user/cross-search-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-search" ] +} +``` + +::::{note} +You only need to create this user on the **local** cluster. +:::: + + +Users with the `remote-search` role can then [search across clusters](../../solutions/search/cross-cluster-search.md). + + +### Configure privileges for {{ccs}} and {{kib}} [clusters-privileges-ccs-kibana-cert] + +When using {{kib}} to search across multiple clusters, a two-step authorization process determines whether or not the user can access data streams and indices on a remote cluster: + +* First, the local cluster determines if the user is authorized to access remote clusters. The local cluster is the cluster that {{kib}} is connected to. +* If the user is authorized, the remote cluster then determines if the user has access to the specified data streams and indices. + +To grant {{kib}} users access to remote clusters, assign them a local role with read privileges to indices on the remote clusters. You specify data streams and indices in a remote cluster as `:`. + +To grant users read access on the remote data streams and indices, you must create a matching role on the remote clusters that grants the `read_cross_cluster` privilege with access to the appropriate data streams and indices. + +For example, you might be actively indexing {{ls}} data on a local cluster and and periodically offload older time-based indices to an archive on your remote cluster. You want to search across both clusters, so you must enable {{kib}} users on both clusters. + + +##### Local cluster [_local_cluster_3] + +On the local cluster, create a `logstash-reader` role that grants `read` and `view_index_metadata` privileges on the local `logstash-*` indices. + +::::{note} +If you configure the local cluster as another remote in {{es}}, the `logstash-reader` role on your local cluster also needs to grant the `read_cross_cluster` privilege. +:::: + + +```console +POST /_security/role/logstash-reader +{ + "indices": [ + { + "names": [ + "logstash-*" + ], + "privileges": [ + "read", + "view_index_metadata" + ] + } + ] +} +``` + +Assign your {{kib}} users a role that grants [access to {{kib}}](../users-roles/cluster-or-deployment-auth/built-in-roles.md), as well as your `logstash_reader` role. For example, the following request creates the `cross-cluster-kibana` user and assigns the `kibana-access` and `logstash-reader` roles. + +```console +PUT /_security/user/cross-cluster-kibana +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ + "logstash-reader", + "kibana-access" + ] +} +``` + + +##### Remote cluster [_remote_cluster_3] + +On the remote cluster, create a `logstash-reader` role that grants the `read_cross_cluster` privilege and `read` and `view_index_metadata` privileges for the `logstash-*` indices. + +```console +POST /_security/role/logstash-reader +{ + "indices": [ + { + "names": [ + "logstash-*" + ], + "privileges": [ + "read_cross_cluster", + "read", + "view_index_metadata" + ] + } + ] +} +``` diff --git a/deploy-manage/remote-clusters/remote-clusters-migrate.md b/deploy-manage/remote-clusters/remote-clusters-migrate.md new file mode 100644 index 000000000..9749e0e19 --- /dev/null +++ b/deploy-manage/remote-clusters/remote-clusters-migrate.md @@ -0,0 +1,253 @@ +--- +navigation_title: "Migrate from certificate to API key authentication" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-migrate.html +--- + + + +# Migrate from certificate to API key authentication [remote-clusters-migrate] + + +The API key based security model for remote clusters offers administrators more fine-grained access controls compared to the TLS certificate based security model. For that reason, you may want to migrate from the certificate based security model to the API key based model. + +While it is possible to migrate by defining a new remote cluster connection, using a new alias, this has several downsides: + +* For {{ccr}}, it’s not possible to change the leader cluster alias for existing tasks. As a result, with a new remote cluster, follower indices would need to be re-created from scratch. +* For {{ccs}}, transform and anomaly detection jobs do allow updating the remote cluster alias. However, if the job was created with wildcards, for example `*:source_index`, and `superuser`, adding a new remote cluster will cause the job to do double the amount of work and potentially skew results with duplications. + +For these reasons, you may prefer to migrate a remote cluster in-place, by following these steps: + +1. [Review the prerequisites](#remote-clusters-migration-prerequisites) +2. [Reconfigure the remote cluster and generate a cross-cluster API key](#remote-clusters-migration-remote-cluster) +3. [Stop cross-cluster operations](#remote-clusters-migration-stop) +4. [Reconnect to the remote cluster](#remote-clusters-migration-reconnect) +5. [Resume cross-cluster operations](#remote-clusters-migration-resume) +6. [Disable certificate based authentication and authorization](#remote-clusters-migration-disable-cert) + +If you run into any issues, refer to [Troubleshooting](remote-clusters-troubleshooting.md). + +## Prerequisites [remote-clusters-migration-prerequisites] + +* The nodes of the local and remote clusters must be on version 8.10 or later. +* The local and remote clusters must have an appropriate license. For more information, refer to [https://www.elastic.co/subscriptions](https://www.elastic.co/subscriptions). + + +## Reconfigure the remote cluster and generate a cross-cluster API key [remote-clusters-migration-remote-cluster] + +On the remote cluster: + +1. Enable the remote cluster server on every node of the remote cluster. In `elasticsearch.yml`: + + 1. Set [`remote_cluster_server.enabled`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote-cluster-network-settings) to `true`. + 2. Configure the bind and publish address for remote cluster server traffic, for example using [`remote_cluster.host`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote-cluster-network-settings). Without configuring the address, remote cluster traffic may be bound to the local interface, and remote clusters running on other machines can’t connect. + 3. Optionally, configure the remote server port using [`remote_cluster.port`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote_cluster.port) (defaults to `9443`). + +2. Next, generate a certificate authority (CA) and a server certificate/key pair. On one of the nodes of the remote cluster, from the directory where {{es}} has been installed: + + 1. Create a CA, if you don’t have a CA already: + + ```sh + ./bin/elasticsearch-certutil ca --pem --out=cross-cluster-ca.zip --pass CA_PASSWORD + ``` + + Replace `CA_PASSWORD` with the password you want to use for the CA. You can remove the `--pass` option and its argument if you are not deploying to a production environment. + + 2. Unzip the generated `cross-cluster-ca.zip` file. This compressed file contains the following content: + + ```txt + /ca + |_ ca.crt + |_ ca.key + ``` + + 3. Generate a certificate and private key pair for the nodes in the remote cluster: + + ```sh + ./bin/elasticsearch-certutil cert --out=cross-cluster.p12 --pass=CERT_PASSWORD --ca-cert=ca/ca.crt --ca-key=ca/ca.key --ca-pass=CA_PASSWORD --dns=example.com --ip=127.0.0.1 + ``` + + * Replace `CA_PASSWORD` with the CA password from the previous step. + * Replace `CERT_PASSWORD` with the password you want to use for the generated private key. + * Use the `--dns` option to specify the relevant DNS name for the certificate. You can specify it multiple times for multiple DNS. + * Use the `--ip` option to specify the relevant IP address for the certificate. You can specify it multiple times for multiple IP addresses. + + 4. If the remote cluster has multiple nodes, you can either: + + * create a single wildcard certificate for all nodes; + * or, create separate certificates for each node either manually or in batch with the [silent mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/certutil.html#certutil-silent). + +3. On every node of the remote cluster: + + 1. Copy the `cross-cluster.p12` file from the earlier step to the `config` directory. If you didn’t create a wildcard certificate, make sure you copy the correct node-specific p12 file. + 2. Add following configuration to `elasticsearch.yml`: + + ```yaml + xpack.security.remote_cluster_server.ssl.enabled: true + xpack.security.remote_cluster_server.ssl.keystore.path: cross-cluster.p12 + ``` + + 3. Add the SSL keystore password to the {{es}} keystore: + + ```sh + ./bin/elasticsearch-keystore add xpack.security.remote_cluster_server.ssl.keystore.secure_password + ``` + + When prompted, enter the `CERT_PASSWORD` from the earlier step. + +4. Restart the remote cluster. +5. On the remote cluster, generate a cross-cluster API key that provides access to the indices you want to use for {{ccs}} or {{ccr}}. You can use the [Create Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) API or [Kibana](../api-keys/elasticsearch-api-keys.md). +6. Copy the encoded key (`encoded` in the response) to a safe location. You will need it to connect to the remote cluster later. + + +## Stop cross-cluster operations [remote-clusters-migration-stop] + +On the local cluster, stop any persistent tasks that refer to the remote cluster: + +* Use the [Stop {{transforms}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-transform.html) API to stop any transforms. +* Use the [Close jobs](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-close-job.html) API to close any anomaly detection jobs. +* Use the [Pause auto-follow pattern](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-pause-auto-follow-pattern.html) API to pause any auto-follow {{ccr}}. +* Use the [Pause follower](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-pause-follow.html) API to pause any manual {{ccr}} or existing indices that were created from the auto-follow pattern. + + +## Reconnect to the remote cluster [remote-clusters-migration-reconnect] + +On the local cluster: + +1. Enhance any roles used by local cluster users with the required [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) or [remote cluster privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-cluster-priv) for {{ccr}} and {{ccs}}. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). Note: + + * You only need to assign additional `remote_indices` or `remote_cluster` privileges to existing roles used for cross-cluster operations. You should be able to copy these privileges from the original roles on the remote cluster, where they are defined under the certification based security model. + * The roles on the local cluster can’t exceed the `access` privilege granted by the cross-cluster API key. Any extra local privileges will be suppressed by the cross-cluster API key’s privileges. + * No update is needed if the {{ccr}} or {{ccs}} tasks have been configured with a `superuser` role. The `superuser` role is automatically updated to allow access to all remote indices. + * Tasks that are run as regular users with named roles are immediately updated with the new privileges. A task will load a new definition the next time it runs. + * You need to restart tasks that are run using an API key (done in a later step). + +2. If you’ve dynamically configured the remote cluster (via the cluster settings API): + + 1. Retrieve the current remote cluster configuration, and store it in a safe place. You may need it later in case you need to [roll back](#remote-clusters-migration-rollback). Use the cluster settings API: + + ```console + GET /_cluster/settings?filter_path=persistent.cluster.remote + ``` + + 2. Remove the existing remote cluster definition by setting the remote cluster settings to `null`. + +3. If you’ve statically configured the remote cluster (via `elasticsearch.yml`), copy the `cluster.remote` settings from `elasticsearch.yml`, and store them in a safe place. You may need them later in case you need to [roll back](#remote-clusters-migration-rollback). +4. On every node of the local cluster: + + 1. Copy the `ca.crt` file generated on the remote cluster earlier into the `config` directory, renaming the file `remote-cluster-ca.crt`. + 2. Add following configuration to `elasticsearch.yml`: + + ```yaml + xpack.security.remote_cluster_client.ssl.enabled: true + xpack.security.remote_cluster_client.ssl.certificate_authorities: [ "remote-cluster-ca.crt" ] + ``` + + 3. Add the cross-cluster API key, created on the remote cluster earlier, to the keystore: + + ```sh + ./bin/elasticsearch-keystore add cluster.remote.ALIAS.credentials + ``` + + Replace `ALIAS` with the same alias that was used for cross-cluster operations before the migration. When prompted, enter the encoded cross-cluster API key created on the remote cluster earlier. + +5. If you’ve dynamically configured the remote cluster (via the cluster settings API): + + 1. Restart the local cluster to load changes to the keystore and settings. + 2. Re-add the remote cluster. Use the same remote cluster alias, and change the transport port into the remote cluster port. For example: + + ```console + PUT /_cluster/settings + { + "persistent" : { + "cluster" : { + "remote" : { + "my_remote" : { <1> + "mode": "proxy", + "proxy_address": "my.remote.cluster.com:9443" <2> + } + } + } + } + } + ``` + + 1. The remote cluster alias. Use the same alias that was used before the migration. + 2. The remote cluster address with the remote cluster port, which defaults to `9443`. + +6. If you’ve statically configured the remote cluster (via `elasticsearch.yml`): + + 1. Update the `cluster.remote` settings in `elasticsearch.yml` on each node of the local cluster. Change the port into the remote cluster port, which defaults to `9443`. + 2. Restart the local cluster to load changes to the keystore and settings. + +7. Use the [remote cluster info API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) to verify that the local cluster has successfully connected to the remote cluster: + + ```console + GET /_remote/info + ``` + + The API response should indicate that the local cluster has connected to the remote cluster: + + ```console-result + { + "my_remote": { + "connected": true, <1> + "mode": "proxy", + "proxy_address": "my.remote.cluster.com:9443", + "server_name": "", + "num_proxy_sockets_connected": 0, + "max_proxy_socket_connections": 18, + "initial_connect_timeout": "30s", + "skip_unavailable": false, + "cluster_credentials": "::es_redacted::" <2> + } + } + ``` + + 1. The remote cluster is connected. + 2. If present, indicates the remote cluster has connected using API key authentication. + + + +## Resume cross-cluster operations [remote-clusters-migration-resume] + +Resume any persistent tasks that you stopped earlier. Tasks should be restarted by the same user or API key that created the task before the migration. Ensure the roles of this user or API key have been updated with the required `remote_indices` or `remote_cluster` privileges. For users, tasks capture the caller’s credentials when started and run in that user’s security context. For API keys, restarting a task will update the task with the updated API key. + +* Use the [Start {{transform}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/start-transform.html) API to start any transforms. +* Use the [Open jobs](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html) API to open any anomaly detection jobs. +* Use the [Resume follower](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-resume-follow.html) API to resume any auto-follow {{ccr}}. +* Use the [Resume auto-follow pattern](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-resume-auto-follow-pattern.html) API to resume any manual {{ccr}} or existing indices that were created from the auto-follow pattern. + + +## Disable certificate based authentication and authorization [remote-clusters-migration-disable-cert] + +::::{note} +Only proceed with this step if the migration has been proved successful on the local cluster. If the migration is unsuccessful, either [find out what the problem is and attempt to fix it](remote-clusters-troubleshooting.md) or [roll back](#remote-clusters-migration-rollback). +:::: + + +Next, disable the certification based connection. Optionally, you can also revoke the authorization. + +1. There is no particular setting to enable or disable a certificate based cross cluster connection, because it shares the same transport protocol with the intra-cluster node-to-node communication. + + One way a remote cluster administrator can stop an existing local cluster from connecting, is by changing TLS trust. The exact steps vary, depending on how the clusters have been configured. A generic solution is to [recreate the CA and certificate/key used by the remote transport interface](../security/secure-cluster-communications.md#encrypt-internode-communication) so that any existing certificate/key, locally or distributed, is no longer trusted. + + Another solution is to apply IP filters to the transport interface, blocking traffic from outside the cluster. + +2. Optionally, delete any roles on the remote cluster that were only used for cross-cluster operations. These roles are no longer used under the API key based security model. + + +## Rollback [remote-clusters-migration-rollback] + +If you need to roll back, follow these steps on the local cluster: + +1. Stop any persistent tasks that refer to the remote cluster. +2. Remove the remote cluster definition by setting the remote cluster settings to `null`. +3. Remove the `remote_indices` or *remote_cluster* privileges from any roles that were updated during the migration. +4. On each node, remove the `remote_cluster_client.ssl.*` settings from `elasticsearch.yml`. +5. Restart the local cluster to apply changes to the keystore and `elasticsearch.yml`. +6. On the local cluster, apply the original remote cluster settings. If the remote cluster connection has been configured statically (using the `elasticsearch.yml` file), restart the cluster. +7. Use the [remote cluster info API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) to verify that the local cluster has connected to the remote cluster. The response should have `"connected": true` and not have `"cluster_credentials": "::es_redacted::"`. +8. Restart any persistent tasks that you’ve stopped earlier. + + diff --git a/deploy-manage/remote-clusters/remote-clusters-self-managed.md b/deploy-manage/remote-clusters/remote-clusters-self-managed.md new file mode 100644 index 000000000..c1b6b6d9c --- /dev/null +++ b/deploy-manage/remote-clusters/remote-clusters-self-managed.md @@ -0,0 +1,71 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html +--- + +# Remote clusters (self-managed) [remote-clusters] + +You can connect a local cluster to other {{es}} clusters, known as *remote clusters*. Remote clusters can be located in different datacenters or geographic regions, and contain indices or data streams that can be replicated with {{ccr}} or searched by a local cluster using {{ccs}}. + + +## {{ccr-cap}} [remote-clusters-ccr] + +With [{{ccr}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html), you ingest data to an index on a remote cluster. This *leader* index is replicated to one or more read-only *follower* indices on your local cluster. Creating a multi-cluster architecture with {{ccr}} enables you to configure disaster recovery, bring data closer to your users, or establish a centralized reporting cluster to process reports locally. + + +## {{ccs-cap}} [remote-clusters-ccs] + +[{{ccs-cap}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html) enables you to run a search request against one or more remote clusters. This capability provides each region with a global view of all clusters, allowing you to send a search request from a local cluster and return results from all connected remote clusters. For full {{ccs}} capabilities, the local and remote cluster must be on the same [subscription level](https://www.elastic.co/subscriptions). + + +## Add remote clusters [add-remote-clusters] + +::::{note} +The instructions that follow describe how to create a remote connection from a self-managed cluster. You can also set up {{ccs}} and {{ccr}} from an [{{ess}} deployment](https://www.elastic.co/guide/en/cloud/current/ec-enable-ccs.md) or from an [{{ece}} deployment](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-enable-ccs.md). +:::: + + +To add remote clusters, you can choose between [two security models](#remote-clusters-security-models) and [two connection modes](#sniff-proxy-modes). Both security models are compatible with either of the connection modes. + + +### Security models [remote-clusters-security-models] + +API key based security model +: For clusters on version 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote cluster fine-grained access controls. [Add remote clusters using API key authentication](remote-clusters-api-key.md). + +Certificate based security model +: Uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. In this model, a superuser on the local cluster gains total read access to the remote cluster, so it is only suitable for clusters that are in the same security domain. [Add remote clusters using TLS certificate authentication](remote-clusters-cert.md). + + ::::{admonition} Deprecated in 9.0.0. + :class: warning + + Use [API key based security model](remote-clusters-api-key.md) instead. + :::: + + + +### Connection modes [sniff-proxy-modes] + +$$$sniff-mode$$$ + +Sniff mode +: In sniff mode, a cluster alias is registered with a name of your choosing and a list of addresses of *seed* nodes specified with the `cluster.remote..seeds` setting. When you register a remote cluster using sniff mode, {{es}} retrieves from one of the seed nodes the addresses of up to three *gateway nodes*. Each `remote_cluster_client` node in the local {{es}} cluster then opens several TCP connections to the publish addresses of the gateway nodes. This mode therefore requires that the gateway nodes' publish addresses are accessible to nodes in the local cluster. + + Sniff mode is the default connection mode. See [Sniff mode remote cluster settings](remote-clusters-settings.md#remote-cluster-sniff-settings) for more information about configuring sniff mode. + + $$$gateway-nodes-selection$$$ + The *gateway nodes* selection depends on the following criteria: + + * **version**: Remote nodes must be compatible with the cluster they are registered to. + * **role**: By default, any non-[master-eligible](https://www.elastic.co/guide/en/elasticsearch/reference/current/node-roles-overview.html#master-node-role) node can act as a gateway node. Dedicated master nodes are never selected as gateway nodes. + * **attributes**: You can define the gateway nodes for a cluster by setting [`cluster.remote.node.attr.gateway`](remote-clusters-settings.md#cluster-remote-node-attr) to `true`. However, such nodes still have to satisfy the two above requirements. + + +$$$proxy-mode$$$ + +Proxy mode +: In proxy mode, a cluster alias is registered with a name of your choosing and the address of a TCP (layer 4) reverse proxy specified with the `cluster.remote..proxy_address` setting. You must configure this proxy to route connections to one or more nodes of the remote cluster. When you register a remote cluster using proxy mode, {{es}} opens several TCP connections to the proxy address and uses these connections to communicate with the remote cluster. In proxy mode {{es}} disregards the publish addresses of the remote cluster nodes which means that the publish addresses of the remote cluster nodes need not be accessible to the local cluster. + + Proxy mode is not the default connection mode, so you must set `cluster.remote..mode: proxy` to use it. See [Proxy mode remote cluster settings](remote-clusters-settings.md#remote-cluster-proxy-settings) for more information about configuring proxy mode. + + Proxy mode has the same [version compatibility requirements](#gateway-nodes-selection) as sniff mode. diff --git a/deploy-manage/remote-clusters/remote-clusters-settings.md b/deploy-manage/remote-clusters/remote-clusters-settings.md new file mode 100644 index 000000000..0cec6b0f4 --- /dev/null +++ b/deploy-manage/remote-clusters/remote-clusters-settings.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-settings.html +--- + +# Remote cluster settings [remote-clusters-settings] + +The following settings apply to both [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) and [proxy mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#proxy-mode). Settings that are specific to sniff mode and proxy mode are described separately. + +`cluster.remote..mode` +: The mode used for a remote cluster connection. The only supported modes are `sniff` and `proxy`. The default is `sniff`. See [Connection modes](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-proxy-modes) for further information about these modes, and [Sniff mode remote cluster settings](#remote-cluster-sniff-settings) and [Proxy mode remote cluster settings](#remote-cluster-proxy-settings) for further information about their settings. + +`cluster.remote.initial_connect_timeout` +: The time to wait for remote connections to be established when the node starts. The default is `30s`. + +`remote_cluster_client` [role](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) +: By default, any node in the cluster can act as a cross-cluster client and connect to remote clusters. To prevent a node from connecting to remote clusters, specify the [node.roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) setting in `elasticsearch.yml` and exclude `remote_cluster_client` from the listed roles. Search requests targeting remote clusters must be sent to a node that is allowed to act as a cross-cluster client. Other features such as {{ml}} [data feeds](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-settings.html#general-ml-settings), [transforms](https://www.elastic.co/guide/en/elasticsearch/reference/current/transform-settings.html#general-transform-settings), and [{{ccr}}](../tools/cross-cluster-replication/set-up-cross-cluster-replication.md) require the `remote_cluster_client` role. + +`cluster.remote..skip_unavailable` +: Per cluster boolean setting that allows to skip specific clusters when no nodes belonging to them are available and they are the target of a remote cluster request. + +::::{important} +In Elasticsearch 8.15, the default value for `skip_unavailable` was changed from `false` to `true`. Before Elasticsearch 8.15, if you want a cluster to be treated as optional for a {{ccs}}, then you need to set that configuration. From Elasticsearch 8.15 forward, you need to set the configuration in order to make a cluster required for the {{ccs}}. Once you upgrade the local ("querying") cluster search coordinator node (the node you send CCS requests to) to 8.15 or later, any remote clusters that do not have an explicit setting for `skip_unavailable` will immediately change over to using the new default of true. This is true regardless of whether you have upgraded the remote clusters to 8.15, as the `skip_unavailable` search behavior is entirely determined by the setting on the local cluster where you configure the remotes. +:::: + + +`cluster.remote..transport.ping_schedule` +: Sets the time interval between regular application-level ping messages that are sent to try and keep remote cluster connections alive. If set to `-1`, application-level ping messages to this remote cluster are not sent. If unset, application-level ping messages are sent according to the global `transport.ping_schedule` setting, which defaults to `-1` meaning that pings are not sent. It is preferable to correctly configure TCP keep-alives instead of configuring a `ping_schedule`, because TCP keep-alives are handled by the operating system and not by {{es}}. By default {{es}} enables TCP keep-alives on remote cluster connections. Remote cluster connections are transport connections so the `transport.tcp.*` [advanced settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings) regarding TCP keep-alives apply to them. + +`cluster.remote..transport.compress` +: Per-cluster setting that enables you to configure compression for requests to a specific remote cluster. The handling cluster will automatically compress responses to compressed requests. The setting options are `true`, `indexing_data`, and `false`. If unset, defaults to the behaviour specified by the node-wide `transport.compress` setting. See the [documentation for the `transport.compress` setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings-compress) for further information. + +`cluster.remote..transport.compression_scheme` +: Per-cluster setting that enables you to configure the compression scheme for requests to a specific cluster if those requests are selected to be compressed by to the `cluster.remote..transport.compress` setting. The handling cluster will automatically use the same compression scheme for responses as for the corresponding requests. The setting options are `deflate` and `lz4`. If unset, defaults to the behaviour specified by the node-wide `transport.compression_scheme` setting. See the [documentation for the `transport.compression_scheme` setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings-compression-scheme) for further information. + +$$$remote-cluster-credentials-setting$$$ + +`cluster.remote..credentials` +: ([Secure](../security/secure-settings.md), [Reloadable](../security/secure-settings.md#reloadable-secure-settings)) Per-cluster setting for configuring [remote clusters with the API Key based model](remote-clusters-api-key.md). This setting takes the encoded value of a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) and must be set in the [{{es}} keystore](../security/secure-settings.md) on each node in the cluster. The presence (or not) of this setting determines which model a remote cluster uses. If present, the remote cluster uses the API key based model. Otherwise, it uses the certificate based model. If the setting is added, removed, or updated in the [{{es}} keystore](../security/secure-settings.md) and reloaded via the [Nodes reload secure settings](../security/secure-settings.md) API, the cluster will automatically rebuild its connection to the remote. + +## Sniff mode remote cluster settings [remote-cluster-sniff-settings] + +To use [sniff mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#sniff-mode) to connect to a remote cluster, set `cluster.remote..mode: sniff` and then configure the following settings. You may also leave `cluster.remote..mode` unset since `sniff` is the default mode. + +`cluster.remote..seeds` +: The list of seed nodes used to sniff the remote cluster state. + +`cluster.remote..node_connections` +: The number of gateway nodes to connect to for this remote cluster. The default is `3`. + +$$$cluster-remote-node-attr$$$ + +`cluster.remote.node.attr` +: A node attribute to filter out nodes that are eligible as a gateway node in the remote cluster. For instance a node can have a node attribute `node.attr.gateway: true` such that only nodes with this attribute will be connected to if `cluster.remote.node.attr` is set to `gateway`. + + +## Proxy mode remote cluster settings [remote-cluster-proxy-settings] + +To use [proxy mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#proxy-mode) to connect to a remote cluster, set `cluster.remote..mode: proxy` and then configure the following settings. + +`cluster.remote..proxy_address` +: The address used for all remote connections. + +`cluster.remote..proxy_socket_connections` +: The number of socket connections to open per remote cluster. The default is `18`. + +`cluster.remote..server_name` +: An optional hostname string which is sent in the `server_name` field of the TLS Server Name Indication extension if [TLS is enabled](../security/secure-cluster-communications.md#encrypt-internode-communication). The TLS transport will fail to open remote connections if this field is not a valid hostname as defined by the TLS SNI specification. + + diff --git a/deploy-manage/remote-clusters/remote-clusters-troubleshooting.md b/deploy-manage/remote-clusters/remote-clusters-troubleshooting.md new file mode 100644 index 000000000..720b49e8f --- /dev/null +++ b/deploy-manage/remote-clusters/remote-clusters-troubleshooting.md @@ -0,0 +1,406 @@ +--- +navigation_title: "Troubleshooting" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-troubleshooting.html +--- + + + +# Troubleshooting [remote-clusters-troubleshooting] + + +You may encounter several issues when setting up a remote cluster for {{ccr}} or {{ccs}}. + +## General troubleshooting [remote-clusters-troubleshooting-general] + +### Checking whether a remote cluster has connected successfully [remote-clusters-troubleshooting-check-connection] + +A successful call to the cluster settings update API for adding or updating remote clusters does not necessarily mean the configuration is successful. Use the [remote cluster info API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) to verify that a local cluster is successfully connected to a remote cluster. + +```console +GET /_remote/info +``` + +The API should return `"connected" : true`. When using [API key authentication](remote-clusters-api-key.md), it should also return `"cluster_credentials": "::es_redacted::"`. + +```console-result +{ + "cluster_one" : { + "seeds" : [ + "127.0.0.1:9443" + ], + "connected" : true, <1> + "num_nodes_connected" : 1, + "max_connections_per_cluster" : 3, + "initial_connect_timeout" : "30s", + "skip_unavailable" : false, + "cluster_credentials": "::es_redacted::", <2> + "mode" : "sniff" + } +} +``` + +1. The remote cluster has connected successfully. +2. If present, indicates the remote cluster has connected using [API key authentication](remote-clusters-api-key.md) instead of [certificate based authentication](remote-clusters-cert.md). + + + +### Enabling the remote cluster server [remote-clusters-troubleshooting-enable-server] + +When using API key authentication, cross-cluster traffic happens on the remote cluster interface, instead of the transport interface. The remote cluster interface is not enabled by default. This means a node is not ready to accept incoming cross-cluster requests by default, while it is ready to send outgoing cross-cluster requests. Ensure you’ve enabled the remote cluster server on every node of the remote cluster. In `elasticsearch.yml`: + +* Set [`remote_cluster_server.enabled`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote-cluster-network-settings) to `true`. +* Configure the bind and publish address for remote cluster server traffic, for example using [`remote_cluster.host`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote-cluster-network-settings). Without configuring the address, remote cluster traffic may be bound to the local interface, and remote clusters running on other machines can’t connect. +* Optionally, configure the remote server port using [`remote_cluster.port`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#remote_cluster.port) (defaults to `9443`). + + + +## Common issues [remote-clusters-troubleshooting-common-issues] + +The following issues are listed in the order they may occur while setting up a remote cluster. + +### Remote cluster not reachable [remote-clusters-not-reachable] + +#### Symptom [_symptom] + +A local cluster may not be able to reach a remote cluster for many reasons. For example, the remote cluster server may not be enabled, an incorrect host or port may be configured, or a firewall may be blocking traffic. When a remote cluster is not reachable, check the logs of the local cluster for a `connect_exception`. + +When the remote cluster is configured using proxy mode: + +```txt +[2023-06-28T16:36:47,264][WARN ][o.e.t.ProxyConnectionStrategy] [local-node] failed to open any proxy connections to cluster [my] +org.elasticsearch.transport.ConnectTransportException: [][192.168.0.42:9443] **connect_exception** +``` + +When the remote cluster is configured using sniff mode: + +```txt +[2023-06-28T16:38:37,731][WARN ][o.e.t.SniffConnectionStrategy] [local-node] fetching nodes from external cluster [my] failed +org.elasticsearch.transport.ConnectTransportException: [][192.168.0.42:9443] **connect_exception** +``` + + +#### Resolution [_resolution] + +* Check the host and port for the remote cluster are correct. +* Ensure the [remote cluster server is enabled](#remote-clusters-troubleshooting-enable-server) on the remote cluster. +* Ensure no firewall is blocking the communication. + + + +### Remote cluster connection is unreliable [remote-clusters-unreliable-network] + +#### Symptom [_symptom_2] + +The local cluster can connect to the remote cluster, but the connection does not work reliably. For example, some cross-cluster requests may succeed while others report connection errors, time out, or appear to be stuck waiting for the remote cluster to respond. + +When {{es}} detects that the remote cluster connection is not working, it will report the following message in its logs: + +```txt +[2023-06-28T16:36:47,264][INFO ][o.e.t.ClusterConnectionManager] [local-node] transport connection to [{my-remote#192.168.0.42:9443}{...}] closed by remote +``` + +This message will also be logged if the node of the remote cluster to which {{es}} is connected is shut down or restarted. + +Note that with some network configurations it could take minutes or hours for the operating system to detect that a connection has stopped working. Until the failure is detected and reported to {{es}}, requests involving the remote cluster may time out or may appear to be stuck. + + +#### Resolution [_resolution_2] + +* Ensure that the network between the clusters is as reliable as possible. +* Ensure that the network is configured to permit [Long-lived idle connections](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#long-lived-connections). +* Ensure that the network is configured to detect faulty connections quickly. In particular, you must enable and fully support TCP keepalives, and set a short [retransmission timeout](../deploy/self-managed/system-config-tcpretries.md). +* On Linux systems, execute `ss -tonie` to verify the details of the configuration of each network connection between the clusters. +* If the problems persist, capture network packets at both ends of the connection and analyse the traffic to look for delays and lost messages. + + + +### TLS trust not established [remote-clusters-troubleshooting-tls-trust] + +TLS can be misconfigured on the local or the remote cluster. The result is that the local cluster does not trust the certificate presented by the remote cluster. + +#### Symptom [_symptom_3] + +The local cluster logs `failed to establish trust with server`: + +```txt +[2023-06-29T09:40:55,465][WARN ][o.e.c.s.DiagnosticTrustManager] [local-node] **failed to establish trust with server** at [192.168.0.42]; the server provided a certificate with subject name [CN=remote_cluster], fingerprint [529de35e15666ffaa26afa50876a2a48119db03a], no keyUsage and no extendedKeyUsage; the certificate is valid between [2023-01-29T12:08:37Z] and [2032-08-29T12:08:37Z] (current time is [2023-08-16T23:40:55.464275Z], certificate dates are valid); the session uses cipher suite [TLS_AES_256_GCM_SHA384] and protocol [TLSv1.3]; the certificate has subject alternative names [DNS:localhost,DNS:localhost6.localdomain6,IP:127.0.0.1,IP:0:0:0:0:0:0:0:1,DNS:localhost4,DNS:localhost6,DNS:localhost.localdomain,DNS:localhost4.localdomain4,IP:192.168.0.42]; the certificate is issued by [CN=Elastic Auto RemoteCluster CA] but the server did not provide a copy of the issuing certificate in the certificate chain; this ssl context ([(shared) (with trust configuration: JDK-trusted-certs)]) is not configured to trust that issuer but trusts [97] other issuers +sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target +``` + +The remote cluster logs `client did not trust this server's certificate`: + +```txt +[2023-06-29T09:40:55,478][WARN ][o.e.x.c.s.t.n.SecurityNetty4Transport] [remote-node] **client did not trust this server's certificate**, closing connection Netty4TcpChannel{localAddress=/192.168.0.42:9443, remoteAddress=/192.168.0.84:57305, profile=_remote_cluster} +``` + + +#### Resolution [_resolution_3] + +Read the warn log message on the local cluster carefully to determine the exact cause of the failure. For example: + +* Is the remote cluster certificate not signed by a trusted CA? This is the most likely cause. +* Is hostname verification failing? +* Is the certificate expired? + +Once you know the cause, you should be able to fix it by adjusting the remote cluster related SSL settings on either the local cluster or the remote cluster. + +Often, the issue is on the local cluster. For example, fix it by configuring necessary trusted CAs (`xpack.security.remote_cluster_client.ssl.certificate_authorities`). + +If you change the `elasticsearch.yml` file, the associated cluster needs to be restarted for the changes to take effect. + + + + +## API key authentication issues [remote-clusters-troubleshooting-api-key] + +### Connecting to transport port when using API key authentication [remote-clusters-troubleshooting-transport-port-api-key] + +When using API key authentication, a local cluster should connect to a remote cluster’s remote cluster server port (defaults to `9443`) instead of the transport port (defaults to `9300`). A misconfiguration can lead to a number of symptoms: + +#### Symptom 1 [_symptom_1] + +It’s recommended to use different CAs and certificates for the transport interface and the remote cluster server interface. If this recommendation is followed, a remote cluster client node does not trust the server certificate presented by a remote cluster on the transport interface. + +The local cluster logs `failed to establish trust with server`: + +```txt +[2023-06-28T12:48:46,575][WARN ][o.e.c.s.DiagnosticTrustManager] [local-node] **failed to establish trust with server** at [1192.168.0.42]; the server provided a certificate with subject name [CN=transport], fingerprint [c43e628be2a8aaaa4092b82d78f2bc206c492322], no keyUsage and no extendedKeyUsage; the certificate is valid between [2023-01-29T12:05:53Z] and [2032-08-29T12:05:53Z] (current time is [2023-06-28T02:48:46.574738Z], certificate dates are valid); the session uses cipher suite [TLS_AES_256_GCM_SHA384] and protocol [TLSv1.3]; the certificate has subject alternative names [DNS:localhost,DNS:localhost6.localdomain6,IP:127.0.0.1,IP:0:0:0:0:0:0:0:1,DNS:localhost4,DNS:localhost6,DNS:localhost.localdomain,DNS:localhost4.localdomain4,IP:192.168.0.42]; the certificate is issued by [CN=Elastic Auto Transport CA] but the server did not provide a copy of the issuing certificate in the certificate chain; this ssl context ([xpack.security.remote_cluster_client.ssl (with trust configuration: PEM-trust{/rcs2/ssl/remote-cluster-ca.crt})]) is not configured to trust that issuer, it only trusts the issuer [CN=Elastic Auto RemoteCluster CA] with fingerprint [ba2350661f66e46c746c1629f0c4b645a2587ff4] +sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target +``` + +The remote cluster logs `client did not trust this server's certificate`: + +```txt +[2023-06-28T12:48:46,584][WARN ][o.e.x.c.s.t.n.SecurityNetty4Transport] [remote-node] **client did not trust this server's certificate**, closing connection Netty4TcpChannel{localAddress=/192.168.0.42:9309, remoteAddress=/192.168.0.84:60810, profile=default} +``` + + +#### Symptom 2 [_symptom_2_2] + +The CA and certificate can be shared between the transport and remote cluster server interface. Since a remote cluster client does not have a client certificate by default, the server will fail to verify the client certificate. + +The local cluster logs `Received fatal alert: bad_certificate`: + +```txt +[2023-06-28T12:43:30,705][WARN ][o.e.t.TcpTransport ] [local-node] exception caught on transport layer [Netty4TcpChannel{localAddress=/192.168.0.84:60738, remoteAddress=/192.168.0.42:9309, profile=_remote_cluster}], closing connection +io.netty.handler.codec.DecoderException: javax.net.ssl.SSLHandshakeException: **Received fatal alert: bad_certificate** +``` + +The remote cluster logs `Empty client certificate chain`: + +```txt +[2023-06-28T12:43:30,772][WARN ][o.e.t.TcpTransport ] [remote-node] exception caught on transport layer [Netty4TcpChannel{localAddress=/192.168.0.42:9309, remoteAddress=/192.168.0.84:60783, profile=default}], closing connection +io.netty.handler.codec.DecoderException: javax.net.ssl.SSLHandshakeException: **Empty client certificate chain** +``` + + +#### Symptom 3 [_symptom_3_2] + +If the remote cluster client is configured for mTLS and provides a valid client certificate, the connection fails because the client does not send the expected authentication header. + +The local cluster logs `missing authentication`: + +```txt +[2023-06-28T13:04:52,710][WARN ][o.e.t.ProxyConnectionStrategy] [local-node] failed to open any proxy connections to cluster [my] +org.elasticsearch.transport.RemoteTransportException: [remote-node][192.168.0.42:9309][cluster:internal/remote_cluster/handshake] +Caused by: org.elasticsearch.ElasticsearchSecurityException: **missing authentication** credentials for action [cluster:internal/remote_cluster/handshake] +``` + +This does not show up in the logs of the remote cluster. + + +#### Symptom 4 [_symptom_4] + +If anonymous access is enabled on the remote cluster and it does not require authentication, depending on the privileges of the anonymous user, the local cluster may log the following. + +If the anonymous user does not the have necessary privileges to make a connection, the local cluster logs `unauthorized`: + +```txt +org.elasticsearch.transport.RemoteTransportException: [remote-node][192.168.0.42:9309][cluster:internal/remote_cluster/handshake] +Caused by: org.elasticsearch.ElasticsearchSecurityException: action [cluster:internal/remote_cluster/handshake] is **unauthorized** for user [anonymous_foo] with effective roles [reporting_user], this action is granted by the cluster privileges [cross_cluster_search,cross_cluster_replication,manage,all] +``` + +If the anonymous user has necessary privileges, for example it is a superuser, the local cluster logs `requires channel profile to be [_remote_cluster], but got [default]`: + +```txt +[2023-06-28T13:09:52,031][WARN ][o.e.t.ProxyConnectionStrategy] [local-node] failed to open any proxy connections to cluster [my] +org.elasticsearch.transport.RemoteTransportException: [remote-node][192.168.0.42:9309][cluster:internal/remote_cluster/handshake] +Caused by: java.lang.IllegalArgumentException: remote cluster handshake action **requires channel profile to be [_remote_cluster], but got [default]** +``` + + +#### Resolution [_resolution_4] + +Check the port number and ensure you are indeed connecting to the remote cluster server instead of the transport interface. + + + +### Connecting without a cross-cluster API key [remote-clusters-troubleshooting-no-api-key] + +A local cluster uses the presence of a cross-cluster API key to determine the model with which it connects to a remote cluster. If a cross-cluster API key is present, it uses API key based authentication. Otherwise, it uses certificate based authentication. You can check what model is being used with the [remote cluster info API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html) on the local cluster: + +```console +GET /_remote/info +``` + +The API should return `"connected" : true`. When using [API key authentication](remote-clusters-api-key.md), it should also return `"cluster_credentials": "::es_redacted::"`. + +```console-result +{ + "cluster_one" : { + "seeds" : [ + "127.0.0.1:9443" + ], + "connected" : true, <1> + "num_nodes_connected" : 1, + "max_connections_per_cluster" : 3, + "initial_connect_timeout" : "30s", + "skip_unavailable" : false, + "cluster_credentials": "::es_redacted::", <2> + "mode" : "sniff" + } +} +``` + +1. The remote cluster has connected successfully. +2. If present, indicates the remote cluster has connected using [API key authentication](remote-clusters-api-key.md) instead of [certificate based authentication](remote-clusters-cert.md). + + +Besides checking the response of the remote cluster info API, you can also check the logs. + +#### Symptom 1 [_symptom_1_2] + +If no cross-cluster API key is used, the local cluster uses the certificate based authentication method, and connects to the remote cluster using the TLS configuration of the transport interface. If the remote cluster has different TLS CA and certificate for transport and remote cluster server interfaces (which is the recommendation), TLS verification will fail. + +The local cluster logs `failed to establish trust with server`: + +```txt +[2023-06-28T12:51:06,452][WARN ][o.e.c.s.DiagnosticTrustManager] [local-node] **failed to establish trust with server** at []; the server provided a certificate with subject name [CN=remote_cluster], fingerprint [529de35e15666ffaa26afa50876a2a48119db03a], no keyUsage and no extendedKeyUsage; the certificate is valid between [2023-01-29T12:08:37Z] and [2032-08-29T12:08:37Z] (current time is [2023-06-28T02:51:06.451581Z], certificate dates are valid); the session uses cipher suite [TLS_AES_256_GCM_SHA384] and protocol [TLSv1.3]; the certificate has subject alternative names [DNS:localhost,DNS:localhost6.localdomain6,IP:127.0.0.1,IP:0:0:0:0:0:0:0:1,DNS:localhost4,DNS:localhost6,DNS:localhost.localdomain,DNS:localhost4.localdomain4,IP:192.168.0.42]; the certificate is issued by [CN=Elastic Auto RemoteCluster CA] but the server did not provide a copy of the issuing certificate in the certificate chain; this ssl context ([xpack.security.transport.ssl (with trust configuration: PEM-trust{/rcs2/ssl/transport-ca.crt})]) is not configured to trust that issuer, it only trusts the issuer [CN=Elastic Auto Transport CA] with fingerprint [bbe49e3f986506008a70ab651b188c70df104812] +sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target +``` + +The remote cluster logs `client did not trust this server's certificate`: + +```txt +[2023-06-28T12:52:16,914][WARN ][o.e.x.c.s.t.n.SecurityNetty4Transport] [remote-node] **client did not trust this server's certificate**, closing connection Netty4TcpChannel{localAddress=/192.168.0.42:9443, remoteAddress=/192.168.0.84:60981, profile=_remote_cluster} +``` + + +#### Symptom 2 [_symptom_2_3] + +Even if TLS verification is not an issue, the connection fails due to missing credentials. + +The local cluster logs `Please ensure you have configured remote cluster credentials`: + +```txt +Caused by: java.lang.IllegalArgumentException: Cross cluster requests through the dedicated remote cluster server port require transport header [_cross_cluster_access_credentials] but none found. **Please ensure you have configured remote cluster credentials** on the cluster originating the request. +``` + +This does not show up in the logs of the remote cluster. + + +#### Resolution [_resolution_5] + +Add the cross-cluster API key to {{es}} keystore on every node of the local cluster. Use the [Nodes reload secure settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) API to reload the keystore. + + + +### Using the wrong API key type [remote-clusters-troubleshooting-wrong-api-key-type] + +API key based authentication requires [cross-cluster API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). It does not work with [REST API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html). + +#### Symptom [_symptom_5] + +The local cluster logs `authentication expected API key type of [cross_cluster]`: + +```txt +[2023-06-28T13:26:53,962][WARN ][o.e.t.ProxyConnectionStrategy] [local-node] failed to open any proxy connections to cluster [my] +org.elasticsearch.transport.RemoteTransportException: [remote-node][192.168.0.42:9443][cluster:internal/remote_cluster/handshake] +Caused by: org.elasticsearch.ElasticsearchSecurityException: **authentication expected API key type of [cross_cluster]**, but API key [agZXJocBmA2beJfq2yKu] has type [rest] +``` + +This does not show up in the logs of the remote cluster. + + +#### Resolution [_resolution_6] + +Ask the remote cluster administrator to create and distribute a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). Replace the existing API key in the {{es}} keystore with this cross-cluster API key on every node of the local cluster. Use the [Nodes reload secure settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) API to reload the keystore. + + + +### Invalid API key [remote-clusters-troubleshooting-non-valid-api-key] + +A cross-cluster API can fail to authenticate. For example, when its credentials are incorrect, or if it’s invalidated or expired. + +#### Symptom [_symptom_6] + +The local cluster logs `unable to authenticate`: + +```txt +[2023-06-28T13:22:58,264][WARN ][o.e.t.ProxyConnectionStrategy] [local-node] failed to open any proxy connections to cluster [my] +org.elasticsearch.transport.RemoteTransportException: [remote-node][192.168.0.42:9443][cluster:internal/remote_cluster/handshake] +Caused by: org.elasticsearch.ElasticsearchSecurityException: **unable to authenticate** user [agZXJocBmA2beJfq2yKu] for action [cluster:internal/remote_cluster/handshake] +``` + +The remote cluster logs `Authentication using apikey failed`: + +```txt +[2023-06-28T13:24:38,744][WARN ][o.e.x.s.a.ApiKeyAuthenticator] [remote-node] **Authentication using apikey failed** - invalid credentials for API key [agZXJocBmA2beJfq2yKu] +``` + + +#### Resolution [_resolution_7] + +Ask the remote cluster administrator to create and distribute a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). Replace the existing API key in the {{es}} keystore with this cross-cluster API key on every node of the local cluster. Use the [Nodes reload secure settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) API to reload the keystore. + + + +### API key or local user has insufficient privileges [remote-clusters-troubleshooting-insufficient-privileges] + +The effective permission for a local user running requests on a remote cluster is determined by the intersection of the cross-cluster API key’s privileges and the local user’s `remote_indices` privileges. + +#### Symptom [_symptom_7] + +Request failures due to insufficient privileges result in API responses like: + +```js +{ + "type": "security_exception", + "reason": "action [indices:data/read/search] towards remote cluster is **unauthorized for user** [foo] with assigned roles [foo-role] authenticated by API key id [agZXJocBmA2beJfq2yKu] of user [elastic-admin] on indices [cd], this action is granted by the index privileges [read,all]" +} +``` + +This does not show up in any logs. + + +#### Resolution [_resolution_8] + +1. Check that the local user has the necessary `remote_indices` or `remote_cluster` privileges. Grant sufficient `remote_indices` or `remote_cluster` privileges if necessary. +2. If permission is not an issue locally, ask the remote cluster administrator to create and distribute a [cross-cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html). Replace the existing API key in the {{es}} keystore with this cross-cluster API key on every node of the local cluster. Use the [Nodes reload secure settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) API to reload the keystore. + + + +### Local user has no `remote_indices` privileges [remote-clusters-troubleshooting-no-remote_indices-privileges] + +This is a special case of insufficient privileges. In this case, the local user has no `remote_indices` privileges at all for the target remote cluster. {{es}} can detect that and issue a more explicit error response. + +#### Symptom [_symptom_8] + +This results in API responses like: + +```js +{ + "type": "security_exception", + "reason": "action [indices:data/read/search] towards remote cluster [my] is unauthorized for user [foo] with effective roles [] (assigned roles [foo-role] were not found) because **no remote indices privileges apply for the target cluster**" +} +``` + + +#### Resolution [_resolution_9] + +Grant sufficient `remote_indices` privileges to the local user. + + + + diff --git a/deploy-manage/security.md b/deploy-manage/security.md new file mode 100644 index 000000000..f08464921 --- /dev/null +++ b/deploy-manage/security.md @@ -0,0 +1,43 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-files.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/secure-cluster.html + - https://www.elastic.co/guide/en/kibana/current/xpack-security.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-securing-stack.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-ece.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-security.html + - https://www.elastic.co/guide/en/kibana/current/using-kibana-with-security.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-limitations.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-security-principles.html +--- + +# Security + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Scope notes: this is just communication security - link to users + roles, spaces, monitoring, ++ + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/security-files.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/secure-cluster.md +% - [ ] ./raw-migrated-files/kibana/kibana/xpack-security.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-securing-stack.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-securing-ece.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-security.md +% - [ ] ./raw-migrated-files/kibana/kibana/using-kibana-with-security.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/security-limitations.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/es-security-principles.md + +$$$field-document-limitations$$$ + +$$$alias-limitations$$$ + +$$$preventing-unauthorized-access$$$ + +$$$preserving-data-integrity$$$ + +$$$maintaining-audit-trail$$$ \ No newline at end of file diff --git a/deploy-manage/security/aws-privatelink-traffic-filters.md b/deploy-manage/security/aws-privatelink-traffic-filters.md new file mode 100644 index 000000000..abee75667 --- /dev/null +++ b/deploy-manage/security/aws-privatelink-traffic-filters.md @@ -0,0 +1,39 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-traffic-filtering-vpc.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-traffic-filtering-vpc.html +--- + +# AWS PrivateLink traffic filters + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-traffic-filtering-vpc.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-traffic-filtering-vpc.md +% Notes: suspect this is not relevant to heroku and needs to be removed + +$$$ec-access-the-deployment-over-private-link$$$ + +$$$ec-associate-traffic-filter-private-link-rule-set$$$ + +$$$ec-create-traffic-filter-private-link-rule-set$$$ + +$$$ec-find-your-endpoint$$$ + +$$$ec-private-link-service-names-aliases$$$ + +$$$ec-remove-association-traffic-filter-private-link-rule-set$$$ + +$$$ech-access-the-deployment-over-private-link$$$ + +$$$ech-associate-traffic-filter-private-link-rule-set$$$ + +$$$ech-create-traffic-filter-private-link-rule-set$$$ + +$$$ech-find-your-endpoint$$$ + +$$$ech-private-link-service-names-aliases$$$ + +$$$ech-remove-association-traffic-filter-private-link-rule-set$$$ \ No newline at end of file diff --git a/deploy-manage/security/azure-private-link-traffic-filters.md b/deploy-manage/security/azure-private-link-traffic-filters.md new file mode 100644 index 000000000..e171241ed --- /dev/null +++ b/deploy-manage/security/azure-private-link-traffic-filters.md @@ -0,0 +1,51 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-traffic-filtering-vnet.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-traffic-filtering-vnet.html +--- + +# Azure Private Link traffic filters + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-traffic-filtering-vnet.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-traffic-filtering-vnet.md +% Notes: suspect this is not relevant to heroku and needs to be removed + +$$$ec-azure-access-the-deployment-over-private-link$$$ + +$$$ec-azure-allow-traffic-from-link-id$$$ + +$$$ec-azure-associate-traffic-filter-private-link-rule-set$$$ + +$$$ec-azure-create-traffic-filter-private-link-rule-set$$$ + +$$$ec-azure-remove-association-traffic-filter-private-link-rule-set$$$ + +$$$ec-find-your-resource-id$$$ + +$$$ec-find-your-resource-name$$$ + +$$$ec-private-link-azure-dns$$$ + +$$$ec-private-link-azure-service-aliases$$$ + +$$$ech-azure-access-the-deployment-over-private-link$$$ + +$$$ech-azure-allow-traffic-from-link-id$$$ + +$$$ech-azure-associate-traffic-filter-private-link-rule-set$$$ + +$$$ech-azure-create-traffic-filter-private-link-rule-set$$$ + +$$$ech-azure-remove-association-traffic-filter-private-link-rule-set$$$ + +$$$ech-find-your-resource-id$$$ + +$$$ech-find-your-resource-name$$$ + +$$$ech-private-link-azure-dns$$$ + +$$$ech-private-link-azure-service-aliases$$$ \ No newline at end of file diff --git a/deploy-manage/security/claim-traffic-filter-link-id-ownership-through-api.md b/deploy-manage/security/claim-traffic-filter-link-id-ownership-through-api.md new file mode 100644 index 000000000..5f3618a82 --- /dev/null +++ b/deploy-manage/security/claim-traffic-filter-link-id-ownership-through-api.md @@ -0,0 +1,137 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-claim-traffic-filter-link-id-through-the-api.html +--- + +# Claim traffic filter link ID ownership through the API [ec-claim-traffic-filter-link-id-through-the-api] + +This example demonstrates how to use the Elasticsearch Service RESTful API to claim different types of private link ID (AWS PrivateLink, Azure Private Link, and GCP Private Service Connect). We cover the following examples: + +* [Claim a traffic filter link id](#ec-claim-a-traffic-filter-link-id) + + * [AWS PrivateLink](#ec-claim-aws-privatelink) + * [Azure Private Link](#ec-claim-azure-private-link) + * [GCP Private Service Connect](#ec-claim-gcp-private-service-connect) + +* [List claimed traffic filter link id](#ec-list-claimed-traffic-filter-link-id) +* [Unclaim a traffic filter link id](#ec-unclaim-a-traffic-filter-link-id) + + * [AWS PrivateLink](#ec-unclaim-aws-privatelink) + * [Azure Private Link](#ec-unclaim-azure-private-link) + * [GCP Private Service Connect](#ec-unclaim-gcp-private-service-connect) + + + +## Claim a traffic filter link id [ec-claim-a-traffic-filter-link-id] + + +### AWS PrivateLink [ec-claim-aws-privatelink] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids/_claim \ +-d ' +{ + "region": "eu-west-1", + "link_id": "$VPC_ENDPOINT_ID" +} +' +``` + + +### GCP Private Service Connect [ec-claim-gcp-private-service-connect] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids/_claim \ +-d ' +{ + "region": "gcp-us-central1", + "link_id": "$PSC_CONNECTION_ID" +} +' +``` + + +### Azure Private Link [ec-claim-azure-private-link] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids/_claim \ +-d ' +{ + "region": "azure-eastus2", + "azure_endpoint_name": "$AZURE_ENDPOINT_NAME", + "azure_endpoint_guid": "$AZURE_ENDPOINT_GUID" +} +' +``` + + +## List claimed traffic filter link id [ec-list-claimed-traffic-filter-link-id] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids \ +``` + + +## Unclaim a traffic filter link id [ec-unclaim-a-traffic-filter-link-id] + + +### AWS PrivateLink [ec-unclaim-aws-privatelink] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids/_unclaim \ +-d ' +{ + "region": "eu-west-1", + "link_id": "$VPC_ENDPOINT_ID" +} +' +``` + + +### GCP Private Service Connect [ec-unclaim-gcp-private-service-connect] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids/_unclaim \ +-d ' +{ + "region": "gcp-us-central1", + "link_id": "$PSC_CONNECTION_ID" +} +' +``` + + +### Azure Private Link [ec-unclaim-azure-private-link] + +```sh +curl \ +-H "Authorization: ApiKey $API_KEY" \ +-H 'content-type: application/json' \ +https://api.elastic-cloud.com/api/v1/deployments/traffic-filter/link-ids/_unclaim \ +-d ' +{ + "region": "azure-eastus2", + "azure_endpoint_name": "$AZURE_ENDPOINT_NAME", + "azure_endpoint_guid": "$AZURE_ENDPOINT_GUID" +} +' +``` + diff --git a/deploy-manage/security/different-ca.md b/deploy-manage/security/different-ca.md new file mode 100644 index 000000000..dc6be56af --- /dev/null +++ b/deploy-manage/security/different-ca.md @@ -0,0 +1,306 @@ +--- +navigation_title: "With a different CA" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/update-node-certs-different.html +--- + + + +# Different CA [update-node-certs-different] + + +If you have to trust a new CA from your organization, or you need to generate a new CA yourself, use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. + +## Generate a new certificate for the transport layer [node-certs-different-transport] + +Create a new CA certificate, or get the CA certificate of your organization, and add it to your existing CA truststore. After you finish updating your certificates for all nodes, you can remove the old CA certificate from your truststore (but not before!). + +::::{note} +The following examples use PKCS#12 files, but the same steps apply to JKS keystores. +:::: + + +1. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names and locations of the keystores that are currently in use. You’ll use the same names for your new keystores. + + In this example, the keystore and truststore are using different files. Your configuration might use the same file for both the keystore and the truststore. + + ::::{note} + These instructions assume that the provided certificate is signed by a trusted CA and the verification mode is set to `certificate`. This setting ensures that nodes to not attempt to perform hostname verification. + + :::: + + + ```yaml + xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 + xpack.security.transport.ssl.keystore.type: PKCS12 + xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 + xpack.security.transport.ssl.truststore.type: PKCS12 + xpack.security.transport.ssl.verification_mode: certificate + ``` + +2. On **any** node in your cluster, generate a new CA certificate. You only need to complete this step one time. If you’re using the CA certificate of your organization, then skip this step. + + ```shell + ./bin/elasticsearch-certutil ca --pem + ``` + + ::::{dropdown} Command parameters + `--pem` + : Generates a directory containing a CA certificate and key in PEM format instead of PKCS#12. + + :::: + + + 1. Enter a name for the compressed output file that will contain your certificate and key, or accept the default name of `elastic-stack-ca.zip`. + 2. Unzip the output file. The resulting directory contains a CA certificate (`ca.crt`) and a private key (`ca.key`). + + ::::{important} + Keep these file in a secure location as they contain the private key for your CA. + :::: + +3. On **every** node in your cluster, import the new `ca.crt` certificate into your existing CA truststore. This step ensures that your cluster trusts the new CA certificate. This example uses the Java `keytool` utility to import the certificate into the `elastic-stack-ca.p12` CA truststore. + + ```shell + keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ + -storepass -alias new-ca -file ca.crt + ``` + + ::::{dropdown} Command parameters + `-keystore` + : Name of the truststore that you are importing the new CA certificate into. + + `-storepass` + : Password for the CA truststore. + + `-alias` + : Name that you want to assign to the new CA certificate entry in the keystore. + + `-file` + : Name of the new CA certificate to import. + + :::: + +4. $$$check-ca-truststore$$$ Check that the new CA certificate was added to your truststore. + + ```shell + keytool -keystore config/elastic-stack-ca.p12 -list + ``` + + When prompted, enter the password for the CA truststore. + + The output should contain both the existing CA certificate and your new certificate. If you previously used the `elasticsearch-certutil` tool to generate your keystore, the alias of the old CA defaults to `ca` and the type of entry is `PrivateKeyEntry`. + + + +### Generate a new certificate for each node in your cluster [node-certs-different-nodes] + +Now that your CA truststore is updated, use your new CA certificate to sign a certificate for your nodes. + +::::{note} +If your organization has its own CA, you’ll need to [generate Certificate Signing Requests (CSRs)](https://www.elastic.co/guide/en/elasticsearch/reference/current/certutil.html#certutil-csr). CSRs contain information that your CA uses to generate and sign a security certificate. +:::: + + +1. Using the new CA certificate and key, create a new certificate for your nodes. + + ```shell + ./bin/elasticsearch-certutil cert --ca-cert ca/ca.crt --ca-key ca/ca.key + ``` + + ::::{dropdown} Command parameters + `--ca-cert` + : Specifies the path to your new CA certificate (`ca.crt`) in PEM format. You must also specify the `--ca-key` parameter. + + `--ca-key` + : Specifies the path to the private key (`ca.key`) for your CA certificate. You must also specify the `--ca-cert` parameter. + + :::: + + + 1. Enter a name for the output file or accept the default of `elastic-certificates.p12`. + 2. When prompted, enter a password for your node certificate. + +2. $$$start-rolling-restart-newca$$$On the current node in your cluster where you’re updating the keystore, start a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + Stop at the step indicating **Perform any needed changes**, and then proceed to the next step in this procedure. + +3. Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `elastic-certificates.p12`. + + ::::{important} + If your [keystore password is changing](same-ca.md#cert-password-updates), then save the keystore with a new filename so that {{es}} doesn’t attempt to reload the file before you update the password. + :::: + +4. If you needed to save the new keystore with a new filename, update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. For example: + + ```yaml + xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 + xpack.security.transport.ssl.keystore.type: PKCS12 + xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 + xpack.security.transport.ssl.truststore.type: PKCS12 + ``` + +5. Start the node where you updated the keystore. +6. $$$verify-keystore-newca$$$(Optional) Use the [SSL certificate API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html) to verify that {{es}} loaded the new keystore. + + ```console + GET /_ssl/certificates + ``` + +7. If you’re only updating certificates for the transport layer (and not the HTTP layer), then complete [step 2](#start-rolling-restart-newca) through [step 6](#verify-keystore-newca) one node at a time until you’ve updated all keystores in your cluster. You can then complete the remaining steps for a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + Otherwise, do not complete a rolling restart. Instead, proceed to the steps for generating a new certificate for the HTTP layer. + +8. (Optional) After replacing keystores on each node in your cluster, [list the certificates in your truststore](#check-ca-truststore) and then remove the old CA certificate. + + If you previously used the `elasticsearch-certutil` tool to generate your keystore, the alias of the old CA defaults to `ca` and the type of entry is `PrivateKeyEntry`. + + ```shell + keytool -delete -noprompt -alias ca -keystore config/elastic-stack-ca.p12 \ + -storepass + ``` + + ::::{dropdown} Command parameters + `-alias` + : Name of the keystore alias for the old CA certificate that you want to remove from your truststore. + + :::: + + + +### What’s next? [transport-layer-newca-whatsnext] + +Well done! You’ve updated the keystore for the transport layer. You can also [update the keystore for the HTTP layer](#node-certs-different-http) if necessary. If you’re not updating the keystore for the HTTP layer, then you’re all set. + + +## Generate a new certificate for the HTTP layer [node-certs-different-http] + +You can generate certificates for the HTTP layer using your new CA certificate and private key. Other components such as {{kib}} or any of the Elastic language clients verify this certificate when they connect to {{es}}. + +::::{note} +If your organization has its own CA, you’ll need to [generate Certificate Signing Requests (CSRs)](https://www.elastic.co/guide/en/elasticsearch/reference/current/certutil.html#certutil-csr). CSRs contain information that your CA uses to generate and sign a security certificate instead of using self-signed certificates that the `elasticsearch-certutil` tool generates. +:::: + + +::::{admonition} Update clients to trust the new CA +After generating (but before using) new certificates for the HTTP layer, you need to go to all the clients that connect to {{es}} (such as {{beats}}, {{ls}}, and any language clients) and configure them to also trust the new CA (`ca.crt`) that you generated. + +This process is different for each client, so refer to your client’s documentation for trusting certificates. You’ll [update HTTP encryption between {{kib}} and {{es}}](#node-certs-different-kibana) after generating the necessary certificates in this procedure. + +:::: + + +1. On any node in your cluster where {{es}} is installed, run the {{es}} HTTP certificate tool. + + ```shell + ./bin/elasticsearch-certutil http + ``` + + This command generates a `.zip` file that contains certificates and keys to use with {{es}} and {{kib}}. Each folder contains a `README.txt` explaining how to use these files. + + 1. When asked if you want to generate a CSR, enter `n`. + 2. When asked if you want to use an existing CA, enter `y`. + 3. Enter the absolute path to your **new** CA certificate, such as the path to the `ca.crt` file. + 4. Enter the absolute path to your new CA certificate private key, such as the path to the `ca.key` file. + 5. Enter an expiration value for your certificate. You can enter the validity period in years, months, or days. For example, enter `1y` for one year. + 6. When asked if you want to generate one certificate per node, enter `y`. + + Each certificate will have its own private key, and will be issued for a specific hostname or IP address. + + 7. When prompted, enter the name of the first node in your cluster. Use the same node name as the value for the `node.name` parameter in the `elasticsearch.yml` file. + 8. Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. + + List every hostname and variant used to connect to your cluster over HTTPS. + + 9. Enter the IP addresses that clients can use to connect to your node. + 10. Repeat these steps for each additional node in your cluster. + +2. After generating a certificate for each of your nodes, enter a password for your keystore when prompted. +3. Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains one directory for both {{es}} and {{kib}}. Within the `/elasticsearch` directory is a directory for each node that you specified with its own `http.p12` file. For example: + + ```txt + /node1 + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + + ```txt + /node2 + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + + ```txt + /node3 + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + +4. If necessary, rename each `http.p12` file to match the name of your existing certificate for HTTP client communications. For example, `node1-http.p12`. +5. $$$start-rolling-restart-http-newca$$$On the current node in your cluster where you’re updating the keystore, start a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + Stop at the step indicating **Perform any needed changes**, and then proceed to the next step in this procedure. + +6. Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `node1-http.p12`. + + ::::{important} + If your [keystore password is changing](same-ca.md#cert-password-updates), then save the keystore with a new filename so that {{es}} doesn’t attempt to reload the file before you update the password. + :::: + +7. If you needed to save the new keystore with a new filename, update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. For example: + + ```yaml + xpack.security.http.ssl.enabled: true + xpack.security.http.ssl.keystore.path: node1-http.p12 + ``` + +8. If your keystore password is changing, add the password for your private key to the secure settings in {{es}}. + + ```shell + ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password + ``` + +9. Start the node where you updated the keystore. + + Use the [cat nodes API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-nodes.html) to confirm that the node joined the cluster: + + ```console + GET _cat/nodes + ``` + +10. $$$verify-keystore-http-newca$$$(Optional) Use the [SSL certificate API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html) to verify that {{es}} loaded the new keystore. + + ```console + GET /_ssl/certificates + ``` + +11. One node at a time, complete [step 5](#start-rolling-restart-http-newca) through [step 10](#verify-keystore-http-newca) until you’ve updated all keystores in your cluster. +12. Complete the remaining steps for a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling), beginning with the step to **Reenable shard allocation**. + + +### What’s next? [http-kibana-newca-whatsnext] + +Well done! You’ve updated the keystore for the HTTP layer. You can now [update encryption between {{kib}} and {{es}}](#node-certs-different-kibana). + + +## Update encryption between {{kib}} and {{es}} [node-certs-different-kibana] + +When you ran the `elasticsearch-certutil` tool with the `http` option, it created a `/kibana` directory containing an `elasticsearch-ca.pem` file. You use this file to configure {{kib}} to trust the {{es}} CA for the HTTP layer. + +1. Copy the `elasticsearch-ca.pem` file to the {{kib}} configuration directory, as defined by the `KBN_PATH_CONF` path. + + ::::{note} + `KBN_PATH_CONF` contains the path for the {{kib}} configuration files. If you installed {{kib}} using archive distributions (`zip` or `tar.gz`), the path defaults to `KBN_HOME/config`. If you used package distributions (Debian or RPM), the path defaults to `/etc/kibana`. + :::: + +2. If you modified the filename for the `elasticsearch-ca.pem` file, edit `kibana.yml` and update the configuration to specify the location of the security certificate for the HTTP layer. + + ```yaml + elasticsearch.ssl.certificateAuthorities: KBN_PATH_CONF/elasticsearch-ca.pem + ``` + +3. Restart {{kib}}. + + diff --git a/deploy-manage/security/elastic-cloud-static-ips.md b/deploy-manage/security/elastic-cloud-static-ips.md new file mode 100644 index 000000000..a2a469a3a --- /dev/null +++ b/deploy-manage/security/elastic-cloud-static-ips.md @@ -0,0 +1,133 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-static-ips.html +--- + +# Elastic Cloud Static IPs [ec-static-ips] + +{{ecloud}} provides a range of static IP addresses that enable you to allow or deny IP ranges. There are two types of static IP addresses, [ingress](#ec-ingress) and [egress](#ec-egress), and they each have their own set of use cases. In general, static IPs can be used to introduce network controls (for example, firewall rules) for traffic that goes to and from {{ecloud}} deployments over the Internet. Use of static IPs is not applicable to private cloud service provider connections (for example, AWS/Azure PrivateLink, GCP Private Service Connect). It is important to note that static IP addresses are [subject to change](#ec-warning), and not all [cloud provider regions](#ec-regions) are currently fully supported for ingress and egress static IPs. + + +## Ingress Static IPs: Traffic To Elastic Cloud [ec-ingress] + +Suitable usage of ingress static IPs to introduce network controls: + +* All traffic **towards Elastic Cloud deployments** from the public Internet, your private cloud network over the public Internet, or your on-premises network over the public Internet (e.g. Elasticsearch traffic, Kibana traffic, etc) uses Ingress Static IPs as network destination + +Not suitable usage of ingress static IPs to introduce network controls: + +* Traffic over private cloud service provider connections (e.g. AWS Privatelink, GCP Private Service Connect, Azure Private Link) +* Traffic to the [Cloud Console](http://cloud.elastic.co) +* Traffic to non Elastic Cloud websites and services hosted by Elastic (e.g. www.elastic.co) + + +## Egress Static IPs: Traffic From Elastic Cloud [ec-egress] + +Suitable usage of egress static IPs to introduce network controls: + +* Traffic **from Elastic Cloud deployments** towards the public Internet, your private cloud network over the public Internet, or your on-premises network over the public Internet (e.g. custom Slack alerts, Email alerts, Kibana alerts, etc.) uses Egress Static IPs as network source +* Cross-cluster replication/cross-cluster search traffic **from Elastic Cloud deployments** towards on-premises Elastic Cloud Enterprise deployments protected by on-premises firewalls or Elastic Cloud Enterprise traffic filters + +Not suitable usage of egress static IPs to introduce network controls: + +* Snapshot traffic that stays within the same cloud provider and regional boundaries (e.g. an Elastic Cloud deployment hosted in aws-us-east-1 using an S3 bucket also hosted in aws-us-east-1 as a snapshot repository) + + +## Supported Regions [ec-regions] + +::::{dropdown} **AWS** +| | | | +| --- | --- | --- | +| **Region** | **Ingress Static IPs** | **Egress Static IPs** | +| aws-af-south-1 | No | Yes | +| aws-ap-east-1 | No | Yes | +| aws-ap-northeast-1 | No | Yes | +| aws-ap-northeast-2 | No | Yes | +| aws-ap-south-1 | No | Yes | +| aws-ap-southeast-1 | No | Yes | +| aws-ap-southeast-2 | No | Yes | +| aws-ca-central-1 | No | Yes | +| aws-eu-central-1 | No | Yes | +| aws-eu-north-1 | Yes | Yes | +| aws-eu-south-1 | No | Yes | +| aws-eu-west-1 | No | Yes | +| aws-eu-west-2 | No | Yes | +| aws-eu-west-3 | No | Yes | +| aws-me-south | No | Yes | +| aws-sa-east-1 | Yes | Yes | +| aws-us-east-1 | Yes | Yes | +| aws-us-east-2 | No | Yes | +| aws-us-west-1 | Yes | Yes | +| aws-us-west-2 | No | Yes | + +:::: + + +::::{dropdown} **Azure** +| | | | +| --- | --- | --- | +| **Region** | **Ingress Static IPs** | **Egress Static IPs** | +| azure-australiaeast | Yes | Yes | +| azure-brazilsouth | Yes | Yes | +| azure-canadacentral | Yes | Yes | +| azure-centralindia | Yes | Yes | +| azure-centralus | Yes | Yes | +| azure-eastus | Yes | Yes | +| azure-eastus2 | Yes | Yes | +| azure-francecentral | Yes | Yes | +| azure-japaneast | Yes | Yes | +| azure-northeurope | Yes | Yes | +| azure-southafricanorth | Yes | Yes | +| azure-southcentralus | Yes | Yes | +| azure-southeastasia | Yes | Yes | +| azure-uksouth | Yes | Yes | +| azure-westeurope | Yes | Yes | +| azure-westus2 | Yes | Yes | + +:::: + + +::::{dropdown} **GCP** +| | | | +| --- | --- | --- | +| **Region** | **Ingress Static IPs** | **Egress Static IPs** | +| gcp-asia-east1 | Yes | No | +| gcp-asia-northeast1 | Yes | No | +| gcp-asia-northeast3 | Yes | No | +| gcp-asia-south1 | Yes | No | +| gcp-asia-southeast1 | Yes | No | +| gcp-asia-southeast2 | Yes | No | +| gcp-australia-southeast1 | Yes | No | +| gcp-europe-north1 | Yes | No | +| gcp-europe-west1 | Yes | No | +| gcp-europe-west2 | Yes | No | +| gcp-europe-west3 | Yes | No | +| gcp-europe-west4 | Yes | No | +| gcp-europe-west9 | Yes | No | +| gcp-northamerica-northeast1 | Yes | No | +| gcp-southamerica-east1 | Yes | No | +| gcp-us-central1 | Yes | No | +| gcp-us-east1 | Yes | No | +| gcp-us-east4 | Yes | No | +| gcp-us-west1 | Yes | No | +| gcp-us-west2 | Yes | No | + +:::: + + +::::{warning} +:name: ec-warning + +Static IP ranges are subject to change. You will need to update your firewall rules when they change to prevent service disruptions. We will announce changes at least 8 weeks in advance (see [example](https://status.elastic.co/incidents/1xs411x77wgh)). Please subscribe to the [Elastic Cloud Status Page](https://status.elastic.co/) to remain up to date with any changes to the Static IP ranges which you will need to update at your side. +:::: + + + +## Using Static IPs [ec_using_static_ips] + +The {{ecloud}} range of static IPs is formatted as a simple JSON object and can be found at link: [https://ips.cld.elstc.co/](https://ips.cld.elstc.co/). Any searching, formatting, or filtering can be done on the client side. + +For example: + +`curl -s https://ips.cld.elstc.co/ | jq '.regions["aws-us-east-1"]'` + diff --git a/deploy-manage/security/enabling-cipher-suites-for-stronger-encryption.md b/deploy-manage/security/enabling-cipher-suites-for-stronger-encryption.md new file mode 100644 index 000000000..c3296bfed --- /dev/null +++ b/deploy-manage/security/enabling-cipher-suites-for-stronger-encryption.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ciphers.html +--- + +# Enabling cipher suites for stronger encryption [ciphers] + +The TLS and SSL protocols use a cipher suite that determines the strength of encryption used to protect the data. You may want to increase the strength of encryption used when using a Oracle JVM; the IcedTea OpenJDK ships without these restrictions in place. This step is not required to successfully use encrypted communication. + +The *Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files* enable the use of additional cipher suites for Java in a separate JAR file that you need to add to your Java installation. You can download this JAR file from Oracle’s [download page](http://www.oracle.com/technetwork/java/javase/downloads/index.md). The *JCE Unlimited Strength Jurisdiction Policy Files`* are required for encryption with key lengths greater than 128 bits, such as 256-bit AES encryption. + +After installation, all cipher suites in the JCE are available for use but requires configuration in order to use them. To enable the use of stronger cipher suites with {{es}} {security-features}, configure the [`cipher_suites` parameter](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ssl-tls-settings). + +::::{note} +The *JCE Unlimited Strength Jurisdiction Policy Files* must be installed on all nodes in the cluster to establish an improved level of encryption strength. +:::: + + diff --git a/deploy-manage/security/encrypt-deployment-with-customer-managed-encryption-key.md b/deploy-manage/security/encrypt-deployment-with-customer-managed-encryption-key.md new file mode 100644 index 000000000..57d5e5d2e --- /dev/null +++ b/deploy-manage/security/encrypt-deployment-with-customer-managed-encryption-key.md @@ -0,0 +1,433 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-encrypt-with-cmek.html +--- + +# Encrypt your deployment with a customer-managed encryption key [ec-encrypt-with-cmek] + +By default, Elastic already encrypts your deployment data and snapshots at rest. You can reinforce this mechanism by providing your own encryption key, also known as Bring Your Own Key (BYOK). To do that, you need a customer-managed key that you set up and manage in your cloud provider’s Key Management Service (KMS). + +::::{note} +Encryption at rest using customer-managed keys is only available for the Enterprise subscription level, when creating new deployments. The ability to edit encryption settings for existing deployments will be supported at a later date. +:::: + + +Using a customer-managed key allows you to strengthen the security of your deployment data and snapshot data at rest. Note that if you use a custom snapshot repository different from the one provided by Elastic Cloud, these snapshots are not encrypted with your customer-managed key by default. The encryption happens at the file system level. + + +## How using a customer-managed key helps to improve your data security [ec_how_using_a_customer_managed_key_helps_to_improve_your_data_security] + +Using a customer-managed key helps protect against threats related to the management and control of encryption keys. It does not directly protect against any specific types of attacks or threats. However, the ability to keep control over your own keys can help mitigate certain types of threats such as: + +* **Insider threats.** By using a customer-managed key, Elastic does not have access to your encryption keys [1]. This can help prevent unauthorized access to data by insiders with malicious intent. +* **Compromised physical infrastructure.** If a data center is physically compromised, the hosts are shut off. With customer-managed key encryption, that’s a second layer of protection that any malicious intruder would have to bypass, in addition to the existing built-in hardware encryption. + +Using a customer-managed key can help comply with regulations or security requirements, but it is not a complete security solution by itself. There are other types of threats that it does not protect against. + +[1] You set up your customer-managed keys and their access in your key management service. When you provide a customer-managed key identifier to Elastic Cloud, we do not access or store the cryptographic material associated with that key. Customer-managed keys are not directly used to encrypt deployment or snapshot data. Elastic Cloud accesses your customer-managed keys to encrypt and decrypt data encryption keys, which, in turn, are used to encrypt the data. + +When a deployment encrypted with a customer-managed key is deleted or terminated, its data is locked first before being deleted, ensuring a fully secure deletion process. + + +## Prerequisites [ec_prerequisites_3] + +:::::::{tab-set} + +::::::{tab-item} AWS +* Have permissions on AWS KMS to [create a symmetric AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.md#symmetric-cmks) and to configure AWS IAM roles. +* Consider the cloud regions where you need your deployment to live. Refer to the [list of available regions, deployment templates, and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) supported by Elastic Cloud. +:::::: + +::::::{tab-item} Azure +* Have the following permissions on Azure: + + * Permissions to [create an RSA key](https://learn.microsoft.com/en-us/azure/key-vault/keys/about-keys#key-types-and-protection-methods) in the Azure Key Vault where you want to store your key. + * Membership in the **Application Administrator** role. This is required to create a new service principal for Elastic Cloud in your Azure tenant. + * Permissions to [assign roles in your Key Vault using Access control (IAM)](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli#prerequisites). This is required to grant the service principal access to your key. + +* The Azure Key Vault where the RSA key will be stored must have [purge protection](https://learn.microsoft.com/en-us/azure/key-vault/general/soft-delete-overview#purge-protection) enabled to support the encryption of snapshots. +* Consider the cloud regions where you need your deployment to live. Refer to the [list of available regions, deployment templates, and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) supported by Elastic Cloud. +:::::: + +::::::{tab-item} Google Cloud +* Consider the cloud regions where you need your deployment to live. Refer to the [list of available regions, deployment templates, and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html) supported by Elastic Cloud. +* Have the following permissions in Google Cloud KMS: + + * Permissions to [create a KMS key](https://cloud.google.com/kms/docs/create-key) on a key ring in the same region as your deployment. If you don’t have a key ring in the same region, or want to store the key in its own key ring, then you also need permissions to [create a key ring](https://cloud.google.com/kms/docs/create-key-ring). + * Permissions to [manage access to your new key resource using IAM](https://cloud.google.com/kms/docs/iam). This is required to grant the service principals used by Elastic access to your key. +:::::: + +::::::: + +## Know before you go [ec_know_before_you_go] + +At this time, the following features are not supported: + +* Encrypting existing deployments with a customer-managed key +* Disabling encryption on a deployment +* AWS: + + * Encrypting deployments using keys from [key stores external to AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.md) + +* Azure: + + * Encrypting deployments using Azure EC or symmetric keys + * Encrypting deployments using keys from [key stores external to Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/keys/byok-specification) + +* Google Cloud: + + * Encrypting deployments using [key stores external to Cloud KMS](https://cloud.google.com/kms/docs/ekm) + + + +## Create an encryption key for your deployment [create-encryption-key] + +:::::::{tab-set} + +::::::{tab-item} AWS +1. Create a symmetric [single-region key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.md) or [multi-region replica key](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-replicate.md). The key must be available in each region in which you have deployments to encrypt. You can use the same key to encrypt multiple deployments. Later, you will need to provide the Amazon Resource Name (ARN) of that key or key alias to Elastic Cloud. + + ::::{note} + Use an alias ARN instead of the key ARN itself if you plan on doing manual key rotations. When using a key ARN directly, only automatic rotations are supported. + :::: + +2. Apply a key policy with the settings required by Elastic Cloud to the key created in the previous step: + + ```json + { + "Sid": "ElasticKeyAccess", + "Effect": "Allow", + "Principal": { + "AWS": "*" + }, + "Action": [ + "kms:Decrypt", <1> + "kms:Encrypt", <2> + "kms:GetKeyRotationStatus", <3> + "kms:GenerateDataKey", <4> + "kms:DescribeKey" <5> + ], + "Resource": "*", + "Condition": { <6> + "ForAnyValue:StringLike": { + "aws:PrincipalOrgPaths": "o-ygducmlz12/r-e5t3/ou-e5t3-fzpdq76p/ou-e5t3-ysfcmd95/ou-e5t3-hwt05su3/*" + } + } + } + ``` + + 1. [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.md) - This operation is used to decrypt data encryption keys stored on the deployment’s host, as well as decrypting snapshots stored in S3. + 2. [kms:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.md) - This operation is used to encrypt the data encryption keys generated by the KMS as well as encrypting your snapshots. + 3. [kms:GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.md) - This operation is used to determine whether automatic key rotation is enabled. + 4. [kms:GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.md) - This operation is used to generate a data encryption key along with an encrypted version of it. The system leverages the randomness provided by the KMS to produce the data encryption key and your actual customer-managed key to encrypt the data encryption key. + 5. [kms:DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.md) - This operation is used to check whether your key is properly configured for Elastic Cloud. In addition, Elastic Cloud uses this to check if a manual key rotation was performed by comparing underlying key IDs associated with an alias. + 6. This condition allows the accounts associated with the Elastic Cloud production infrastructure to access your key. Under typical circumstances, Elastic Cloud will only be accessing your key via two AWS accounts: the account your deployment’s host is in and the account your S3 bucket containing snapshots is in. However, determining these particular account IDs prior to the deployment creation is not possible at the moment. This encompasses all of the possibilities. For more on this, check the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.md#condition-keys-principalorgpaths). +:::::: + +::::::{tab-item} Azure +1. Create an RSA key in your Key Vault. The key must be available in each region in which you have deployments to encrypt. You can use the same key to encrypt multiple deployments. +2. After the key is created, view the key and note the key identifier. It should look similar to the following: + + * `https://example-byok-key-vault.vault.azure.net/keys/test-key` (without version identifier) + * `https://example-byok-key-vault.vault.azure.net/keys/test-key/1234` (with version identifier) + + Later, you will need to provide this identifier to Elastic Cloud. + + +::::{tip} +Provide your key identifier without the key version identifier so Elastic Cloud can [rotate the key](#rotate-a-customer-managed-key) on your behalf. +:::: +:::::: + +::::::{tab-item} Google Cloud +1. [Create a new symmetric key](https://cloud.google.com/kms/docs/create-key) in Google Cloud KMS. + + The key must be in a key ring that’s in the same region as your deployment. Do not use key ring in a multi-region location. + +2. After the key is created, view the key and [note its resource ID](https://cloud.google.com/kms/docs/getting-resource-ids#getting_the_id_for_a_key_and_version). The resource ID uses the following format: + + `projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME` + + Later, you will need to provide this ID to Elastic Cloud. +:::::: + +::::::: + +## Create a deployment encrypted with your key [ec_create_a_deployment_encrypted_with_your_key] + +:::::::{tab-set} + +::::::{tab-item} AWS +1. Create a new deployment. You can do it from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), or from the API: + + * from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body): + + * Select **Create deployment** from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) home page. + * In the **Settings**, set the **Cloud provider** to **Amazon Web Services** and select a region. + * Expand the **Advanced settings** and turn on **Use a customer-managed encryption key**. An additional field appears to let you specify the ARN of the AWS KMS key or key alias you will use to encrypt your new deployment. + * Configure the rest of your deployment to your convenience, and select **Create deployment**. + + * using the API: + + * Choose a **cloud region** and a **deployment template** (also called hardware profile) for your deployment from the [list of available regions, deployment templates, and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html). + * [Get a valid Elastic Cloud API key](https://www.elastic.co/guide/en/cloud/current/ec-api-authentication.html) with the **Organization owner** role or the **Admin** role on deployments. These roles allow you to create new deployments. + * Get the ARN of the symmetric AWS KMS key or of its alias. Use an alias if you are planning to do manual key rotations as specified in the [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.md). + * Use these parameters to create a new deployment with the [Elastic Cloud API](https://www.elastic.co/guide/en/cloud/current/Deployment_-_CRUD.html). For example: + + ```curl + curl -XPOST \ + -H 'Content-Type: application/json' \ + -H "Authorization: ApiKey " \ + "https://api.elastic-cloud.com/api/v1/deployments?template_id=" \ + -d ' + { + "name": "my-deployment", + "version": "8.15.0", + "region": "us-east-1", + "settings": { + "byok": { + "key_resource_path": "" + } + } + } + ``` + + ::::{tip} + You can also create the deployment from a snapshot of a deployment that was initially not encrypted with a customer-managed key. You can use this as a workaround to encrypt existing data under new deployments using your key, until encrypting existing deployments with a customer-managed key is supported. + :::: + + +The deployment is now created and encrypted using the specified key. Future snapshots will also be encrypted using that key. +:::::: + +::::::{tab-item} Azure +To create a new deployment with a customer-managed key in Azure, you need to perform actions in Elastic Cloud and in your Azure tenant. + +**Step 1: Create a service principal for Elastic Cloud** + +1. In Elastic Cloud, retrieve the Azure application ID: + + * Select **Create deployment** from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) home page. + * In the **Settings**, set the **Cloud provider** to **Azure** and select a region. + * Expand the **Advanced settings** and turn on **Use a customer-managed encryption key**. + * Copy the **Azure application ID**. + +2. Using the ID that you copied, [create a new service principal](https://learn.microsoft.com/en-us/azure/storage/common/customer-managed-keys-configure-cross-tenant-existing-account?tabs=azure-portal#the-customer-installs-the-service-provider-application-in-the-customer-tenant) for Elastic Cloud in your Azure tenant. The service principal grants Elastic Cloud access to interact with your RSA key. + + For example, you might use the following Azure CLI command to create the service principal: + + ```bash + az ad sp create --id + ``` + + ::::{tip} + The user performing this action needs to belong to the **Application Administrator** role. + :::: + + + After it’s created, the service principal appears as `ess-byok-multitenant-app-production` in your Azure tenant. + +3. In your Azure Portal, view the key [that you created](#create-encryption-key). In the **Access control (IAM)** settings for the key, grant the service principal the role **Key Vault Crypto User**. + +**Step 2: Create your deployment**
+ +After you have created the service principal and granted it the necessary permissions, you can finish creating your deployment. You can do so from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), or from the API. + +* Using the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body): + + * Select **Create deployment** from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) home page. + * In the **Settings**, set the **Cloud provider** to **Azure** and select a region. + * Expand the **Advanced settings** and turn on **Use a customer-managed encryption key**. + * Enter the Azure key identifier for the RSA key that you created. + * Configure the rest of your deployment according to your requirements, and then select **Create deployment**. + +* Using the API: + + * Choose a **cloud region** and a **deployment template** (also called hardware profile) for your deployment from the [list of available regions, deployment templates, and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html). + + * [Get a valid Elastic Cloud API key](https://www.elastic.co/guide/en/cloud/current/ec-api-authentication.html) with the **Organization owner** role or the **Admin** role on deployments. These roles allow you to create new deployments. + * Use these parameters to create a new deployment with the [Elastic Cloud API](https://www.elastic.co/guide/en/cloud/current/Deployment_-_CRUD.html). For example: + + ```curl + curl -XPOST \ + -H 'Content-Type: application/json' \ + -H "Authorization: ApiKey " \ + "https://api.elastic-cloud.com/api/v1/deployments?template_id=" \ + -d ' + { + "name": "my-deployment", + "version": "8.15.0", + "region": "azure-eastus", + "settings": { + "byok": { + "key_resource_path": "" + } + } + } + ``` + + ::::{tip} + You can also create the deployment from a snapshot of a deployment that was initially not encrypted with a customer-managed key. You can use this as a workaround to encrypt existing data under new deployments using your key, until encrypting existing deployments with a customer-managed key is supported. + :::: + + +The deployment is now created and encrypted using the specified key. Future snapshots will also be encrypted using that key. +:::::: + +::::::{tab-item} Google Cloud +**Step 1: Grant service principals access to your key** + +Elastic Cloud uses two service principals to encrypt and decrypt data using your key. You must grant these services access to your key before you create your deployment. + +* **Google Cloud Platform cloud storage service agent**: Used for Elastic-managed snapshots stored on Google Cloud Storage. +* **Elastic service account**: Used for all other Elasticsearch data. + +1. In Elastic Cloud, retrieve the email addresses for the service principals that will be used by Elastic: + + * Select **Create deployment** from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) home page. + * In the **Settings**, set the **Cloud provider** to **Google Cloud** and select a region. + * Expand the **Advanced settings** and turn on **Use a customer-managed encryption key**. + * Note the **Elastic service account** and **Google Cloud Platform storage service agent** email addresses. + +2. For each email address that you copied, [grant them](https://cloud.google.com/kms/docs/iam#granting_roles_on_a_resource) the following roles on the key resource: + + * **Elastic service account**: + + * `cloudkms.cryptoKeyVersions.useToDecrypt` + * `cloudkms.cryptoKeyVersions.useToEncrypt` + * `cloudkms.cryptoKeys.get` + + * **Google Cloud Platform cloud storage service agent**: + + * `cloudkms.cryptoKeyVersions.useToDecrypt` + * `cloudkms.cryptoKeyVersions.useToEncrypt` + + +::::{tip} +The user performing this action needs to belong to the **Owner** or **Cloud KMS Admin** role. +:::: + + +**Step 2: Create your deployment** + +After you have granted the Elastic principals the necessary roles, you can finish creating your deployment. You can do so from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body), or from the API. + +* Using the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body): + + * Select **Create deployment** from the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body) home page. + * In the **Settings**, set the **Cloud provider** to **Google Cloud** and select a region. + * Expand the **Advanced settings** and turn on **Use a customer-managed encryption key**. + * Enter the resource ID for the key that you created. + * Configure the rest of your deployment according to your requirements, and then select **Create deployment**. + +* Using the API: + + * Choose a **cloud region** and a **deployment template** (also called hardware profile) for your deployment from the [list of available regions, deployment templates, and instance configurations](https://www.elastic.co/guide/en/cloud/current/ec-regions-templates-instances.html). + + * [Get a valid Elastic Cloud API key](https://www.elastic.co/guide/en/cloud/current/ec-api-authentication.html) with the **Organization owner** role or the **Admin** role on deployments. These roles allow you to create new deployments. + * Use these parameters to create a new deployment with the [Elastic Cloud API](https://www.elastic.co/guide/en/cloud/current/Deployment_-_CRUD.html). For example: + + ```curl + curl -XPOST \ + -H 'Content-Type: application/json' \ + -H "Authorization: ApiKey " \ + "https://api.elastic-cloud.com/api/v1/deployments?template_id=" \ + -d ' + { + "name": "my-deployment", + "version": "8.15.0", + "region": "gcp-us-east1", + "settings": { + "byok": { + "key_resource_path": "" + } + } + } + ``` + + ::::{tip} + You can also create the deployment from a snapshot of a deployment that was initially not encrypted with a customer-managed key. You can use this as a workaround to encrypt existing data under new deployments using your key, until encrypting existing deployments with a customer-managed key is supported. + :::: + + +The deployment is now created and encrypted using the specified key. Future snapshots will also be encrypted using that key. +:::::: + +::::::: +You can check that your hosted deployment is correctly encrypted with the key you specified. To do that, go to the deployment’s **Security** page and select **Manage encryption key** in **Encryption at rest**. + + +## Rotate a customer-managed key [rotate-a-customer-managed-key] + +:::::::{tab-set} + +::::::{tab-item} AWS +Elastic Cloud will automatically rotate the keys every 31 days as a security best practice. + +You can also trigger a manual rotation [in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.md), which will take effect in Elastic Cloud within 30 minutes. **For manual rotations to work, you must use an alias when creating the deployment. We do not currently support [on-demand rotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.md) but plan on supporting this in the future.** +:::::: + +::::::{tab-item} Azure +To rotate your key, you can [update your key version](https://learn.microsoft.com/en-us/azure/container-registry/tutorial-rotate-revoke-customer-managed-keys) or [configure a key rotation policy](https://learn.microsoft.com/en-us/azure/key-vault/keys/how-to-configure-key-rotation) in Azure Key Vault. In both cases, the rotation will take effect in Elastic Cloud within a day. + +For rotations to work, you must provide your key identifier without the key version identifier when you create your deployment. + +Elastic Cloud does not currently support rotating your key using a new key identifier. +:::::: + +::::::{tab-item} Google Cloud +Key rotations are triggered in Google Cloud. You can rotate your key [manually](https://cloud.google.com/kms/docs/rotate-key#manual) or [automatically](https://cloud.google.com/kms/docs/rotate-key#automatic). In both cases, the rotation will take effect in Elastic Cloud within a day. +:::::: + +::::::: + +## Revoke a customer-managed key [ec_revoke_a_customer_managed_key] + +Revoking a customer-managed key in your key management service can be a break-glass procedure in case of a security breach. Elastic Cloud gets an error if an encryption key is disabled, deleted, or if the appropriate role is removed from the IAM policy. Within 30 minutes maximum, Elastic Cloud locks the directories in which your deployment data live and prompts you to delete your deployment as an increased security measure. + +If that happens and this is not intended, you can restore the key in the key management system. Your deployment operations will resume when the key can be reached again. For more details, check [Troubleshooting](#ec-encrypt-with-cmek-troubleshooting). + +When a customer-managed key is permanently revoked and isn’t restored, the data stored in Elastic Cloud is effectively crypto-shredded. + +In a future release of Elastic Cloud, you will be able to: + +* Remove a customer-managed key and revert your deployment to using an Elastic-managed encryption. +* Edit the customer-managed key in use in a deployment to re-encrypt it with a different key. + + +## Encrypt an existing deployment using a new customer-managed key [ec_encrypt_an_existing_deployment_using_a_new_customer_managed_key] + +Encrypting deployments with a customer-managed key is currently only possible for new deployments. In a future release of Elastic Cloud, you will be able to: + +* Encrypt an existing Elastic Cloud deployment with a customer-managed key. +* Edit the customer-managed key in use in a deployment to re-encrypt it with a different key. + + +## Troubleshooting [ec-encrypt-with-cmek-troubleshooting] + +**My deployment became inaccessible. What’s causing this?** + +When Elastic Cloud can’t reach the encryption key, your deployment may become inaccessible. The most common reasons for this issue are: + +* Connectivity issues between Elastic Cloud and the KMS.
+ + When Elastic Cloud is unable to access the customer-managed key, Elastic is alerted and will work to identify the cause. Elastic does not pause or terminate deployment instances when detecting connectivity issues, but your deployment may be inaccessible until issues are fixed. + +* The customer-managed key was deleted or revoked on the KMS.
+ + Restore or recover your key, and if need be, rotate your key and associate a new key before deleting your old key. Elastic Cloud will send you alerts prompting you to restore the key if it cannot access your key and your deployment is not operational.
+ + Within 30 minutes maximum, Elastic Cloud locks the directories in which your deployment data live and prompts you to delete your deployment as an increased security measure.
+ + While it is locked, the deployment retains all data but is not readable or writable*: + + * If access to the key is never restored, the deployment data does not become accessible again + * When restoring access to the key, the deployment becomes operational again: + + * If Elastic didn’t have to perform any platform operations on your instances during the locked period, operations are restored with minimum downtime. + * If Elastic performed some platform operations on your instances during the locked period, restoring operations can require some downtime. It’s also possible that some data can’t be restored** depending on the available snapshots. + + +**During the locked directory period, Elastic may need to perform platform operations on the machines hosting your instances that result in data loss on the Elasticsearch data nodes but not the deployment snapshots.* + +***Elastic recommends that you keep snapshots of your deployment in custom snapshot repositories in your own CSP account for data recovery purposes.* diff --git a/deploy-manage/security/encrypt-deployment.md b/deploy-manage/security/encrypt-deployment.md new file mode 100644 index 000000000..37095fb51 --- /dev/null +++ b/deploy-manage/security/encrypt-deployment.md @@ -0,0 +1,5 @@ +# Encrypt your deployment + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 \ No newline at end of file diff --git a/deploy-manage/security/fips-140-2.md b/deploy-manage/security/fips-140-2.md new file mode 100644 index 000000000..eb9bdfc48 --- /dev/null +++ b/deploy-manage/security/fips-140-2.md @@ -0,0 +1,40 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/fips-140-compliance.html + - https://www.elastic.co/guide/en/kibana/current/xpack-security-fips-140-2.html +--- + +# FIPS 140-2 + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Scope notes: link to Deploy a FIPS compatible version of ECK + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/fips-140-compliance.md +% - [ ] ./raw-migrated-files/kibana/kibana/xpack-security-fips-140-2.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$configuring-es-yml$$$ + +$$$fips-cached-password-hashing$$$ + +$$$fips-limitations$$$ + +$$$fips-stored-password-hashing$$$ + +$$$fips-tls$$$ + +$$$fips-upgrade-considerations$$$ + +$$$java-security-manager$$$ + +$$$java-security-provider$$$ + +$$$keystore-fips-password$$$ + +$$$verify-security-provider$$$ \ No newline at end of file diff --git a/deploy-manage/security/gcp-private-service-connect-traffic-filters.md b/deploy-manage/security/gcp-private-service-connect-traffic-filters.md new file mode 100644 index 000000000..6c0a17db0 --- /dev/null +++ b/deploy-manage/security/gcp-private-service-connect-traffic-filters.md @@ -0,0 +1,39 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-traffic-filtering-psc.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-traffic-filtering-psc.html +--- + +# GCP Private Service Connect traffic filters + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-traffic-filtering-psc.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-traffic-filtering-psc.md +% Notes: suspect this is not relevant to heroku and needs to be removed + +$$$ec-find-your-psc-connection-id$$$ + +$$$ec-private-service-connect-uris$$$ + +$$$ec-psc-access-the-deployment-over-psc$$$ + +$$$ec-psc-associate-traffic-filter-psc-rule-set$$$ + +$$$ec-psc-create-traffic-filter-psc-rule-set$$$ + +$$$ec-psc-remove-association-psc-rule-set$$$ + +$$$ech-find-your-psc-connection-id$$$ + +$$$ech-private-service-connect-uris$$$ + +$$$ech-psc-access-the-deployment-over-psc$$$ + +$$$ech-psc-associate-traffic-filter-psc-rule-set$$$ + +$$$ech-psc-create-traffic-filter-psc-rule-set$$$ + +$$$ech-psc-remove-association-psc-rule-set$$$ \ No newline at end of file diff --git a/deploy-manage/security/httprest-clients-security.md b/deploy-manage/security/httprest-clients-security.md new file mode 100644 index 000000000..7249f64bf --- /dev/null +++ b/deploy-manage/security/httprest-clients-security.md @@ -0,0 +1,80 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/http-clients.html +--- + +# HTTP/REST clients and security [http-clients] + +The {{es}} {security-features} work with standard HTTP [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) headers to authenticate users. Since Elasticsearch is stateless, this header must be sent with every request: + +```shell +Authorization: Basic <1> +``` + +1. The `` is computed as `base64(USERNAME:PASSWORD)` + + +Alternatively, you can use [token-based authentication services](../users-roles/cluster-or-deployment-auth/token-based-authentication-services.md). + + +## Client examples [http-clients-examples] + +This example uses `curl` without basic auth to create an index: + +```shell +curl -XPUT 'localhost:9200/idx' +``` + +```js +{ + "error": "AuthenticationException[Missing authentication token]", + "status": 401 +} +``` + +Since no user is associated with the request above, an authentication error is returned. Now we’ll use `curl` with basic auth to create an index as the `rdeniro` user: + +```shell +curl --user rdeniro:taxidriver -XPUT 'localhost:9200/idx' +``` + +```js +{ + "acknowledged": true +} +``` + + +## Secondary authorization [http-clients-secondary-authorization] + +Some APIs support secondary authorization headers for situations where you want tasks to run with a different set of credentials. For example, you can send the following header in addition to the basic authentication header: + +```shell +es-secondary-authorization: Basic <1> +``` + +1. The `` is computed as `base64(USERNAME:PASSWORD)` + + +The `es-secondary-authorization` header has the same syntax as the `Authorization` header. It therefore also supports the use of [token-based authentication services](../users-roles/cluster-or-deployment-auth/token-based-authentication-services.md). For example: + +```shell +es-secondary-authorization: ApiKey <1> +``` + +1. The `` is computed as `base64(API key ID:API key)` + + + +## Client libraries over HTTP [http-clients-libraries] + +For more information about using {{security-features}} with the language specific clients, refer to: + +* [Java](https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_basic_authentication.html) +* [JavaScript](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/auth-reference.html) +* [.NET](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/configuration.html) +* [Perl](https://metacpan.org/pod/Search::Elasticsearch::Cxn::HTTPTiny#CONFIGURATION) +* [PHP](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/connecting.html) +* [Python](https://elasticsearch-py.readthedocs.io/en/master/#ssl-and-authentication) +* [Ruby](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport#authentication) + diff --git a/deploy-manage/security/ip-traffic-filtering.md b/deploy-manage/security/ip-traffic-filtering.md new file mode 100644 index 000000000..527e8a63c --- /dev/null +++ b/deploy-manage/security/ip-traffic-filtering.md @@ -0,0 +1,34 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-traffic-filtering-ip.html + - https://www.elastic.co/guide/en/cloud/current/ec-traffic-filtering-ip.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-traffic-filtering-ip.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ip-filtering.html +--- + +# IP traffic filtering + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-traffic-filtering-ip.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-traffic-filtering-ip.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-traffic-filtering-ip.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/ip-filtering.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-associate-traffic-filter-ip-rule-set$$$ + +$$$ec-remove-association-traffic-filter-ip-rule-set$$$ + +$$$ece-associate-traffic-filter-ip-rule-set$$$ + +$$$ece-remove-association-traffic-filter-ip-rule-set$$$ + +$$$ech-associate-traffic-filter-ip-rule-set$$$ + +$$$ech-remove-association-traffic-filter-ip-rule-set$$$ \ No newline at end of file diff --git a/deploy-manage/security/kibana-session-management.md b/deploy-manage/security/kibana-session-management.md new file mode 100644 index 000000000..14e45383d --- /dev/null +++ b/deploy-manage/security/kibana-session-management.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/xpack-security-session-management.html +--- + +# Kibana session management [xpack-security-session-management] + +When you log in, {{kib}} creates a session that is used to authenticate subsequent requests to {{kib}}. A session consists of two components: an encrypted cookie that is stored in your browser, and an encrypted document in a dedicated {{es}} hidden index. By default, the name of that index is `.kibana_security_session_1`, where the prefix is derived from the primary `.kibana` index. If either of these components are missing, the session is no longer valid. + +When your session expires, or you log out, {{kib}} will invalidate your cookie and remove session information from the index. {{kib}} also periodically invalidates and removes any expired sessions that weren’t explicitly invalidated. + +To manage user sessions programmatically, {{kib}} exposes [session management APIs](https://www.elastic.co/guide/en/kibana/current/session-management-api.html). For details, check out [Session and cookie security settings](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#security-session-and-cookie-settings). + +## Session idle timeout [session-idle-timeout] + +You can use `xpack.security.session.idleTimeout` to expire sessions after a period of inactivity. This and `xpack.security.session.lifespan` are both highly recommended. By default, sessions expire after 3 days of inactivity. To define another value for a sliding session expiration, set the property in the `kibana.yml` configuration file. The idle timeout is formatted as a duration of `[ms|s|m|h|d|w|M|Y]` (e.g. *20m*, *24h*, *7d*, *1w*). For example, set the idle timeout to expire sessions after 30 minutes of inactivity: + +```yaml +xpack.security.session.idleTimeout: "3d" +``` + + +## Session lifespan [session-lifespan] + +You can use `xpack.security.session.lifespan` to configure the maximum session duration or "lifespan" — also known as the "absolute timeout". This and `xpack.security.session.idleTimeout` are both highly recommended. By default, a maximum session lifespan is 30 days. To define another lifespan, set the property in the `kibana.yml` configuration file. The lifespan is formatted as a duration of `[ms|s|m|h|d|w|M|Y]` (e.g. *20m*, *24h*, *7d*, *1w*). For example, set the lifespan to expire sessions after 7 days: + +```yaml +xpack.security.session.lifespan: "7d" +``` + + +## Session cleanup interval [session-cleanup-interval] + +::::{important} +If you disable session idle timeout and lifespan, then Kibana will not automatically remove session information from the index unless you explicitly log out. This might lead to an infinitely growing session index. As long as either idle timeout or lifespan is configured, Kibana sessions will be cleaned up even if you don’t explicitly log out. + +:::: + + +You can configure the interval at which {{kib}} tries to remove expired and invalid sessions from the session index. By default, this value is 1 hour and cannot be less than 10 seconds. To define another interval, set the `xpack.security.session.cleanupInterval` property in the `kibana.yml` configuration file. The interval is formatted as a duration of `[ms|s|m|h|d|w|M|Y]` (e.g. *20m*, *24h*, *7d*, *1w*). For example, schedule the session index cleanup to perform once a day: + +```yaml +xpack.security.session.cleanupInterval: "1d" +``` + + +## Maximum number of concurrent sessions [session-max-sessions] + +By default, there is no limit to the maximum number of concurrent sessions each user can have in {{kib}}. To add a limit, use the `xpack.security.session.сoncurrentSessions.maxSessions` configuration option. If set, the value of this option should be an integer between `1` and `1000`. When the limit is exceeded, the oldest session is automatically invalidated. + +::::{note} +Due to the rate at which session information is refreshed, there might be a few seconds where the concurrent session limit is not enforced. This is something to consider for use cases where it is common to create multiple sessions simultaneously. +:::: + + +```yaml +xpack.security.session.concurrentSessions: + maxSessions: 3 +``` + + diff --git a/deploy-manage/security/manage-traffic-filtering-through-api.md b/deploy-manage/security/manage-traffic-filtering-through-api.md new file mode 100644 index 000000000..7b03cafa6 --- /dev/null +++ b/deploy-manage/security/manage-traffic-filtering-through-api.md @@ -0,0 +1,48 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-traffic-filtering-through-the-api.html + - https://www.elastic.co/guide/en/cloud/current/ec-traffic-filtering-through-the-api.html +--- + +# Manage traffic filtering through the API + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-traffic-filtering-through-the-api.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-traffic-filtering-through-the-api.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-associate-rule-set-with-a-deployment$$$ + +$$$ec-aws-privatelink-traffic-filters-rule-set$$$ + +$$$ec-azure-privatelink-traffic-filters-rule-set$$$ + +$$$ec-create-a-traffic-filter-rule-set$$$ + +$$$ec-delete-a-rule-set$$$ + +$$$ec-delete-rule-set-association-with-a-deployment$$$ + +$$$ec-gcp-private-service-connect-traffic-filters-rule-set$$$ + +$$$ec-ip-traffic-filters-egress-rule-set$$$ + +$$$ec-ip-traffic-filters-ingress-rule-set$$$ + +$$$ec-update-a-traffic-filter-rule-set$$$ + +$$$ece-associate-rule-set-with-a-deployment$$$ + +$$$ece-create-a-traffic-filter-rule-set$$$ + +$$$ece-delete-a-rule-set$$$ + +$$$ece-delete-rule-set-association-with-a-deployment$$$ + +$$$ece-ip-traffic-filters-ingress-rule-set$$$ + +$$$ece-update-a-traffic-filter-rule-set$$$ \ No newline at end of file diff --git a/deploy-manage/security/manually-configure-security-in-self-managed-cluster.md b/deploy-manage/security/manually-configure-security-in-self-managed-cluster.md new file mode 100644 index 000000000..6a02f3397 --- /dev/null +++ b/deploy-manage/security/manually-configure-security-in-self-managed-cluster.md @@ -0,0 +1,60 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/manually-configure-security.html +--- + +# Manually configure security in a self-managed cluster [manually-configure-security] + +Security needs vary depending on whether you’re developing locally on your laptop or securing all communications in a production environment. Regardless of where you’re deploying the {{stack}} ("ELK"), running a secure cluster is incredibly important to protect your data. That’s why security is [enabled and configured by default](../deploy/self-managed/installing-elasticsearch.md) in {{es}} 8.0 and later. + +If you want to enable security on an existing, unsecured cluster, use your own Certificate Authority (CA), or would rather manually configure security, the following scenarios provide steps for configuring TLS on the transport layer, plus securing HTTPS traffic if you want it. + +If you configure security manually *before* starting your {{es}} nodes, the auto-configuration process will respect your security configuration. You can adjust your TLS configuration at any time, such as [updating node certificates](updating-certificates.md). + +:::{image} ../../images/elasticsearch-reference-elastic-security-overview.png +:alt: Elastic Security layers +::: + + +## Minimal security ({{es}} Development) [security-minimal-overview] + +If you’ve been working with {{es}} and want to enable security on your existing, unsecured cluster, start here. You’ll set passwords for the built-in users to prevent unauthorized access to your local cluster, and also configure password authentication for {{kib}}. + +::::{important} +The minimal security scenario is not sufficient for [production mode](../deploy/self-managed/bootstrap-checks.md#dev-vs-prod-mode) clusters. If your cluster has multiple nodes, you must enable minimal security and then [configure Transport Layer Security (TLS)](secure-cluster-communications.md) between nodes. +:::: + + +[Set up minimal security](set-up-minimal-security.md) + + +## Basic security ({{es}} + {{kib}}) [security-basic-overview] + +This scenario configures TLS for communication between nodes. This security layer requires that nodes verify security certificates, which prevents unauthorized nodes from joining your {{es}} cluster. + +Your external HTTP traffic between {{es}} and {{kib}} won’t be encrypted, but internode communication will be secured. + +[Set up basic security](secure-cluster-communications.md) + + +## Basic security plus secured HTTPS traffic ({{stack}}) [security-basic-https-overview] + +This scenario builds on the one for basic security and secures all HTTP traffic with TLS. In addition to configuring TLS on the transport interface of your {{es}} cluster, you configure TLS on the HTTP interface for both {{es}} and {{kib}}. + +::::{note} +If you need mutual (bidirectional) TLS on the HTTP layer, then you’ll need to configure mutual authenticated encryption. +:::: + + +You then configure {{kib}} and Beats to communicate with {{es}} using TLS so that all communications are encrypted. This level of security is strong, and ensures that any communications in and out of your cluster are secure. + +[Set up basic security plus HTTPS traffic](secure-http-communications.md) + + + + + + + + + diff --git a/deploy-manage/security/private-link-traffic-filters.md b/deploy-manage/security/private-link-traffic-filters.md new file mode 100644 index 000000000..f7d0556d1 --- /dev/null +++ b/deploy-manage/security/private-link-traffic-filters.md @@ -0,0 +1,5 @@ +# Private link traffic filters + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 \ No newline at end of file diff --git a/deploy-manage/security/same-ca.md b/deploy-manage/security/same-ca.md new file mode 100644 index 000000000..e15f978d4 --- /dev/null +++ b/deploy-manage/security/same-ca.md @@ -0,0 +1,212 @@ +--- +navigation_title: "With the same CA" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/update-node-certs-same.html +--- + + + +# Same CA [update-node-certs-same] + + +This procedure assumes that the you have access to the CA certificate and key that was originally generated (or otherwise held by your organization) and used to sign the node certificates currently in use. It also assumes that the clients connecting to {{es}} on the HTTP layer are configured to trust the CA certificate. + +If you have access to the CA used to sign your existing certificates, you only need to replace the certificates and keys for each node in your cluster. If you replace your existing certificates and keys on each node and use the same filenames, {{es}} reloads the files starts using the new certificates and keys. + +You don’t have to restart each node, but doing so forces new TLS connections and is [a recommended practice](updating-certificates.md#use-rolling-restarts) when updating certificates. Therefore, the following steps include a node restart after updating each certificate. + +The following steps provide instructions for generating new node certificates and keys for both the transport layer and the HTTP layer. You might only need to replace one of these layer’s certificates depending on which of your certificates are expiring. + +::::{important} +:name: cert-password-updates + +If your keystore is password protected, the password is stored in the {{es}} secure settings, *and* the password needs to change, then you must perform a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) on your cluster. You must also use a different file name for the keystore so that {{es}} doesn’t reload the file before the node is restarted. +:::: + + +::::{tip} +If your CA has changed, complete the steps in [update security certificates with a different CA](different-ca.md). +:::: + + +## Generate a new certificate for the transport layer [node-certs-same-transport] + +The following examples use PKCS#12 files, but the same steps apply to JKS keystores. + +1. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names and locations of the keystores that are currently in use. You’ll use the same names for your new certificate. + + In this example, the keystore and truststore are pointing to different files. Your configuration might use the same file that contains the certificate and CA. In this case, include the path to that file for both the keystore and truststore. + + ::::{note} + These instructions assume that the provided certificate is signed by a trusted CA and the verification mode is set to `certificate`. This setting ensures that nodes to not attempt to perform hostname verification. + + :::: + + + ```yaml + xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 + xpack.security.transport.ssl.keystore.type: PKCS12 + xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 + xpack.security.transport.ssl.truststore.type: PKCS12 + xpack.security.transport.ssl.verification_mode: certificate + ``` + +2. Using your existing CA, generate a keystore for your nodes. You must use the CA that was used to sign the certificate currently in use. + + ```shell + ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 + ``` + + ::::{dropdown} Command parameters + `--ca ` + : Name of the CA keystore used to sign your certificates. If you used the `elasticsearch-certutil` tool to generate your existing CA, the keystore name defaults to `elastic-stack-ca.p12`. + + :::: + + + 1. Enter a name for the output file or accept the default of `elastic-certificates.p12`. + 2. When prompted, enter a password for the node keystore. + +3. If you entered a password when creating the node keystore that is different from the current keystore password, run the following command to store the password in the {{es}} keystore: + + ```shell + ./bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password + ``` + +4. $$$start-rolling-restart$$$On the current node in your cluster where you’re updating the keystore, start a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + Stop at the step indicating **Perform any needed changes**, and then proceed to the next step in this procedure. + +5. $$$replace-keystores$$$Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `elastic-certificates.p12`. + + ::::{important} + If your [keystore password is changing](#cert-password-updates), then save the keystore with a new filename so that {{es}} doesn’t attempt to reload the file before you update the password. + :::: + +6. If you needed to save the new keystore with a new filename, update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. For example: + + ```yaml + xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 + xpack.security.transport.ssl.keystore.type: PKCS12 + xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 + xpack.security.transport.ssl.truststore.type: PKCS12 + ``` + +7. Start the node where you updated the keystore. +8. $$$verify-keystore$$$(Optional) Use the [SSL certificate API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html) to verify that {{es}} loaded the new keystore. + + ```console + GET /_ssl/certificates + ``` + +9. If you’re only updating certificates for the transport layer (and not the HTTP layer), then complete [step 4](#start-rolling-restart) through [step 8](#verify-keystore) one node at a time until you’ve updated all keystores in your cluster. You can then complete the remaining steps for a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + Otherwise, do not complete a rolling restart. Instead, proceed to the steps for generating a new certificate for the HTTP layer. + + + +### What’s next? [transport-layer-sameca-whatsnext] + +Well done! You’ve updated the keystore for the transport layer. You can also [update the keystore for the HTTP layer](#node-certs-same-http) if necessary. If you’re not updating the keystore for the HTTP layer, then you’re all set. + + +## Generate a new certificate for the HTTP layer [node-certs-same-http] + +Other components such as {{kib}} or any of the Elastic language clients verify this certificate when they connect to {{es}}. + +::::{note} +If your organization has its own CA, you’ll need to [generate Certificate Signing Requests (CSRs)](https://www.elastic.co/guide/en/elasticsearch/reference/current/certutil.html#certutil-csr). CSRs contain information that your CA uses to generate and sign a certificate. +:::: + + +1. On any node in your cluster where {{es}} is installed, run the {{es}} HTTP certificate tool. + + ```shell + ./bin/elasticsearch-certutil http + ``` + + This command generates a `.zip` file that contains certificates and keys to use with {{es}} and {{kib}}. Each folder contains a `README.txt` explaining how to use these files. + + 1. When asked if you want to generate a CSR, enter `n`. + 2. When asked if you want to use an existing CA, enter `y`. + 3. Enter the absolute path to your CA, such as the path to the `elastic-stack-ca.p12` file. + 4. Enter the password for your CA. + 5. Enter an expiration value for your certificate. You can enter the validity period in years, months, or days. For example, enter `1y` for one year. + 6. When asked if you want to generate one certificate per node, enter `y`. + + Each certificate will have its own private key, and will be issued for a specific hostname or IP address. + + 7. When prompted, enter the name of the first node in your cluster. It’s helpful to use the same node name as the value for the `node.name` parameter in the `elasticsearch.yml` file. + 8. Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. + + List every hostname and variant used to connect to your cluster over HTTPS. + + 9. Enter the IP addresses that clients can use to connect to your node. + 10. Repeat these steps for each additional node in your cluster. + +2. After generating a certificate for each of your nodes, enter a password for your private key when prompted. +3. Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains two directories; one each for {{es}} and {{kib}}. Within the `/elasticsearch` directory is a directory for each node that you specified with its own `http.p12` file. For example: + + ```txt + /node1 + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + + ```txt + /node2 + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + + ```txt + /node3 + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + +4. If necessary, rename the `http.p12` file to match the name of your existing certificate for HTTP client communications. For example, `node1-http.p12`. +5. $$$start-rolling-restart-http$$$On the current node in your cluster where you’re updating the keystore, start a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + Stop at the step indicating **Perform any needed changes**, and then proceed to the next step in this procedure. + +6. Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `node1-http.p12`. + + ::::{important} + If your [keystore password is changing](#cert-password-updates), then save the keystore with a new filename so that {{es}} doesn’t attempt to reload the file before you update the password. + :::: + +7. If you needed to save the new keystore with a new filename, update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. For example: + + ```yaml + xpack.security.http.ssl.enabled: true + xpack.security.http.ssl.keystore.path: node1-http.p12 + ``` + +8. If your keystore password is changing, add the password for your private key to the secure settings in {{es}}. + + ```shell + ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password + ``` + +9. Start the node where you updated the keystore. + + Use the [cat nodes API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-nodes.html) to confirm that the node joined the cluster: + + ```console + GET _cat/nodes + ``` + +10. $$$verify-keystore-http$$$(Optional) Use the [SSL certificate API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html) to verify that {{es}} loaded the new keystore. + + ```console + GET /_ssl/certificates + ``` + +11. One node at a time, complete [step 5](#start-rolling-restart-http) through [step 10](#verify-keystore-http) until you’ve updated all keystores in your cluster. +12. Complete the remaining steps for a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling), beginning with the step to **Reenable shard allocation**. + + diff --git a/deploy-manage/security/secure-clients-integrations.md b/deploy-manage/security/secure-clients-integrations.md new file mode 100644 index 000000000..e4520f4e6 --- /dev/null +++ b/deploy-manage/security/secure-clients-integrations.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-clients-integrations.html +--- + +# Secure clients and integrations [security-clients-integrations] + +You will need to update the configuration for several [clients](httprest-clients-security.md) to work with a secured {{es}} cluster. + +The {{es}} {security-features} enable you to secure your {{es}} cluster. But {{es}} itself is only one product within the {{stack}}. It is often the case that other products in the {{stack}} are connected to the cluster and therefore need to be secured as well, or at least communicate with the cluster in a secured way: + +* [Apache Hadoop](https://www.elastic.co/guide/en/elasticsearch/reference/current/hadoop.html) +* [Auditbeat](https://www.elastic.co/guide/en/beats/auditbeat/current/securing-auditbeat.html) +* [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/securing-filebeat.html) +* [{{fleet}} & {{agent}}](https://www.elastic.co/guide/en/fleet/current/secure.html) +* [Heartbeat](https://www.elastic.co/guide/en/beats/heartbeat/current/securing-heartbeat.html) +* [{{kib}}](../security.md) +* [Logstash](https://www.elastic.co/guide/en/logstash/current/ls-security.html) +* [Metricbeat](https://www.elastic.co/guide/en/beats/metricbeat/current/securing-metricbeat.html) +* [Monitoring and security](../monitor.md) +* [Packetbeat](https://www.elastic.co/guide/en/beats/packetbeat/current/securing-packetbeat.html) +* [Reporting](../../explore-analyze/report-and-share.md) +* [Winlogbeat](https://www.elastic.co/guide/en/beats/winlogbeat/current/securing-winlogbeat.html) + + + + diff --git a/deploy-manage/security/secure-cluster-communications.md b/deploy-manage/security/secure-cluster-communications.md new file mode 100644 index 000000000..9b0f9285b --- /dev/null +++ b/deploy-manage/security/secure-cluster-communications.md @@ -0,0 +1,25 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-security.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup.html + - https://www.elastic.co/guide/en/kibana/current/elasticsearch-mutual-tls.html +--- + +# Secure cluster communications + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-security.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/security-basic-setup.md +% Notes: concepts +% - [ ] ./raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$generate-certificates$$$ + +$$$encrypt-internode-communication$$$ \ No newline at end of file diff --git a/deploy-manage/security/secure-endpoints.md b/deploy-manage/security/secure-endpoints.md new file mode 100644 index 000000000..5774bf28c --- /dev/null +++ b/deploy-manage/security/secure-endpoints.md @@ -0,0 +1,31 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-security-principles.html +--- + +# Secure endpoints [es-security-principles] + +Protecting your {{es}} cluster and the data it contains is of utmost importance. Implementing a defense in depth strategy provides multiple layers of security to help safeguard your system. The following principles provide a foundation for running {{es}} in a secure manner that helps to mitigate attacks on your system at multiple levels. + + +## Run {{es}} with security enabled [security-run-with-security] + +Never run an {{es}} cluster without security enabled. This principle cannot be overstated. Running {{es}} without security leaves your cluster exposed to anyone who can send network traffic to {{es}}, permitting these individuals to download, modify, or delete any data in your cluster. [Start the {{stack}} with security enabled](../deploy/self-managed/installing-elasticsearch.md) or [manually configure security](manually-configure-security-in-self-managed-cluster.md) to prevent unauthorized access to your clusters and ensure that internode communication is secure. + + +## Run {{es}} with a dedicated non-root user [security-not-root-user] + +Never try to run {{es}} as the `root` user, which would invalidate any defense strategy and permit a malicious user to do **anything** on your server. You must create a dedicated, unprivileged user to run {{es}}. By default, the `rpm`, `deb`, `docker`, and Windows packages of {{es}} contain an `elasticsearch` user with this scope. + + +## Protect {{es}} from public internet traffic [security-protect-cluster-traffic] + +Even with security enabled, never expose {{es}} to public internet traffic. Using an application to sanitize requests to {{es}} still poses risks, such as a malicious user writing [`_search`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html) requests that could overwhelm an {{es}} cluster and bring it down. Keep {{es}} as isolated as possible, preferably behind a firewall and a VPN. Any internet-facing applications should run pre-canned aggregations, or not run aggregations at all. + +While you absolutely shouldn’t expose {{es}} directly to the internet, you also shouldn’t expose {{es}} directly to users. Instead, use an intermediary application to make requests on behalf of users. This implementation allows you to track user behaviors, such as can submit requests, and to which specific nodes in the cluster. For example, you can implement an application that accepts a search term from a user and funnels it through a [`simple_query_string`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) query. + + +## Implement role based access control [security-create-appropriate-users] + +[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request. + diff --git a/deploy-manage/security/secure-http-communications.md b/deploy-manage/security/secure-http-communications.md new file mode 100644 index 000000000..933f4a529 --- /dev/null +++ b/deploy-manage/security/secure-http-communications.md @@ -0,0 +1,49 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup-https.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-tls-certificates.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-custom-http-certificate.html + - https://www.elastic.co/guide/en/kibana/current/Security-production-considerations.html +--- + +# Secure HTTP communications + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/security-basic-setup-https.md +% Notes: just the relevant section + concepts +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-tls-certificates.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-custom-http-certificate.md +% - [ ] ./raw-migrated-files/kibana/kibana/Security-production-considerations.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$encrypt-kibana-browser$$$ + +$$$encrypt-kibana-http$$$ + +$$$configure-beats-security$$$ + +$$$configuring-tls-browser-kib$$$ + +$$$beats-setup-role$$$ + +$$$beats-monitoring-role$$$ + +$$$beats-writer-role$$$ + +$$$beats-reader-role$$$ + +$$$configure-metricbeat-tls$$$ + +$$$encrypt-http-communication$$$ + +$$$csp-strict-mode$$$ + +$$$k8s-setting-up-your-own-certificate$$$ + +$$$k8s-static-ip-custom-domain$$$ \ No newline at end of file diff --git a/deploy-manage/security/secure-saved-objects.md b/deploy-manage/security/secure-saved-objects.md new file mode 100644 index 000000000..9753ef1be --- /dev/null +++ b/deploy-manage/security/secure-saved-objects.md @@ -0,0 +1,71 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/xpack-security-secure-saved-objects.html +--- + +# Secure saved objects [xpack-security-secure-saved-objects] + +{{kib}} stores entities such as dashboards, visualizations, alerts, actions, and advanced settings as saved objects, which are kept in a dedicated, internal {{es}} index. If such an object includes sensitive information, for example a PagerDuty integration key or email server credentials used by the alert action, {{kib}} encrypts it and makes sure it cannot be accidentally leaked or tampered with. + +Encrypting sensitive information means that a malicious party with access to the {{kib}} internal indices won’t be able to extract that information without also knowing the encryption key. + +Example `kibana.yml`: + +```yaml +xpack.encryptedSavedObjects: + encryptionKey: "min-32-byte-long-strong-encryption-key" +``` + +::::{important} +If you don’t specify an encryption key, {{kib}} might disable features that rely on encrypted saved objects. + +:::: + + +::::{tip} +For help generating the encryption key, refer to the [`kibana-encryption-keys`](https://www.elastic.co/guide/en/kibana/current/kibana-encryption-keys.html) script. + +:::: + + +## Encryption key rotation [encryption-key-rotation] + +Many policies and best practices stipulate that encryption keys should be periodically rotated to decrease the amount of content encrypted with one key and therefore limit the potential damage if the key is compromised. {{kib}} allows you to rotate encryption keys whenever there is a need. + +When you change an encryption key, be sure to keep the old one for some time. Although {{kib}} only uses a new encryption key to encrypt all new and updated data, it still may need the old one to decrypt data that was encrypted using the old key. It’s possible to have multiple old keys used only for decryption. {{kib}} doesn’t automatically re-encrypt existing saved objects with the new encryption key. Re-encryption only happens when you update existing object or use the [rotate encryption key API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-saved-objects). + +Here is how your `kibana.yml` might look if you use key rotation functionality: + +```yaml +xpack.encryptedSavedObjects: + encryptionKey: "min-32-byte-long-NEW-encryption-key" <1> + keyRotation: + decryptionOnlyKeys: ["min-32-byte-long-OLD#1-encryption-key", "min-32-byte-long-OLD#2-encryption-key"] <2> +``` + +1. The encryption key {{kib}} will use to encrypt all new or updated saved objects. This is known as the primary encryption key. +2. A list of encryption keys {{kib}} will try to use to decrypt existing saved objects if decryption with the primary encryption key isn’t possible. These keys are known as the decryption-only or secondary encryption keys. + + +::::{note} +You might also leverage this functionality if multiple {{kib}} instances connected to the same {{es}} cluster use different encryption keys. In this case, you might have a mix of saved objects encrypted with different keys, and every {{kib}} instance can only deal with a specific subset of objects. To fix this, you must choose a single primary encryption key for `xpack.encryptedSavedObjects.encryptionKey`, move all other encryption keys to `xpack.encryptedSavedObjects.keyRotation.decryptionOnlyKeys`, and sync this configuration across all {{kib}} instances. + +:::: + + +At some point, you might want to dispose of old encryption keys completely. Make sure there are no saved objects that {{kib}} encrypted with these encryption keys. You can use the [rotate encryption key API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-saved-objects) to determine which existing saved objects require decryption-only keys and re-encrypt them with the primary key. + + +## Docker configuration [encryption-key-docker-configuration] + +It’s also possible to configure the encryption keys using [Docker environment variables](../deploy/self-managed/install-with-docker.md#environment-variable-config). + +Docker environment variable examples: + +```sh +XPACK_ENCRYPTEDSAVEDOBJECTS_ENCRYPTIONKEY="min-32-byte-long-NEW-encryption-key" +XPACK_ENCRYPTEDSAVEDOBJECTS_KEYROTATION_DECRYPTIONONLYKEYS[0]="min-32-byte-long-OLD#1-encryption-key" +XPACK_ENCRYPTEDSAVEDOBJECTS_KEYROTATION_DECRYPTIONONLYKEYS[1]="min-32-byte-long-OLD#2-encryption-key" +``` + + diff --git a/deploy-manage/security/secure-settings.md b/deploy-manage/security/secure-settings.md new file mode 100644 index 000000000..a4e9ea471 --- /dev/null +++ b/deploy-manage/security/secure-settings.md @@ -0,0 +1,36 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-keystore.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restful-api-examples-configuring-keystore.html + - https://www.elastic.co/guide/en/cloud/current/ec-configuring-keystore.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-configuring-keystore.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-es-secure-settings.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/secure-settings.html + - https://www.elastic.co/guide/en/kibana/current/secure-settings.html +--- + +# Secure your settings + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Scope notes: put UI and API instructions on the same page could consider merging with the page above + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-configuring-keystore.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-restful-api-examples-configuring-keystore.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-configuring-keystore.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-configuring-keystore.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-es-secure-settings.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/secure-settings.md +% - [ ] ./raw-migrated-files/kibana/kibana/secure-settings.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$reloadable-secure-settings$$$ + +$$$ec-add-secret-values$$$ + +$$$change-password$$$ \ No newline at end of file diff --git a/deploy-manage/security/secure-your-cluster-deployment.md b/deploy-manage/security/secure-your-cluster-deployment.md new file mode 100644 index 000000000..1a832a5a4 --- /dev/null +++ b/deploy-manage/security/secure-your-cluster-deployment.md @@ -0,0 +1,40 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/es-security-principles.html + - https://www.elastic.co/guide/en/kibana/current/using-kibana-with-security.html + - https://www.elastic.co/guide/en/elastic-stack/current/install-stack-demo-secure.html +--- + +# Secure your cluster or deployment + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Scope notes: consider keeping the mapped tutorial as a quickstart at some level + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/es-security-principles.md +% - [ ] ./raw-migrated-files/kibana/kibana/using-kibana-with-security.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/install-stack-demo-secure.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$install-stack-demo-secure-agent$$$ + +$$$install-stack-demo-secure-ca$$$ + +$$$install-stack-demo-secure-fleet$$$ + +$$$install-stack-demo-secure-http$$$ + +$$$install-stack-demo-secure-kib-es$$$ + +$$$install-stack-demo-secure-prereqs$$$ + +$$$install-stack-demo-secure-second-node$$$ + +$$$install-stack-demo-secure-transport$$$ + +$$$install-stack-demo-secure-view-data$$$ \ No newline at end of file diff --git a/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation.md b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation.md new file mode 100644 index 000000000..227b8c4f4 --- /dev/null +++ b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation.md @@ -0,0 +1,47 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-considerations.html +--- + +# Secure your Elastic Cloud Enterprise installation [ece-securing-considerations] + +Elastic Cloud Enterprise can run on shared and less secure environments, but you should be aware of some limitations when deploying our product. + + +### Users with admin privileges [ece_users_with_admin_privileges] + +In Elastic Cloud Enterprise 3.8.1, every user who can manage your installation through the Cloud UI or the RESTful API is a user with admin privileges. This includes both the `admin` user and the `readonly` user that get created when you install ECE on your first host. Initially, only the `admin` user has the required privileges to make changes to resources on ECE. + +[Role-based access control](../users-roles/cloud-enterprise-orchestrator/manage-users-roles.md) for Elastic Cloud Enterprise allows you to connect multiple users or user groups to the platform. + +All Elasticsearch clusters come with X-Pack security features and support role-based access control. To learn more, check [Secure Your Clusters](../users-roles/cluster-or-deployment-auth.md). + + +### Clusters share the same resources [ece_clusters_share_the_same_resources] + +The Elasticsearch clusters you create on Elastic Cloud Enterprise share the same resources. It is currently not possible to run a specific cluster on entirely dedicated hardware not shared by other clusters. + + +### Encryption [ece_encryption] + +Elastic Cloud Enterprise does not implement encryption at rest out of the box. To ensure encryption at rest for all data managed by Elastic Cloud Enterprise, the hosts running Elastic Cloud Enterprise must be configured with disk-level encryption, such as dm-crypt. In addition, snapshot targets must ensure that data is encrypted at rest as well. + +Configuring dm-crypt or similar technologies is outside the scope of the Elastic Cloud Enterprise documentation, and issues related to disk encryption are outside the scope of support. + +Elastic Cloud Enterprise provides full encryption of all network traffic by default when using Elasticsearch 6.0 or higher. + +TLS is supported when interacting with the RESTful API of Elastic Cloud Enterprise and for the proxy layer that routes user requests to clusters of all versions. Internally, our administrative services also ensure transport-level encryption. + +In Elasticsearch versions lower than 6.0, traffic between nodes in a cluster and between proxies and the clusters is *not* encrypted. + + +## Attack vectors versus separation of roles [ece-securing-vectors] + +As covered in [Separation of Roles](../deploy/cloud-enterprise/ece-roles.md), it is important to not mix certain roles in a production environment. + +Specifically, a host that is used as an allocator should hold *only* the allocator role. Allocators run the Elasticsearch and Kibana nodes that handle your workloads, which can expose a larger attack surface than the internal admin services. By separating the allocator role from other roles, you reduce any potential security exposure. + +Elastic Cloud Enterprise is designed to ensure that an allocator has access only to the keys necessary to manage the clusters that it has been assigned. If there is a compromise of Elasticsearch or Kibana combined with a zero-day or Linux kernel exploit, for example, this design ensures that the entire Elastic Cloud Enterprise installation or clusters other than those already managed by that allocator are not affected. + +Security comes in layers, and running separate services on separate infrastructure is the last layer of defense, on top of other security features like the JVM security manager, system call filtering, and running nodes in isolated containers with no shared secrets. + diff --git a/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/allow-x509-certificates-signed-with-sha-1.md b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/allow-x509-certificates-signed-with-sha-1.md new file mode 100644 index 000000000..04565dc9c --- /dev/null +++ b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/allow-x509-certificates-signed-with-sha-1.md @@ -0,0 +1,51 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-allow-x509-sha1.html +--- + +# Allow x509 Certificates Signed with SHA-1 [ece-allow-x509-sha1] + +Elastic Cloud Enterprise 3.5.0 and later defaults to rejecting x509 certificates signed with the SHA-1 hash function. This does not apply to self-signed root certificates. Practical attacks against SHA-1 have been demonstrated since 2017 and publicly trusted Certificate Authorities have not issues SHA-1 certificates since 2015. + +You can temporarily bring back the legacy behavior by running the following script. Note that this requires a proxy restart, and support for x509 SHA-1 certificates will be entirely removed in a future release. + +1. On a host that holds the director role: + + ```sh + docker run \ + -v ~/.found-shell:/elastic_cloud_apps/shell/.found-shell \ + --env SHELL_ZK_AUTH=$(docker exec -it frc-directors-director bash -c 'echo -n $FOUND_ZK_READWRITE') $(docker inspect -f '{{ range .HostConfig.ExtraHosts }} --add-host {{.}} {{ end }}' frc-directors-director) \ + --env FOUND_SCRIPT=allowX509Sha1Certs.sc \ + --rm -it \ + $(docker inspect -f '{{ .Config.Image }}' frc-directors-director) \ + /elastic_cloud_apps/shell/run-shell.sh + ``` + +2. On all the proxy hosts: + + ```sh + docker rm -f frc-proxies-proxyv2 + ``` + + +To reset back to the default behavior of rejected x509 certificates signed with the SHA-1 hash function, you can run the following code. + +1. On a host that holds the director role: + + ```sh + docker run \ + -v ~/.found-shell:/elastic_cloud_apps/shell/.found-shell \ + --env SHELL_ZK_AUTH=$(docker exec -it frc-directors-director bash -c 'echo -n $FOUND_ZK_READWRITE') $(docker inspect -f '{{ range .HostConfig.ExtraHosts }} --add-host {{.}} {{ end }}' frc-directors-director) \ + --env FOUND_SCRIPT=rejectX509Sha1Certs.sc \ + --rm -it \ + $(docker inspect -f '{{ .Config.Image }}' frc-directors-director) \ + /elastic_cloud_apps/shell/run-shell.sh + ``` + +2. On all the proxy hosts: + + ```sh + docker rm -f frc-proxies-proxyv2 + ``` + + diff --git a/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/configure-tls-version.md b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/configure-tls-version.md new file mode 100644 index 000000000..92af919ac --- /dev/null +++ b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/configure-tls-version.md @@ -0,0 +1,57 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-tls-version.html +--- + +# Configure the TLS version [ece-configure-tls-version] + +Elastic Cloud Enterprise 2.4.0 and later defaults to minimum TLS version 1.2 with a modern set of cipher suites. + +| | | | +| --- | --- | --- | +| **Elastic Cloud Enterprise version** | **Default minimum TLS version** | **Default allowed cipher suites** | +| 2.4.0 and later | TLS 1.2 | `ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256` | +| 2.3.1 and earlier | TLS 1.0 | `CDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA` | + +You can bring back the legacy behavior by running the following script. Note that this requires a proxy restart. + +1. On a host that holds the director role: + + ```sh + docker run \ + -v ~/.found-shell:/elastic_cloud_apps/shell/.found-shell \ + --env SHELL_ZK_AUTH=$(docker exec -it frc-directors-director bash -c 'echo -n $FOUND_ZK_READWRITE') $(docker inspect -f '{{ range .HostConfig.ExtraHosts }} --add-host {{.}} {{ end }}' frc-directors-director) \ + --env FOUND_SCRIPT=setIntermediateTls.sc \ + --rm -it \ + $(docker inspect -f '{{ .Config.Image }}' frc-directors-director) \ + /elastic_cloud_apps/shell/run-shell.sh + ``` + +2. On all of the proxy hosts: + + ```sh + docker rm -f frc-proxies-proxyv2 + ``` + + +To reset back to the default behavior of using TLSv1.2 and a modern cipher suite, you can run the following code. + +1. On a host that holds the director role: + + ```sh + docker run \ + -v ~/.found-shell:/elastic_cloud_apps/shell/.found-shell \ + --env SHELL_ZK_AUTH=$(docker exec -it frc-directors-director bash -c 'echo -n $FOUND_ZK_READWRITE') $(docker inspect -f '{{ range .HostConfig.ExtraHosts }} --add-host {{.}} {{ end }}' frc-directors-director) \ + --env FOUND_SCRIPT=resetToDefaultTls.sc \ + --rm -it \ + $(docker inspect -f '{{ .Config.Image }}' frc-directors-director) \ + /elastic_cloud_apps/shell/run-shell.sh + ``` + +2. On all of the proxy hosts: + + ```sh + docker rm -f frc-proxies-proxyv2 + ``` + + diff --git a/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md new file mode 100644 index 000000000..d2cf158ae --- /dev/null +++ b/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md @@ -0,0 +1,299 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-certificates.html +--- + +# Manage security certificates [ece-manage-certificates] + +During installation, Elastic Cloud Enterprise generates certificates so that you can connect to your installation securely. In order to connect securely, you must first download and trust the CA certificates generated during installation before issuing any requests to ECE. If your organization operates as its own certificate authority, you can provide your certificates for ECE to avoid a security warning when connecting to the Cloud UI over HTTPS. + +In these instructions, we show you how you can download the security certificate that gets generated during the ECE installation and use it to add your own TLS/SSL certificates. You can add your TLS/SSL certificates any time after you have installed ECE on your hosts. In addition to the steps shown here, you might also need to import your CA certificate into your browser certificate chain, if you don’t already use the same certificate within your organization. + +You can change the certificates for the following ECE components separately: + +Cloud UI certificate +: Used to connect securely to the Cloud UI and to make RESTful API calls. + +Proxy certificate +: Used to connect securely to Elasticsearch clusters and Kibana. You should use a wildcard certificate rooted at the [cluster endpoint that you set](../../deploy/cloud-enterprise/change-endpoint-urls.md) (`*.example.com`, for example). A wildcard certificate is required, because the first label of the DNS address is distinct for Elasticsearch clusters and Kibana (`bc898abb421843918ebc31a513169a.example.com`, for example). + + If you wish to enable [custom endpoint aliases](../../deploy/cloud-enterprise/enable-custom-endpoint-aliases.md) in ECE 2.10 or later, please also follow the directions for adding Subject Alternative Name (SAN) entries to support these aliases. + + ::::{note} + If you plan to deploy [Integration Servers](../../deploy/cloud-enterprise/manage-integrations-server.md), you must add two additional wildcard subdomains, `*.fleet.` and `*.apm.`, to the Subject Alternative Names (SANs) attached to the proxy wildcard certificate. Based on the previous example, your proxy certificates should end up with those three wildcards: `*.example.com, `*.fleet.example.com`, and `*.apm.example.com`. + :::: + + + After the certificates have been installed, connecting securely to Elasticsearch, Kibana, and the Cloud UI or making secure RESTful API calls to ECE should not result in any security warnings or errors. + + + +## Before you begin [ece_before_you_begin_7] + +When uploading the certificate chain to ECE, the following requirements apply: + +* You must upload the full certificate chain, including certificate authorities. +* The chain must be in this order: Private key > SSL certificate > Interim CA (optional) > Root CA. +* The certificates must be in PEM format and the result should be a single file containing the full chain. + +The PEM file should be structured like this: + +```sh +-----BEGIN RSA PRIVATE KEY----- +(Your Private Key: your_domain_name.key) +-----END RSA PRIVATE KEY----- +-----BEGIN CERTIFICATE----- +(Your Primary SSL certificate: your_domain_name.crt) +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +(Your Intermediate certificate: Intermediate.crt) +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +(Your Root certificate: TrustedRoot.crt) +-----END CERTIFICATE----- +``` + +Each key and certificate would be generated by you or your IT team. + + +## Get existing ECE security certificates [ece-existing-security-certificates] + +Obtain the existing certificate generated during the installation of ECE. + +1. You can use the [openssl](https://www.openssl.org/source/) command line tool to display the whole server certificate chain. Run the command against the Cloud UI URL provided at the end of the installation process on your first host, `192.168.43.10:12343` in our example: + + ```sh + openssl s_client -showcerts -connect 192.168.43.10:12343 < /dev/zero + + CONNECTED(00000003) + depth=2 CN = elastic ce master + verify error:num=19:self signed certificate in certificate chain + --- + Certificate chain + 0 s:/CN=elastic ce admin console a954e2668da4 + i:/CN=elastic ce admin console root + -----BEGIN CERTIFICATE----- + MIIDjzCCAnegAwIBAgIGAVqk1eYJMA0GCSqGSIb3DQEBCwUAMCgxJjAkBgNVBAMT + HWVsYXN0aWMgY2UgYWRtaW4gY29uc29sZSByb290MB4XDTE3MDMwNjE4MTYwNVoX + DTI3MDMwNDE4MTYwNVowMDEuMCwGA1UEAxMlZWxhc3RpYyBjZSBhZG1pbiBjb25z + b2xlIGE5NTRlMjY2OGRhNDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB + ALqsQZexkEWoOnhK5uDrGC4kjEWVSWoYOR6ymd8ySHIqhqAZTGoRhiO46jlrCr+e + Jqn3a+qlNNCmEBc5BqjDlKpEKmaLQJoAZock2fOXLiKVQZiJK+ygShoMq2KGpIeY + m/gzQ01atAuETBut8AgpjMN2/xbm3FI0KiqPEpglC8wKQ4hKukbVn5YJBZmBjJxr + 17vzhDpC/qJJ+owRNUoz9vd4VEfDjNhaZWJ8ihDWUCL9rDwVp8XVLUQ38SBurd7A + zJjfzHfrpI9+C8F2UBHjDdqus253Qho5a8S+hGq7VRVqcGoo0nvqThVvR2s0tEDk + fsN0rDOL3or9BwUbv0gIiAECAwEAAaOBtjCBszAsBgNVHREEJTAjggxlY2UtMC1y + dW5uZXKCDTE5Mi4xNjguNDMuMTCHBMCoKwowSQYDVR0jBEIwQIAUgB4X3GsrUoGz + SzJ4IQ8nuB6cosOhIKQeMBwxGjAYBgNVBAMTEWVsYXN0aWMgY2UgbWFzdGVyggYB + WqTVH5EwHQYDVR0OBBYEFA7euGA6jC4XSKCRNt1ZWqABUa/EMAkGA1UdEwQCMAAw + DgYDVR0PAQH/BAQDAgTwMA0GCSqGSIb3DQEBCwUAA4IBAQA9xskIXZ8byN0I+M/R + cXKbvVzsu//gVgswCSZ/KpidWZnSxhuQ4tIryby6DqTKSvzp17ASld1VrYp3vZw+ + zIgU7k7f/w2ATnm39Sn/DxuKUGEblMjUs2X9cF+ijFZklgX1LyWwIK9iKCATuS7J + OThTFGuV0NScsvhiFTTaCXteQql+WwFOI2vL5XZKE8XiQesDiJfNbWg2K/EhxBih + sFPWgik9aljciAHXK/pH9vQNf2rfpSL9HSTc89RetDFkmkXGIPKd3lxORE6wCdKm + mUi6uktMCnBSyMapNEbiWR3sAPf30y81UAVJKcnzd7r8bP3V/19ZBEfvEUSy80DT + th3x + -----END CERTIFICATE----- + 1 s:/CN=elastic ce admin console root + i:/CN=elastic ce master + -----BEGIN CERTIFICATE----- + MIIDUDCCAjigAwIBAgIGAVqk1R+RMA0GCSqGSIb3DQEBCwUAMBwxGjAYBgNVBAMT + EWVsYXN0aWMgY2UgbWFzdGVyMB4XDTE3MDMwNjE4MTUxNVoXDTI3MDMwNDE4MTUx + NVowKDEmMCQGA1UEAxMdZWxhc3RpYyBjZSBhZG1pbiBjb25zb2xlIHJvb3QwggEi + MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCbse8n9LOSSnrBI6KSFieNZKKL + MEjK+TqbA5dYmyC7935Jkpe2aWBhVT2o29+EgKotlWF6/3i+db4SPRVTJ21rLYJu + usPkPr9jkEvKxExPG9hgzvXBQvbgKx4kzw9wEi5Mmh1bEsEBqkQsfXG5Tgk8J+VA + IUIueiqZXhkmZvEx4e7m2rVhxWoVMHkzlQGOmZ77cQ9F68yFeCnbXUrvIIVs1Doj + vFOybEFfYKuMjUqG+i6M0WrvOxij6QHnOfLEBc/Th0ckU60yKFnTYRHaym6xBcZN + oDdkGwl7imbn62jvBUF7VLs7QLnkjF7ExxDksY3uxdcL9+q7BRwFW3bDTWDfAgMB + AAGjgYswgYgwSQYDVR0jBEIwQIAUZdT53vvMI/XLUKahehVoLA5z4RGhIKQeMBwx + GjAYBgNVBAMTEWVsYXN0aWMgY2UgbWFzdGVyggYBWqTVFtIwHQYDVR0OBBYEFIAe + F9xrK1KBs0syeCEPJ7genKLDMAwGA1UdEwQFMAMBAf8wDgYDVR0PAQH/BAQDAgH2 + MA0GCSqGSIb3DQEBCwUAA4IBAQDR6vYhPau8ue0D/+iUha1NA6zAoImSEqr06dGe + fyDJ5BCRWIEXvF4e//th55h/8eObCZhyeDPhcg1u73MWWGub3WO1EFqo4+Se7fKS + 6uz5tTQplfSHI6fUaRzQ6lIClmc5RaAtnV86if/pfcK9Vb0yoLxOR4510gFZTp2x + WRi8Q9E2LHkTYoMxoWZG9CyNrZ1apsV8GE1DG9f8OaxJ99exymVctySQynJqPSPP + S2Xzb6TYzvW6ZiApzAgM6oS2KejA2CRNO+HjNWsJCceBuM8Z60Jq8Rm5Wh1rHjWw + vFJZB0z0J6l/rOKAIIpeoPxoyDr/4RlommC3BRMEcOF0NdTk + -----END CERTIFICATE----- + 2 s:/CN=elastic ce master + i:/CN=elastic ce master + -----BEGIN CERTIFICATE----- + MIIDRDCCAiygAwIBAgIGAVqk1RbSMA0GCSqGSIb3DQEBCwUAMBwxGjAYBgNVBAMT + EWVsYXN0aWMgY2UgbWFzdGVyMB4XDTE3MDMwNjE4MTUxMloXDTI3MDMwNDE4MTUx + MlowHDEaMBgGA1UEAxMRZWxhc3RpYyBjZSBtYXN0ZXIwggEiMA0GCSqGSIb3DQEB + AQUAA4IBDwAwggEKAoIBAQDbwOBtXjKvw4B10HDfoXatlXn8qUHkesV9+lWT0NT1 + WU1X4rc9TwCsWHbH1S0YmOiTw9YVrzFjbYtjNgW5M3DXiewfvnfVm6ifrcuU1C0L + yN8WxqBmvQt/7H2hyKwgsmiXfoULbT5PGuhizvRntlD2OgnPjshwetkRN//O3NWo + Osd2LKMyzUvRPxNP2CwbQLetLgEpQjrjB+nfv4WZHkAQ4vGwxFkN6WaIpqhuhg2q + I8xEHHh1IYTEOiQJZXXg7nU3vqY3kQ2Yu9kopuUJoXY5CviZLZO/xCriNVEPaOhX + 6pWM+dDHaEzx1EiZNg3bjpAXAP+aErSDVAlqbYqCoeAvAgMBAAGjgYswgYgwHQYD + VR0OBBYEFGXU+d77zCP1y1CmoXoVaCwOc+ERMEkGA1UdIwRCMECAFGXU+d77zCP1 + y1CmoXoVaCwOc+ERoSCkHjAcMRowGAYDVQQDExFlbGFzdGljIGNlIG1hc3RlcoIG + AVqk1RbSMAwGA1UdEwQFMAMBAf8wDgYDVR0PAQH/BAQDAgH2MA0GCSqGSIb3DQEB + CwUAA4IBAQBclrkSxPRhN6uxPmJ4QIlZ8OOBKuPPul5434Au8UWAzQX8p6tKLBBT + Zpl9py/fg8YS1iTlPBkRCjssZG9x3x0gG2ftDqrO4AqL7L0X3oZRy+sIkG17h3GI + CcHO596EGzhFPSa183kIwGXb4mI5nNUe43KkDXEyid/VIn27jokeqslfu2KQJnC1 + ggwLRgrNpeNO4pb7cK4aBu3oLZ0tPnhdbIG+bVgHE6a6ZYyBH266oJmNpqmNOTzn + JjrgOt5gEB5JcL1VWXZ3lU3ukd5Jq/rGFkqytBj+uQccpuWkGUMqU82xjREES8D8 + AIHl4ghc6SM1jl2SqZR7aoAjP0uGwW31 + -----END CERTIFICATE----- + --- + Server certificate + subject=/CN=elastic ce admin console a954e2668da4 + issuer=/CN=elastic ce admin console root + --- + No client certificate CA names sent + Peer signing digest: SHA512 + Server Temp Key: ECDH, P-256, 256 bits + --- + SSL handshake has read 3120 bytes and written 433 bytes + --- + New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384 + Server public key is 2048 bit + Secure Renegotiation IS supported + Compression: NONE + Expansion: NONE + No ALPN negotiated + SSL-Session: + Protocol : TLSv1.2 + Cipher : ECDHE-RSA-AES256-GCM-SHA384 + Session-ID: C9FA70D80592981C4174F490EF47AF0091326AED6ED4115CED30A9861EBD7758 + Session-ID-ctx: + Master-Key: 0EF40D4B72E102395352FE7935CAA47CA84BF743E8BF102B98856AFCB76E4BDDCEFDE3E0F7D4D4681A3BCFB170864C9F + Key-Arg : None + PSK identity: None + PSK identity hint: None + SRP username: None + Start Time: 1488824550 + Timeout : 300 (sec) + Verify return code: 19 (self signed certificate in certificate chain) + --- + HTTP/1.1 501 Not Implemented + Server: fac/9431ee + Date: Mon, 06 Mar 2017 18:21:19 GMT + Content-Type: text/plain; charset=UTF-8 + Connection: close + Content-Length: 23 + Unsupported HTTP methodclosed + ``` + +2. Save the last certificate shown in the output to a local file, `elastic-ece-ca-cert.pem` in this example: + + ```sh + cat << EOF > ~/elastic-ece-ca-cert.pem + -----BEGIN CERTIFICATE----- + MIIDRDCCAiygAwIBAgIGAVqk1RbSMA0GCSqGSIb3DQEBCwUAMBwxGjAYBgNVBAMT + EWVsYXN0aWMgY2UgbWFzdGVyMB4XDTE3MDMwNjE4MTUxMloXDTI3MDMwNDE4MTUx + MlowHDEaMBgGA1UEAxMRZWxhc3RpYyBjZSBtYXN0ZXIwggEiMA0GCSqGSIb3DQEB + AQUAA4IBDwAwggEKAoIBAQDbwOBtXjKvw4B10HDfoXatlXn8qUHkesV9+lWT0NT1 + WU1X4rc9TwCsWHbH1S0YmOiTw9YVrzFjbYtjNgW5M3DXiewfvnfVm6ifrcuU1C0L + yN8WxqBmvQt/7H2hyKwgsmiXfoULbT5PGuhizvRntlD2OgnPjshwetkRN//O3NWo + Osd2LKMyzUvRPxNP2CwbQLetLgEpQjrjB+nfv4WZHkAQ4vGwxFkN6WaIpqhuhg2q + I8xEHHh1IYTEOiQJZXXg7nU3vqY3kQ2Yu9kopuUJoXY5CviZLZO/xCriNVEPaOhX + 6pWM+dDHaEzx1EiZNg3bjpAXAP+aErSDVAlqbYqCoeAvAgMBAAGjgYswgYgwHQYD + VR0OBBYEFGXU+d77zCP1y1CmoXoVaCwOc+ERMEkGA1UdIwRCMECAFGXU+d77zCP1 + y1CmoXoVaCwOc+ERoSCkHjAcMRowGAYDVQQDExFlbGFzdGljIGNlIG1hc3RlcoIG + AVqk1RbSMAwGA1UdEwQFMAMBAf8wDgYDVR0PAQH/BAQDAgH2MA0GCSqGSIb3DQEB + CwUAA4IBAQBclrkSxPRhN6uxPmJ4QIlZ8OOBKuPPul5434Au8UWAzQX8p6tKLBBT + Zpl9py/fg8YS1iTlPBkRCjssZG9x3x0gG2ftDqrO4AqL7L0X3oZRy+sIkG17h3GI + CcHO596EGzhFPSa183kIwGXb4mI5nNUe43KkDXEyid/VIn27jokeqslfu2KQJnC1 + ggwLRgrNpeNO4pb7cK4aBu3oLZ0tPnhdbIG+bVgHE6a6ZYyBH266oJmNpqmNOTzn + JjrgOt5gEB5JcL1VWXZ3lU3ukd5Jq/rGFkqytBj+uQccpuWkGUMqU82xjREES8D8 + AIHl4ghc6SM1jl2SqZR7aoAjP0uGwW31 + -----END CERTIFICATE----- + EOF + ``` + + In subsequent steps, this `elastic-ece-ca-cert.pem` file is referred to as the `CA_CERTIFICATE_FILENAME` and used to add your own TLS/SSL certificates. + + + +## Generate a CA certificate and X.509 certificate chain [ece-tls-generate] + +The steps in this section provide high-level instructions on what you need to do if you do not already have a CA certificate and X.509 certificate chain. The method by which you generate the certificate and certificate chain differs by operating system, and the exact steps are outside the scope of these instructions. + +The high-level steps to generate the necessary files include: + +1. Generate a certificate authority (CA) RSA key pair. +2. Create a self-signed CA certificate. +3. Generate a server RSA key pair. +4. Create a certificate signing request (CSR) for server certificate with the common name and the alternative name set. +5. Sign the server CSR with CA key pair. +6. Concatenate the PEM encode server RSA private key, the server certificate, and the CA certificate into a single file. + +Use the concatenated file containing the unencrypted RSA private key, server certificate, and CA certificate when adding your own TLS/SSL certificates in subsequent steps. + +::::{note} +If your organization already uses a CA certificate and X.509 certificate chain, you need to have these files ready. You also need your unencrypted RSA private key. +:::: + + + +## Add a Cloud UI certificate [ece-tls-ui] + +To add a Cloud UI certificate from the Cloud UI: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Under **TLS settings** for the Cloud UI, choose **Upload new certificate** and select a concatenated file containing your RSA private key, server certificate, and CA certificate. Upload the selected file. + +To get the details of the certificate you added, select **Show certificate chain**. + +To add a Cloud UI certificate from the command line: + +1. Add the certificate for the Cloud UI to your ECE installation, where `CA_CERTIFICATE_FILENAME` is the name of the CA certificate you downloaded earlier and `CLOUDUI_PEM_FILENAME` is the name of the concatenated file containing your RSA private key, server certificate, and CA certificate: + + ``` + curl --cacert CA_CERTIFICATE_FILENAME -H 'Content-Type: application/json' --data-binary @CLOUDUI_PEM_FILENAME --user "admin:PASSWORD" "https://admin:12443/api/v1/platform/configuration/security/tls/ui" + ``` + +2. Log out of the Cloud UI and log in again. +3. Verify that you are now using the new certificate chain. There should be no security warnings when you connect to the Cloud UI over HTTPS in your web browser. + + Alternatively, you can also check the certificate using the openssl command: + + ``` + openssl s_client -CAfile CA_CERTIFICATE_FILENAME -showcerts -connect containerhost:12443 < /dev/zero + ``` + + +After adding your certificate, API requests made through the Cloud UI should use your certificate. When you use the `curl` command, include the path to your CA certificate with the `--cacert` parameter. + + +## Add a proxy certificate [ece-tls-proxy] + +To add a proxy certificate from the Cloud UI: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Settings**. +3. Under **TLS settings** for the proxy, choose **Upload new certificate** and select a concatenated file containing your RSA private key, server certificate, and CA certificate. Upload the file. + + To get the details of the certificate you added, select **Show certificate chain**. + + +To add a proxy certificate from the command line: + +1. Add the wildcard certificate chain for the proxy to your ECE installation, where `CA_CERTIFICATE_FILENAME` is the name of the CA certificate you downloaded earlier and `PROXY_PEM_FILENAME` is the name of the concatenated file containing your RSA private key, server certificate, and CA certificate: + + ``` + curl --cacert CA_CERTIFICATE_FILENAME -H 'Content-Type: application/json' --data-binary @PROXY_PEM_FILENAME --user "admin:PASSWORD" "https://admin:12343/api/v1/platform/configuration/security/tls/proxy" + ``` + +2. Log out of any Kibana instances you might be logged into and log in again. +3. Verify that you are now using the new certificate chain. There should be no security warnings when you connect to the Elasticsearch or Kibana endpoints over HTTPS in your web browser. + + Alternatively, you can also use the openssl command to check the proxy certificates, where HOSTNAME_OR_IP is the hostname or IP address of the proxy host: + + ``` + openssl s_client -CAfile CA_CERTIFICATE_FILENAME -showcerts -connect HOSTNAME_OR_IP:9243 < /dev/zero + openssl s_client -CAfile CA_CERTIFICATE_FILENAME -showcerts -connect HOSTNAME_OR_IP:9343 < /dev/zero + ``` + + + +## Limitations [ece-tls-limitations] + +* You cannot add certificates signed by an internal certificate authority to be used for outbound connections. +* In versions 2.6 up to 2.10, some or all platform certificates were generated with a 398-day expiration. If your {{ece}} installation ever ran on these versions, even momentarily before an upgrade, you must rotate the certificates manually before expiry. For details, check [our KB article](https://ela.st/ece-certificate-rotation). + diff --git a/deploy-manage/security/security-certificates-keys.md b/deploy-manage/security/security-certificates-keys.md new file mode 100644 index 000000000..9af860c79 --- /dev/null +++ b/deploy-manage/security/security-certificates-keys.md @@ -0,0 +1,242 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-stack-security.html +--- + +# Security certificates and keys [configuring-stack-security] + +When you start {{es}} for the first time, the following security configuration occurs automatically: + +* [Certificates and keys](../deploy/self-managed/installing-elasticsearch.md#stack-security-certificates) for TLS are generated for the transport and HTTP layers. +* The TLS configuration settings are written to `elasticsearch.yml`. +* A password is generated for the `elastic` user. +* An enrollment token is generated for {{kib}}. + +You can then start {{kib}} and enter the enrollment token, which is valid for 30 minutes. This token automatically applies the security settings from your {{es}} cluster, authenticates to {{es}} with the built-in `kibana` service account, and writes the security configuration to `kibana.yml`. + +::::{note} +There are [some cases](../deploy/self-managed/installing-elasticsearch.md#stack-skip-auto-configuration) where security can’t be configured automatically because the node startup process detects that the node is already part of a cluster, or that security is already configured or explicitly disabled. +:::: + + + +## Prerequisites [_prerequisites_12] + +* [Download](https://www.elastic.co/downloads/elasticsearch) and unpack the `elasticsearch` package distribution for your environment. +* [Download](https://www.elastic.co/downloads/kibana) and unpack the `kibana` package distribution for your environment. + + +## Start {{es}} and enroll {{kib}} with security enabled [stack-start-with-security] + +1. From the installation directory, start {{es}}. + + ```shell + bin/elasticsearch + ``` + + The command prints the `elastic` user password and an enrollment token for {{kib}}. + +2. Copy the generated `elastic` password and enrollment token. These credentials are only shown when you start {{es}} for the first time. + + ::::{note} + If you need to reset the password for the `elastic` user or other built-in users, run the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) tool. To generate new enrollment tokens for {{kib}} or {{es}} nodes, run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool. These tools are available in the {{es}} `bin` directory. + + :::: + + + We recommend storing the `elastic` password as an environment variable in your shell. Example: + + ```sh + export ELASTIC_PASSWORD="your_password" + ``` + +3. (Optional) Open a new terminal and verify that you can connect to your {{es}} cluster by making an authenticated call. + + ```shell + curl --cacert config/certs/http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200 + ``` + +4. From the directory where you installed {{kib}}, start {{kib}}. + + ```shell + bin/kibana + ``` + +5. Enroll {{kib}} using either interactive or detached mode. + + * **Interactive mode** (browser) + + 1. In your terminal, click the generated link to open {{kib}} in your browser. + 2. In your browser, paste the enrollment token that you copied and click the button to connect your {{kib}} instance with {{es}}. + + ::::{note} + {{kib}} won’t enter interactive mode if it detects existing credentials for {{es}} (`elasticsearch.username` and `elasticsearch.password`) or an existing URL for `elasticsearch.hosts`. + + :::: + + * **Detached mode** (non-browser) + + Run the `kibana-setup` tool and pass the generated enrollment token with the `--enrollment-token` parameter. + + ```sh + bin/kibana-setup --enrollment-token + ``` + + + +## Enroll additional nodes in your cluster [stack-enroll-nodes] + +When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to localhost. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration. + +Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically. + +Additionally, only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need to set `transport.host` to a [supported value](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#network-interface-values) (such as uncommenting the suggested value of `0.0.0.0`), or an IP address that’s bound to an interface where other hosts can reach it. Refer to [transport settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#transport-settings) for more information. + +To enroll new nodes in your cluster, create an enrollment token with the `elasticsearch-create-enrollment-token` tool on any existing node in your cluster. You can then start a new node with the `--enrollment-token` parameter so that it joins an existing cluster. + +1. In a separate terminal from where {{es}} is running, navigate to the directory where you installed {{es}} and run the [`elasticsearch-create-enrollment-token`](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-enrollment-token.html) tool to generate an enrollment token for your new nodes. + + ```sh + bin/elasticsearch-create-enrollment-token -s node + ``` + + Copy the enrollment token, which you’ll use to enroll new nodes with your {{es}} cluster. + +2. From the installation directory of your new node, start {{es}} and pass the enrollment token with the `--enrollment-token` parameter. + + ```sh + bin/elasticsearch --enrollment-token + ``` + + {{es}} automatically generates certificates and keys in the following directory: + + ```sh + config/certs + ``` + +3. Repeat the previous step for any new nodes that you want to enroll. + + +## Connect clients to {{es}} [_connect_clients_to_es_5] + +When you start {{es}} for the first time, TLS is configured automatically for the HTTP layer. A CA certificate is generated and stored on disk at: + +```sh +/etc/elasticsearch/certs/http_ca.crt +``` + +The hex-encoded SHA-256 fingerprint of this certificate is also output to the terminal. Any clients that connect to {{es}}, such as the [{{es}} Clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html), {{beats}}, standalone {{agent}}s, and {{ls}} must validate that they trust the certificate that {{es}} uses for HTTPS. {{fleet-server}} and {{fleet}}-managed {{agent}}s are automatically configured to trust the CA certificate. Other clients can establish trust by using either the fingerprint of the CA certificate or the CA certificate itself. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate. You can also copy the CA certificate to your machine and configure your client to use it. + + +### Use the CA fingerprint [_use_the_ca_fingerprint_5] + +Copy the fingerprint value that’s output to your terminal when {{es}} starts, and configure your client to use this fingerprint to establish trust when it connects to {{es}}. + +If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate by running the following command. The path is to the auto-generated CA certificate for the HTTP layer. + +```sh +openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt +``` + +The command returns the security certificate, including the fingerprint. The `issuer` should be `Elasticsearch security auto-configuration HTTP CA`. + +```sh +issuer= /CN=Elasticsearch security auto-configuration HTTP CA +SHA256 Fingerprint= +``` + + +### Use the CA certificate [_use_the_ca_certificate_5] + +If your library doesn’t support a method of validating the fingerprint, the auto-generated CA certificate is created in the following directory on each {{es}} node: + +```sh +/etc/elasticsearch/certs/http_ca.crt +``` + +Copy the `http_ca.crt` file to your machine and configure your client to use this certificate to establish trust when it connects to {{es}}. + + +## What’s next? [_whats_next] + +Congratulations! You’ve successfully started the {{stack}} with security enabled. {{es}} and {{kib}} are secured with TLS on the HTTP layer, and internode communication is encrypted. If you want to enable HTTPS for web traffic, you can [encrypt traffic between your browser and {{kib}}](secure-http-communications.md#encrypt-kibana-browser). + + +## Security certificates and keys [stack-security-certificates] + +When you install {{es}}, the following certificates and keys are generated in the {{es}} configuration directory, which are used to connect a {{kib}} instance to your secured {{es}} cluster and to encrypt internode communication. The files are listed here for reference. + +`http_ca.crt` +: The CA certificate that is used to sign the certificates for the HTTP layer of this {{es}} cluster. + +`http.p12` +: Keystore that contains the key and certificate for the HTTP layer for this node. + +`transport.p12` +: Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster. + +`http.p12` and `transport.p12` are password-protected PKCS#12 keystores. {{es}} stores the passwords for these keystores as [secure settings](secure-settings.md). To retrieve the passwords so that you can inspect or change the keystore contents, use the [`bin/elasticsearch-keystore`](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-keystore.html) tool. + +Use the following command to retrieve the password for `http.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.http.ssl.keystore.secure_password +``` + +Use the following command to retrieve the password for `transport.p12`: + +```sh +bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password +``` + +Additionally, when you use the enrollment token to connect {{kib}} to a secured {{es}} cluster, the HTTP layer CA certificate is retrieved from {{es}} and stored in the {{kib}} `/data` directory. This file establishes trust between {{kib}} and the {{es}} Certificate Authority (CA) for the HTTP layer. + + +## Cases when security auto configuration is skipped [stack-skip-auto-configuration] + +When you start {{es}} for the first time, the node startup process tries to automatically configure security for you. The process runs some checks to determine: + +* If this is the first time that the node is starting +* Whether security is already configured +* If the startup process can modify the node configuration + +If any of those checks fail, there’s a good indication that you [manually configured security](manually-configure-security-in-self-managed-cluster.md), or don’t want security to be configured automatically. In these cases, the node starts normally using the existing configuration. + +::::{important} +If you redirect {{es}} output to a file, security autoconfiguration is skipped. Autoconfigured credentials can only be viewed on the terminal the first time you start {{es}}. If you need to redirect output to a file, start {{es}} without redirection the first time and use redirection on all subsequent starts. +:::: + + + +### Existing environment detected [stack-existing-environment-detected] + +If certain directories already exist, there’s a strong indication that the node was started previously. Similarly, if certain files *don’t* exist, or we can’t read or write to specific files or directories, then we’re likely not running as the user who installed {{es}} or an administrator imposed restrictions. If any of the following environment checks are true, security isn’t configured automatically. + +The {{es}} `/data` directory exists and isn’t empty +: The existence of this directory is a strong indicator that the node was started previously, and might already be part of a cluster. + +The `elasticsearch.yml` file doesn’t exist (or isn’t readable), or the `elasticsearch.keystore` isn’t readable +: If either of these files aren’t readable, we can’t determine whether {{es}} security features are already enabled. This state can also indicate that the node startup process isn’t running as a user with sufficient privileges to modify the node configuration. + +The {{es}} configuration directory isn’t writable +: This state likely indicates that an administrator made this directory read-only, or that the user who is starting {{es}} is not the user that installed {{es}}. + + +### Existing settings detected [stack-existing-settings-detected] + +The following settings are incompatible with security auto configuration. If any of these settings exist, the node startup process skips configuring security automatically and the node starts normally. + +* [`node.roles`](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) is set to a value where the node can’t be elected as `master`, or if the node can’t hold data +* [`xpack.security.autoconfiguration.enabled`](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#general-security-settings) is set to `false` +* [`xpack.security.enabled`](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#general-security-settings) has a value set +* Any of the [`xpack.security.transport.ssl.*`](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#transport-tls-ssl-settings) or [`xpack.security.http.ssl.*`](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#http-tls-ssl-settings) settings have a value set in the `elasticsearch.yml` configuration file or in the `elasticsearch.keystore` +* Any of the `discovery.type`, `discovery.seed_hosts`, or `cluster.initial_master_nodes` [discovery and cluster formation settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-settings.html) have a value set + + ::::{note} + Exceptions are when `discovery.type` is set to `single-node`, or when `cluster.initial_master_nodes` exists but contains only the name of the current node. + + :::: + + diff --git a/deploy-manage/security/set-up-basic-security-plus-https.md b/deploy-manage/security/set-up-basic-security-plus-https.md new file mode 100644 index 000000000..c6f7ec0e0 --- /dev/null +++ b/deploy-manage/security/set-up-basic-security-plus-https.md @@ -0,0 +1,472 @@ +--- +navigation_title: "Set up basic security plus HTTPS" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup-https.html +--- + + + +# Set up basic security plus HTTPS [security-basic-setup-https] + + +When you enable TLS on the HTTP layer it provides an additional layer of security to ensure that all communications to and from your cluster are encrypted. + +When you run the `elasticsearch-certutil` tool in `http` mode, the tool asks several questions about how you want to generate certificates. While there are numerous options, the following choices result in certificates that should work for most environments. + +::::{admonition} Signing certificates +:name: signing-certificates + +The first question that the `elasticsearch-certutil` tool prompts you with is whether you want to generate a Certificate Signing Request (CSR). Answer `n` if you want to sign your own certificates, or `y` if you want to sign certificates with a central CA. + + +#### Sign your own certificates [_sign_your_own_certificates] + +If you want to use the CA that you created when [Generating the certificate authority](secure-cluster-communications.md#generate-certificates) answer `n` when asked if you want to generate a CSR. You then specify the location of your CA, which the tool uses to sign and generate a `.p12` certificate. The steps in this procedure follow this workflow. + + +#### Sign certificates with a central CA [_sign_certificates_with_a_central_ca] + +If you work in an environment with a central security team, they can likely generate a certificate for you. Infrastructure within your organization might already be configured to trust an existing CA, so it may be easier for clients to connect to {{es}} if you use a CSR and send that request to the team that controls your CA. To use a central CA, answer `y` to the first question. + +:::: + + +## Prerequisites [basic-setup-https-prerequisites] + +Complete all steps in [Set up basic security for the Elastic Stack](secure-cluster-communications.md). + + +## Encrypt HTTP client communications for {{es}} [encrypt-http-communication] + +1. On **every** node in your cluster, stop {{es}} and {{kib}} if they are running. +2. On any single node, from the directory where you installed {{es}}, run the {{es}} HTTP certificate tool to generate a Certificate Signing Request (CSR). + + ```shell + ./bin/elasticsearch-certutil http + ``` + + This command generates a `.zip` file that contains certificates and keys to use with {{es}} and {{kib}}. Each folder contains a `README.txt` explaining how to use these files. + + 1. When asked if you want to generate a CSR, enter `n`. + 2. When asked if you want to use an existing CA, enter `y`. + 3. Enter the path to your CA. This is the absolute path to the `elastic-stack-ca.p12` file that you generated for your cluster. + 4. Enter the password for your CA. + 5. Enter an expiration value for your certificate. You can enter the validity period in years, months, or days. For example, enter `90D` for 90 days. + 6. When asked if you want to generate one certificate per node, enter `y`. + + Each certificate will have its own private key, and will be issued for a specific hostname or IP address. + + 7. When prompted, enter the name of the first node in your cluster. Use the same node name that you used when [generating node certificates](secure-cluster-communications.md#generate-certificates). + 8. Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. + + List every hostname and variant used to connect to your cluster over HTTPS. + + 9. Enter the IP addresses that clients can use to connect to your node. + 10. Repeat these steps for each additional node in your cluster. + +3. After generating a certificate for each of your nodes, enter a password for your private key when prompted. +4. Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains one directory for both {{es}} and {{kib}}. + + ```txt + /elasticsearch + |_ README.txt + |_ http.p12 + |_ sample-elasticsearch.yml + ``` + + ```txt + /kibana + |_ README.txt + |_ elasticsearch-ca.pem + |_ sample-kibana.yml + ``` + +5. On **every** node in your cluster, complete the following steps: + + 1. Copy the relevant `http.p12` certificate to the `$ES_PATH_CONF` directory. + 2. Edit the `elasticsearch.yml` file to enable HTTPS security and specify the location of the `http.p12` security certificate. + + ```yaml + xpack.security.http.ssl.enabled: true + xpack.security.http.ssl.keystore.path: http.p12 + ``` + + 3. Add the password for your private key to the secure settings in {{es}}. + + ```shell + ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password + ``` + + 4. Start {{es}}. + + +**Next**: [Encrypt HTTP client communications for {{kib}}](secure-http-communications.md#encrypt-kibana-http) + + +## Encrypt HTTP client communications for {{kib}} [encrypt-kibana-http] + +Browsers send traffic to {{kib}} and {{kib}} sends traffic to {{es}}. These communication channels are configured separately to use TLS. You encrypt traffic between {{kib}} and {{es}}, and then encrypt traffic between your browser and {{kib}}. + +### Encrypt traffic between {{kib}} and {{es}} [encrypt-kibana-elasticsearch] + +When you ran the `elasticsearch-certutil` tool with the `http` option, it created a `/kibana` directory containing an `elasticsearch-ca.pem` file. You use this file to configure {{kib}} to trust the {{es}} CA for the HTTP layer. + +1. Copy the `elasticsearch-ca.pem` file to the {{kib}} configuration directory, as defined by the `$KBN_PATH_CONF` path. +2. Open `kibana.yml` and add the following line to specify the location of the security certificate for the HTTP layer. + + ```yaml + elasticsearch.ssl.certificateAuthorities: $KBN_PATH_CONF/elasticsearch-ca.pem + ``` + +3. Add the following line to specify the HTTPS URL for your {{es}} cluster. + + ```yaml + elasticsearch.hosts: https://:9200 + ``` + +4. Restart {{kib}}. + +:::::{admonition} Connect to a secure monitoring cluster +If the Elastic monitoring features are enabled and you configured a separate {{es}} monitoring cluster, you can also configure {{kib}} to connect to the monitoring cluster via HTTPS. The steps are the same, but each setting is prefixed by `monitoring`. For example, `monitoring.ui.elasticsearch.hosts` and `monitoring.ui.elasticsearch.ssl.truststore.path`. + +::::{note} +You must create a separate `elasticsearch-ca.pem` security file for the monitoring cluster. +:::: + + +::::: + + +**Next**: [Encrypt traffic between your browser and {{kib}}](secure-http-communications.md#encrypt-kibana-browser) + + +### Encrypt traffic between your browser and {{kib}} [encrypt-kibana-browser] + +You create a server certificate and private key for {{kib}}. {{kib}} uses this server certificate and corresponding private key when receiving connections from web browsers. + +When you obtain a server certificate, you must set its subject alternative name (SAN) correctly to ensure that browsers will trust it. You can set one or more SANs to the {{kib}} server’s fully-qualified domain name (FQDN), hostname, or IP address. When choosing the SAN, pick whichever attribute you’ll use to connect to {{kib}} in your browser, which is likely the FQDN. + +The following instructions create a Certificate Signing Request (CSR) for {{kib}}. A CSR contains information that a CA uses to generate and sign a security certificate. The certificate can be trusted (signed by a public, trusted CA) or untrusted (signed by an internal CA). A self-signed or internally-signed certificate is acceptable for development environments and building a proof of concept, but should not be used in a production environment. + +::::{warning} +Before going to production, use a trusted CA such as [Let’s Encrypt](https://letsencrypt.org/) or your organization’s internal CA to sign the certificate. Using a signed certificate establishes browser trust for connections to {{kib}} for internal access or on the public internet. +:::: + + +1. Generate a server certificate and private key for {{kib}}. + + ```shell + ./bin/elasticsearch-certutil csr -name kibana-server -dns example.com,www.example.com + ``` + + The CSR has a common name (CN) of `kibana-server`, a SAN of `example.com`, and another SAN of `www.example.com`. + + This command generates a `csr-bundle.zip` file by default with the following contents: + + ```txt + /kibana-server + |_ kibana-server.csr + |_ kibana-server.key + ``` + +2. Unzip the `csr-bundle.zip` file to obtain the `kibana-server.csr` unsigned security certificate and the `kibana-server.key` unencrypted private key. +3. Send the `kibana-server.csr` certificate signing request to your internal CA or trusted CA for signing to obtain a signed certificate. The signed file can be in different formats, such as a `.crt` file like `kibana-server.crt`. +4. Open `kibana.yml` and add the following lines to configure {{kib}} to access the server certificate and unencrypted private key. + + ```yaml + server.ssl.certificate: $KBN_PATH_CONF/kibana-server.crt + server.ssl.key: $KBN_PATH_CONF/kibana-server.key + ``` + + ::::{note} + `$KBN_PATH_CONF` contains the path for the {{kib}} configuration files. If you installed {{kib}} using archive distributions (`zip` or `tar.gz`), the path defaults to `$KBN_HOME/config`. If you used package distributions (Debian or RPM), the path defaults to `/etc/kibana`. + :::: + +5. Add the following line to `kibana.yml` to enable TLS for inbound connections. + + ```yaml + server.ssl.enabled: true + ``` + +6. Start {{kib}}. + +::::{note} +After making these changes, you must always access {{kib}} via HTTPS. For example, `https://.com`. +:::: + + +**Next**: [Configure {{beats}} security](secure-http-communications.md#configure-beats-security) + + + +## Configure {{beats}} security [configure-beats-security] + +{{beats}} are open source data shippers that you install as agents on your servers to send operational data to {{es}}. Each Beat is a separately installable product. The following steps cover configuring security for {{metricbeat}}. Follow these steps for each [additional Beat](https://www.elastic.co/guide/en/beats/libbeat/current/getting-started.html) you want to configure security for. + +### Prerequisites [_prerequisites_13] + +[Install {{metricbeat}}](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-installation-configuration.html) using your preferred method. + +::::{important} +You cannot connect to the {{stack}} or configure assets for {{metricbeat}} before completing the following steps. +:::: + + + +### Create roles for {{metricbeat}} [_create_roles_for_metricbeat] + +Typically, you need to create the following separate roles: + +* **setup** role for setting up index templates and other dependencies +* **monitoring** role for sending monitoring information +* **writer** role for publishing events collected by {metricbeat} +* **reader** role for Kibana users who need to view and create visualizations that access {{metricbeat}} data + +::::{note} +These instructions assume that you are using the default name for {{metricbeat}} indices. If the indicated index names are not listed, or you are using a custom name, enter it manually when defining roles and modify the privileges to match your index naming pattern. +:::: + + +To create users and roles from Stack Management in {{kib}}, select **Roles** or **Users** from the side navigation. + +**Next**: [Create a setup role](secure-http-communications.md#beats-setup-role) + + +##### Create a setup role and user [beats-setup-role] + +Administrators who set up {{metricbeat}} typically need to load mappings, dashboards, and other objects used to index data into {{es}} and visualize it in {{kib}}. + +::::{warning} +Setting up {{metricbeat}} is an admin-level task that requires extra privileges. As a best practice, grant the setup role to administrators only, and use a more restrictive role for event publishing. +:::: + + +1. Create the setup role: +2. Enter **metricbeat_setup** as the role name. +3. Choose the **monitor** and **manage_ilm** cluster privileges. +4. On the **metricbeat-\** indices, choose the ***manage** and **write** privileges. + + If the **metricbeat-\*** indices aren’t listed, enter that pattern into the list of indices. + +5. Create the setup user: +6. Enter **metricbeat_setup** as the user name. +7. Enter the username, password, and other user details. +8. Assign the following roles to the **metricbeat_setup** user: + + | Role | Purpose | + | --- | --- | + | `metricbeat_setup` | Set up {{metricbeat}}. | + | `kibana_admin` | Load dependencies, such as example dashboards, if available, into {{kib}} | + | `ingest_admin` | Set up index templates and, if available, ingest pipelines | + + +**Next**: [Create a monitoring role](secure-http-communications.md#beats-monitoring-role) + + +##### Create a monitoring role and user [beats-monitoring-role] + +To send monitoring data securely, create a monitoring user and grant it the necessary privileges. + +You can use the built-in `beats_system` user, if it’s available in your environment. Because the built-in users are not available in {{ecloud}}, these instructions create a user that is explicitly used for monitoring {{metricbeat}}. + +1. If you’re using the built-in `beats_system` user, on any node in your cluster, run the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) utility to set the password for that user: + + This command resets the password for the `beats_system` user to an auto-generated value. + + ```shell + ./bin/elasticsearch-reset-password -u beats_system + ``` + + If you want to set the password to a specific value, run the command with the interactive (`-i`) parameter. + + ```shell + ./bin/elasticsearch-reset-password -i -u beats_system + ``` + +2. Create the monitoring role: +3. Enter **metricbeat_monitoring** as the role name. +4. Choose the **monitor** cluster privilege. +5. On the **.monitoring-beats-\** indices, choose the ***create_index** and **create_doc** privileges. +6. Create the monitoring user: +7. Enter **metricbeat_monitoring** as the user name. +8. Enter the username, password, and other user details. +9. Assign the following roles to the **metricbeat_monitoring** user: + + | Role | Purpose | + | --- | --- | + | `metricbeat_monitoring` | Monitor {{metricbeat}}. | + | `kibana_admin` | Use {{kib}} | + | `monitoring_user` | Use Stack Monitoring in {{kib}} to monitor {{metricbeat}} | + + +**Next**: [Create a writer role](secure-http-communications.md#beats-writer-role) + + +##### Create a writer role and user [beats-writer-role] + +Users who publish events to {{es}} need to create and write to {{metricbeat}} indices. To minimize the privileges required by the writer role, use the setup role to pre-load dependencies. This section assumes that you’ve [created the setup role](secure-http-communications.md#beats-setup-role). + +1. Create the writer role: +2. Enter **metricbeat_writer** as the role name. +3. Choose the **monitor** and **read_ilm** cluster privileges. +4. On the **metricbeat-\** indices, choose the ***create_doc***, ***create_index**, and **view_index_metadata** privileges. +5. Create the writer user: +6. Enter **metricbeat_writer** as the user name. +7. Enter the username, password, and other user details. +8. Assign the following roles to the **metricbeat_writer** user: + + | Role | Purpose | + | --- | --- | + | `metricbeat_writer` | Monitor {{metricbeat}} | + | `remote_monitoring_collector` | Collect monitoring metrics from {{metricbeat}} | + | `remote_monitoring_agent` | Send monitoring data to the monitoring cluster | + + +**Next**: [Create a reader role](secure-http-communications.md#beats-reader-role) + + +##### Create a reader role and user [beats-reader-role] + +{{kib}} users typically need to view dashboards and visualizations that contain {{metricbeat}} data. These users might also need to create and edit dashboards and visualizations. Create the reader role to assign proper privileges to these users. + +1. Create the reader role: +2. Enter **metricbeat_reader** as the role name. +3. On the **metricbeat-\*** indices, choose the **read** privilege. +4. Under **Kibana**, click **Add Kibana privilege**. + + * Under **Spaces**, choose **Default**. + * Choose **Read** or **All** for Discover, Visualize, Dashboard, and Metrics. + +5. Create the reader user: +6. Enter **metricbeat_reader** as the user name. +7. Enter the username, password, and other user details. +8. Assign the following roles to the **metricbeat_reader** user: + + | Role | Purpose | + | --- | --- | + | `metricbeat_reader` | Read {{metricbeat}} data. | + | `monitoring_user` | Allow users to monitor the health of {{metricbeat}}itself. Only assign this role to users who manage {{metricbeat}} | + | `beats_admin` | Create and manage configurations in {{beats}} centralmanagement. Only assign this role to users who need to use {{beats}} centralmanagement. | + + +**Next**: [Configure {{metricbeat}} to use TLS](secure-http-communications.md#configure-metricbeat-tls) + + +#### Configure {{metricbeat}} to use TLS [configure-metricbeat-tls] + +Before starting {{metricbeat}}, you configure the connections to {{es}} and {{kib}}. You can configure authentication to send data to your secured cluster using basic authentication, API key authentication, or Public Key Infrastructure (PKI) certificates. + +The following instructions use the credentials for the `metricbeat_writer` and `metricbeat_setup` users that you created. If you need a greater level of security, we recommend using PKI certificates. + +After configuring connections to {{es}} and {{kib}}, you’ll enable the `elasticsearch-xpack` module and configure that module to use HTTPS. + +::::{warning} +In production environments, we strongly recommend using a separate cluster (referred to as the monitoring cluster) to store your data. Using a separate monitoring cluster prevents production cluster outages from impacting your ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. +:::: + + +1. On the node where you [generated certificates for the HTTP layer](secure-http-communications.md#encrypt-http-communication), navigate to the `/kibana` directory. +2. Copy the `elasticsearch-ca.pem` certificate to the directory where you installed {{metricbeat}}. +3. Open the `metricbeat.yml` configuration file and configure the connection to {{es}}. + + Under `output.elasticsearch`, specify the following fields: + + ```yaml + output.elasticsearch: + hosts: [":9200"] + protocol: "https" + username: "metricbeat_writer" + password: "" + ssl: + certificate_authorities: ["elasticsearch-ca.pem"] + verification_mode: "certificate" + ``` + + `hosts` + : Specifies the host where your {{es}} cluster is running. + + `protocol` + : Indicates the protocol to use when connecting to {{es}}. This value must be `https`. + + `username` + : Name of the user with privileges required to publish events to {{es}}. The `metricbeat_writer` user that you created has these privileges. + + `password` + : Password for the indicated `username`. + + `certificate_authorities` + : Indicates the path to the local `.pem` file that contains your CA’s certificate. + +4. Configure the connection to {{kib}}. + + Under `setup.kibana`, specify the following fields: + + ```yaml + setup.kibana + host: "https://:5601" + ssl.enabled: true + username: "metricbeat_setup" + password: "p@ssw0rd" + ``` + + `hosts` + : The URLs of the {{es}} instances to use for all your queries. Ensure that you include `https` in the URL. + + `username` + : Name of the user with privileges required to set up dashboards in {{kib}}. The `metricbeat_setup` user that you created has these privileges. + + `password` + : Password for the indicated `username`. + +5. Enable the `elasticsearch-xpack` module. + + ```shell + ./metricbeat modules enable elasticsearch-xpack + ``` + +6. Modify the `elasticsearch-xpack` module to use HTTPS. This module collects metrics about {{es}}. + + Open `/modules.d/elasticsearch-xpack.yml` and specify the following fields: + + ```yaml + - module: elasticsearch + xpack.enabled: true + period: 10s + hosts: ["https://:9200"] + username: "remote_monitoring_user" + password: "" + ssl: <1> + enabled: true + certificate_authorities: ["elasticsearch-ca.pem"] + verification_mode: "certificate" + ``` + + 1. Configuring SSL is required when monitoring a node with encrypted traffic. See [Configure SSL for {{metricbeat}}](https://www.elastic.co/guide/en/beats/metricbeat/current/configuration-ssl.html).`hosts` + : Specifies the host where your {{es}} cluster is running. Ensure that you include `https` in the URL. + + `username` + : Name of the user with privileges to collect metric data. The built-in `monitoring_user` user has these privileges. Alternatively, you can create a user and assign it the `monitoring_user` role. + + `password` + : Password for the indicated `username`. + + `certificate_authorities` + : Indicates the path to the local `.pem` file that contains your CA’s certificate. + +7. If you want to use the predefined assets for parsing, indexing, and visualizing your data, run the following command to load these assets: + + ```shell + ./metricbeat setup -e + ``` + +8. Start {{es}}, and then start {{metricbeat}}. + + ```shell + ./metricbeat -e + ``` + + `-e` is optional and sends output to standard error instead of the configured log output. + +9. Log in to {{kib}}, open the main menu, and click **Stack Monitoring**. + + You’ll see cluster alerts that require your attention and a summary of the available monitoring metrics for {{es}}. Click any of the header links on the available cards to view additional information. diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md new file mode 100644 index 000000000..458d827c4 --- /dev/null +++ b/deploy-manage/security/set-up-basic-security.md @@ -0,0 +1,137 @@ +--- +navigation_title: "Set up basic security" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup.html +--- + + + +# Set up basic security [security-basic-setup] + + +When you start {{es}} for the first time, passwords are generated for the `elastic` user and TLS is automatically configured for you. If you configure security manually *before* starting your {{es}} nodes, the auto-configuration process will respect your security configuration. You can adjust your TLS configuration at any time, such as [updating node certificates](updating-certificates.md). + +::::{important} +If your cluster has multiple nodes, then you must configure TLS between nodes. [Production mode](../deploy/self-managed/bootstrap-checks.md#dev-vs-prod-mode) clusters will not start if you do not enable TLS. +:::: + + +The transport layer relies on mutual TLS for both encryption and authentication of nodes. Correctly applying TLS ensures that a malicious node cannot join the cluster and exchange data with other nodes. While implementing username and password authentication at the HTTP layer is useful for securing a local cluster, the security of communication between nodes requires TLS. + +Configuring TLS between nodes is the basic security setup to prevent unauthorized nodes from accessing to your cluster. + +::::{admonition} Understanding transport contexts +Transport Layer Security (TLS) is the name of an industry standard protocol for applying security controls (such as encryption) to network communications. TLS is the modern name for what used to be called Secure Sockets Layer (SSL). The {{es}} documentation uses the terms TLS and SSL interchangeably. + +Transport Protocol is the name of the protocol that {{es}} nodes use to communicate with one another. This name is specific to {{es}} and distinguishes the transport port (default `9300`) from the HTTP port (default `9200`). Nodes communicate with one another using the transport port, and REST clients communicate with {{es}} using the HTTP port. + +Although the word *transport* appears in both contexts, they mean different things. It’s possible to apply TLS to both the {{es}} transport port and the HTTP port. We know that these overlapping terms can be confusing, so to clarify, in this scenario we’re applying TLS to the {{es}} transport port. In [the next scenario](secure-http-communications.md), we’ll apply TLS to the {{es}} HTTP port. + +:::: + + +## Generate the certificate authority [generate-certificates] + +You can add as many nodes as you want in a cluster but they must be able to communicate with each other. The communication between nodes in a cluster is handled by the transport module. To secure your cluster, you must ensure that internode communications are encrypted and verified, which is achieved with mutual TLS. + +In a secured cluster, {{es}} nodes use certificates to identify themselves when communicating with other nodes. + +The cluster must validate the authenticity of these certificates. The recommended approach is to trust a specific certificate authority (CA). When nodes are added to your cluster they must use a certificate signed by the same CA. + +For the transport layer, we recommend using a separate, dedicated CA instead of an existing, possibly shared CA so that node membership is tightly controlled. Use the `elasticsearch-certutil` tool to generate a CA for your cluster. + +1. Before starting {{es}}, use the `elasticsearch-certutil` tool on any single node to generate a CA for your cluster. + + ```shell + ./bin/elasticsearch-certutil ca + ``` + + 1. When prompted, accept the default file name, which is `elastic-stack-ca.p12`. This file contains the public certificate for your CA and the private key used to sign certificates for each node. + 2. Enter a password for your CA. You can choose to leave the password blank if you’re not deploying to a production environment. + +2. On any single node, generate a certificate and private key for the nodes in your cluster. You include the `elastic-stack-ca.p12` output file that you generated in the previous step. + + ```shell + ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 + ``` + + `--ca ` + : Name of the CA file used to sign your certificates. The default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. + + 1. Enter the password for your CA, or press **Enter** if you did not configure one in the previous step. + 2. Create a password for the certificate and accept the default file name. + + The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. + +3. On **every** node in your cluster, copy the `elastic-certificates.p12` file to the `$ES_PATH_CONF` directory. + + +## Encrypt internode communications with TLS [encrypt-internode-communication] + +The transport networking layer is used for internal communication between nodes in a cluster. When security features are enabled, you must use TLS to ensure that communication between the nodes is encrypted. + +Now that you’ve generated a certificate authority and certificates, you’ll update your cluster to use these files. + +::::{note} +{{es}} monitors all files such as certificates, keys, keystores, or truststores that are configured as values of TLS-related node settings. If you update any of these files, such as when your hostnames change or your certificates are due to expire, {{es}} reloads them. The files are polled for changes at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. +:::: + + +Complete the following steps **for each node in your cluster**. To join the same cluster, all nodes must share the same `cluster.name` value. + +1. Open the `$ES_PATH_CONF/elasticsearch.yml` file and make the following changes: + + 1. Add the [`cluster-name`](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-name) setting and enter a name for your cluster: + + ```yaml + cluster.name: my-cluster + ``` + + 2. Add the [`node.name`](../deploy/self-managed/important-settings-configuration.md#node-name) setting and enter a name for the node. The node name defaults to the hostname of the machine when {{es}} starts. + + ```yaml + node.name: node-1 + ``` + + 3. Add the following settings to enable internode communication and provide access to the node’s certificate. + + Because you are using the same `elastic-certificates.p12` file on every node in your cluster, set the verification mode to `certificate`: + + ```yaml + xpack.security.transport.ssl.enabled: true + xpack.security.transport.ssl.verification_mode: certificate <1> + xpack.security.transport.ssl.client_authentication: required + xpack.security.transport.ssl.keystore.path: elastic-certificates.p12 + xpack.security.transport.ssl.truststore.path: elastic-certificates.p12 + ``` + + 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#transport-tls-ssl-settings). + +2. If you entered a password when creating the node certificate, run the following commands to store the password in the {{es}} keystore: + + ```shell + ./bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password + ``` + + ```shell + ./bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password + ``` + +3. Complete the previous steps for each node in your cluster. +4. On **every** node in your cluster, start {{es}}. The method for [starting](../maintenance/start-stop-services/start-stop-elasticsearch.md) and [stopping](../maintenance/start-stop-services/start-stop-elasticsearch.md) {{es}} varies depending on how you installed it. + + For example, if you installed {{es}} with an archive distribution (`tar.gz` or `.zip`), you can enter `Ctrl+C` on the command line to stop {{es}}. + + ::::{warning} + You must perform a full cluster restart. Nodes that are configured to use TLS for transport cannot communicate with nodes that use unencrypted transport connection (and vice-versa). + :::: + + + +## What’s next? [encrypting-internode-whatsnext] + +Congratulations! You’ve encrypted communications between the nodes in your cluster and can pass the [TLS bootstrap check](../deploy/self-managed/bootstrap-checks.md#bootstrap-checks-tls). + +To add another layer of security, [Set up basic security for the Elastic Stack plus secured HTTPS traffic](secure-http-communications.md). In addition to configuring TLS on the transport interface of your {{es}} cluster, you configure TLS on the HTTP interface for both {{es}} and {{kib}}. + + diff --git a/deploy-manage/security/set-up-minimal-security.md b/deploy-manage/security/set-up-minimal-security.md new file mode 100644 index 000000000..71e1f5344 --- /dev/null +++ b/deploy-manage/security/set-up-minimal-security.md @@ -0,0 +1,138 @@ +--- +navigation_title: "Set up minimal security" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-minimal-setup.html +--- + + + +# Set up minimal security [security-minimal-setup] + + +::::{important} +You only need to complete the following steps if you’re running an existing, unsecured cluster and want to enable the {{es}} {security-features}. +:::: + + +In {{es}} 8.0 and later, security is [enabled automatically](../deploy/self-managed/installing-elasticsearch.md) when you start {{es}} for the first time. + +If you’re running an existing {{es}} cluster where security is disabled, you can manually enable the {{es}} {security-features} and then create passwords for built-in users. You can add more users later, but using the built-in users simplifies the process of enabling security for your cluster. + +::::{important} +The minimal security scenario is not sufficient for [production mode](../deploy/self-managed/bootstrap-checks.md#dev-vs-prod-mode) clusters. If your cluster has multiple nodes, you must enable minimal security and then [configure Transport Layer Security (TLS)](secure-cluster-communications.md) between nodes. +:::: + + +## Enable {{es}} security features [_enable_es_security_features] + +Enabling the {{es}} security features provides basic authentication so that you can run a local cluster with username and password authentication. + +1. On **every** node in your cluster, stop both {{kib}} and {{es}} if they are running. +2. On **every** node in your cluster, add the `xpack.security.enabled` setting to the `$ES_PATH_CONF/elasticsearch.yml` file and set the value to `true`: + + ```yaml + xpack.security.enabled: true + ``` + + ::::{note} + The `$ES_PATH_CONF` variable is the path for the {{es}} configuration files. If you installed {{es}} using archive distributions (`zip` or `tar.gz`), the variable defaults to `$ES_HOME/config`. If you used package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. + :::: + +3. If your cluster has a single node, add the `discovery.type` setting in the `$ES_PATH_CONF/elasticsearch.yml` file and set the value to `single-node`. This setting ensures that your node does not inadvertently connect to other clusters that might be running on your network. + + ```yaml + discovery.type: single-node + ``` + + + +## Set passwords for built-in users [security-create-builtin-users] + +To communicate with your cluster, you must configure a password for the `elastic` and `kibana_system` built-in users. Unless you enable anonymous access (not recommended), all requests that don’t include credentials are rejected. + +::::{note} +You only need to set passwords for the `elastic` and `kibana_system` users when enabling minimal or basic security. +:::: + + +1. On **every** node in your cluster, start {{es}}. For example, if you installed {{es}} with a `.tar.gz` package, run the following command from the `ES_HOME` directory: + + ```shell + ./bin/elasticsearch + ``` + +2. On any node in your cluster, open another terminal window and set the password for the `elastic` built-in user by running the [`elasticsearch-reset-password`](https://www.elastic.co/guide/en/elasticsearch/reference/current/reset-password.html) utility. This command resets the password to an auto-generated value. + + ```shell + ./bin/elasticsearch-reset-password -u elastic + ``` + + If you want to set the password to a specific value, run the command with the interactive (`-i`) parameter. + + ```shell + ./bin/elasticsearch-reset-password -i -u elastic + ``` + +3. Set the password for the `kibana_system` built-in user. + + ```shell + ./bin/elasticsearch-reset-password -u kibana_system + ``` + +4. Save the new passwords. In the next step, you’ll add the password for the `kibana_system` user to {{kib}}. + +**Next**: [Configure {{kib}} to connect to {{es}} with a password](#add-built-in-users) + + +## Configure {{kib}} to connect to {{es}} with a password [add-built-in-users] + +When the {{es}} security features are enabled, users must log in to {{kib}} with a valid username and password. + +You’ll configure {{kib}} to use the built-in `kibana_system` user and the password that you created earlier. {{kib}} performs some background tasks that require use of the `kibana_system` user. + +This account is not meant for individual users and does not have permission to log in to {{kib}} from a browser. Instead, you’ll log in to {{kib}} as the `elastic` superuser. + +1. Add the `elasticsearch.username` setting to the `KBN_PATH_CONF/kibana.yml` file and set the value to the `kibana_system` user: + + ```yaml + elasticsearch.username: "kibana_system" + ``` + + ::::{note} + The `KBN_PATH_CONF` variable is the path for the {{kib}} configuration files. If you installed {{kib}} using archive distributions (`zip` or `tar.gz`), the variable defaults to `KIB_HOME/config`. If you used package distributions (Debian or RPM), the variable defaults to `/etc/kibana`. + :::: + +2. From the directory where you installed {{kib}}, run the following commands to create the {{kib}} keystore and add the secure settings: + + 1. Create the {{kib}} keystore: + + ```shell + ./bin/kibana-keystore create + ``` + + 2. Add the password for the `kibana_system` user to the {{kib}} keystore: + + ```shell + ./bin/kibana-keystore add elasticsearch.password + ``` + + When prompted, enter the password for the `kibana_system` user. + +3. Restart {{kib}}. For example, if you installed {{kib}} with a `.tar.gz` package, run the following command from the {{kib}} directory: + + ```shell + ./bin/kibana + ``` + +4. Log in to {{kib}} as the `elastic` user. Use this superuser account to [manage spaces, create new users, and assign roles](../users-roles/cluster-or-deployment-auth/quickstart.md). If you’re running {{kib}} locally, go to `http://localhost:5601` to view the login page. + + +## What’s next? [minimal-security-whatsnext] + +Congratulations! You enabled password protection for your local cluster to prevent unauthorized access. You can log in to {{kib}} securely as the `elastic` user and create additional users and roles. If you’re running a [single-node cluster](../deploy/self-managed/bootstrap-checks.md#single-node-discovery), then you can stop here. + +If your cluster has multiple nodes, then you must configure Transport Layer Security (TLS) between nodes. [Production mode](../deploy/self-managed/bootstrap-checks.md#dev-vs-prod-mode) clusters will not start if you do not enable TLS. + +[Set up basic security for the {{stack}}](secure-cluster-communications.md) to secure all internal communication between nodes in your cluster. + + diff --git a/deploy-manage/security/supported-ssltls-versions-by-jdk-version.md b/deploy-manage/security/supported-ssltls-versions-by-jdk-version.md new file mode 100644 index 000000000..726580b65 --- /dev/null +++ b/deploy-manage/security/supported-ssltls-versions-by-jdk-version.md @@ -0,0 +1,112 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/jdk-tls-versions.html +--- + +# Supported SSL/TLS versions by JDK version [jdk-tls-versions] + +{{es}} relies on your JDK’s implementation of SSL and TLS. + +Different JDK versions support different versions of SSL, and this may affect how {{es}} operates. + +::::{note} +This support applies when running on the default JSSE provider in the JDK. JVMs that are configured to use a [FIPS 140-2](fips-140-2.md) security provider might have a custom TLS implementation, which might support TLS protocol versions that differ from this list. + +Check your security provider’s release notes for information on TLS support. + +:::: + + +`SSLv3` +: SSL v3 is supported on all {{es}} [compatible JDKs](../deploy/self-managed/installing-elasticsearch.md#jvm-version) but is disabled by default. See [Enabling additional SSL/TLS versions on your JDK](#jdk-enable-tls-protocol). + +`TLSv1` +: TLS v1.0 is supported on all {{es}} [compatible JDKs](../deploy/self-managed/installing-elasticsearch.md#jvm-version). Some newer JDKs, including the JDK bundled with {{es}}, disable TLS v1.0 by default. See [Enabling additional SSL/TLS versions on your JDK](#jdk-enable-tls-protocol). + +`TLSv1.1` +: TLS v1.1 is supported on all {{es}} [compatible JDKs](../deploy/self-managed/installing-elasticsearch.md#jvm-version). Some newer JDKs, including the JDK bundled with {{es}}, disable TLS v1.1 by default. See [Enabling additional SSL/TLS versions on your JDK](#jdk-enable-tls-protocol). + +`TLSv1.2` +: TLS v1.2 is supported on all {{es}} [compatible JDKs](../deploy/self-managed/installing-elasticsearch.md#jvm-version). It is enabled by default on all JDKs that are supported by {{es}}, including the bundled JDK. + +`TLSv1.3` +: TLS v1.3 is supported on JDK11 and later, and JDK8 builds newer than 8u261 (including the most recent release of each JDK8 distribution that {{es}} supports). TLS v1.3 is supported and enabled by default on the JDK that is bundled with {{es}}. + + ::::{note} + Although {{es}} supports running on older JDK8 builds without TLS v1.3, we recommend upgrading to a JDK version that includes TLS v1.3 for better support and updates. + :::: + + +## Enabling additional SSL/TLS versions on your JDK [jdk-enable-tls-protocol] + +The set of supported SSL/TLS versions for a JDK is controlled by a java security properties file that is installed as part of your JDK. + +This configuration file lists the SSL/TLS algorithms that are disabled in that JDK. Complete these steps to remove a TLS version from that list and use it in your JDK. + +1. Locate the configuration file for your JDK. +2. Copy the `jdk.tls.disabledAlgorithms` setting from that file, and add it to a custom configuration file within the {{es}} configuration directory. +3. In the custom configuration file, remove the value for the TLS version you want to use from `jdk.tls.disabledAlgorithms`. +4. Configure {{es}} to pass a custom system property to the JDK so that your custom configuration file is used. + +### Locate the configuration file for your JDK [_locate_the_configuration_file_for_your_jdk] + +For the {{es}} **bundled JDK**, the configuration file is in a sub directory of the {{es}} home directory (`$ES_HOME`): + +* Linux: `$ES_HOME/jdk/conf/security/java.security` +* Windows: `$ES_HOME/jdk/conf/security/java.security` +* macOS:`$ES_HOME/jdk.app/Contents/Home/conf/security/java.security` + +For **JDK8**, the configuration file is within the `jre/lib/security` directory of the Java installation. If `$JAVA_HOME` points to the home directory of the JDK that you use to run {{es}}, then the configuration file will be in: + +* `$JAVA_HOME/jre/lib/security/java.security` + +For **JDK11 or later**, the configuration file is within the `conf/security` directory of the Java installation. If `$JAVA_HOME` points to the home directory of the JDK that you use to run {{es}}, then the configuration file will be in: + +* `$JAVA_HOME/conf/security/java.security` + + +### Copy the disabledAlgorithms setting [_copy_the_disabledalgorithms_setting] + +Within the JDK configuration file is a line that starts with `jdk.tls.disabledAlgorithms=`. This setting controls which protocols and algorithms are *disabled* in your JDK. The value of that setting will typically span multiple lines. + +For example, in OpenJDK 16 the setting is: + +```text +jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, \ + DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL +``` + +Create a new file in your in your {{es}} configuration directory named `es.java.security`. Copy the `jdk.tls.disabledAlgorithms` setting from the JDK’s default configuration file into `es.java.security`. You do not need to copy any other settings. + + +### Enable required TLS versions [_enable_required_tls_versions] + +Edit the `es.java.security` file in your {{es}} configuration directory, and modify the `jdk.tls.disabledAlgorithms` setting so that any SSL or TLS versions that you wish to use are no longer listed. + +For example, to enable TLSv1.1 on OpenJDK 16 (which uses the `jdk.tls.disabledAlgorithms` settings shown previously), the `es.java.security` file would contain the previously disabled TLS algorithms *except* `TLSv1.1`: + +```text +jdk.tls.disabledAlgorithms=SSLv3, TLSv1, RC4, DES, MD5withRSA, \ + DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL +``` + + +### Enable your custom security configuration [_enable_your_custom_security_configuration] + +To enable your custom security policy, add a file in the [`jvm.options.d`](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options) directory within your {{es}} configuration directory. + +To enable your custom security policy, create a file named `java.security.options` within the [jvm.options.d](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-options) directory of your {{es}} configuration directory, with this content: + +```text +-Djava.security.properties=/path/to/your/es.java.security +``` + + + +## Enabling TLS versions in {{es}} [_enabling_tls_versions_in_es] + +SSL/TLS versions can be enabled and disabled within {{es}} via the [`ssl.supported_protocols` settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ssl-tls-settings). + +{{es}} will only support the TLS versions that are enabled by the [underlying JDK](). If you configure `ssl.supported_procotols` to include a TLS version that is not enabled in your JDK, then it will be silently ignored. + +Similarly, a TLS version that is enabled in your JDK, will not be used unless it is configured as one of the `ssl.supported_protocols` in {{es}}. diff --git a/deploy-manage/security/traffic-filtering.md b/deploy-manage/security/traffic-filtering.md new file mode 100644 index 000000000..63a9e9723 --- /dev/null +++ b/deploy-manage/security/traffic-filtering.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-traffic-filtering-deployment-configuration.html + - https://www.elastic.co/guide/en/cloud/current/ec-traffic-filtering-deployment-configuration.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-traffic-filtering-deployment-configuration.html +--- + +# Traffic filtering + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/346 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-traffic-filtering-deployment-configuration.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-traffic-filtering-deployment-configuration.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-traffic-filtering-deployment-configuration.md \ No newline at end of file diff --git a/deploy-manage/security/updating-certificates.md b/deploy-manage/security/updating-certificates.md new file mode 100644 index 000000000..795466591 --- /dev/null +++ b/deploy-manage/security/updating-certificates.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/update-node-certs.html +--- + +# Updating certificates [update-node-certs] + +You might need to update your TLS certificates if your current node certificates expire soon, you’re adding new nodes to your secured cluster, or a security breach has broken the trust of your certificate chain. Use the [SSL certificate](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html) API to check when your certificates are expiring. + +In instances where you have access to the original Certificate Authority (CA) key and certificate that you used to sign your existing node certificates (and where you can still trust your CA), you can [use that CA to sign the new certificates](same-ca.md). + +If you have to trust a new CA from your organization, or you need to generate a new CA yourself, you need to use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. In this case, you’ll [sign node certificates with your new CA](different-ca.md) and instruct your nodes to trust this certificate chain. + +Depending on which certificates are expiring, you might need to update the certificates for the transport layer, the HTTP layer, or both. + +Regardless of the scenario, {{es}} monitors the SSL resources for updates by default, on a five-second interval. You can just copy the new certificate and key files (or keystore) into the {{es}} configuration directory and your nodes will detect the changes and reload the keys and certificates. + +Because {{es}} doesn’t reload the `elasticsearch.yml` configuration, you must use **the same file names** if you want to take advantage of automatic certificate and key reloading. + +If you need to update the `elasticsearch.yml` configuration or change passwords for keys or keystores that are stored in the [secure settings](secure-settings.md), then you must complete a [rolling restart](#use-rolling-restarts). {{es}} will not automatically reload changes for passwords stored in the secure settings. + +::::{admonition} Rolling restarts are preferred +:name: use-rolling-restarts + +While it’s possible to do an in-place update for security certificates, using a [rolling restart](../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) on your cluster is safer. An in-place update avoids some complications of a rolling restart, but incurs the following risks: + +* If you use PEM files, your certificate and key are in separate files. You must update both files *simultaneously* or the node might experience a temporary period where it cannot establish new connections. +* Updating the certificate and key does not automatically force existing connections to refresh. This means that even if you make a mistake, a node can seem like it’s functioning but only because it still has existing connections. It’s possible that a node will be unable to connect with other nodes, rendering it unable to recover from a network outage or node restart. + +:::: + + + + diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index f2ce0b7f6..66a6f7a5b 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -1,3 +1,868 @@ -project: 'Deploy and Manage' +project: 'Deploy and manage' toc: - - file: index.md \ No newline at end of file + - file: index.md + - file: distributed-architecture.md + children: + - file: distributed-architecture/clusters-nodes-shards.md + children: + - file: distributed-architecture/clusters-nodes-shards/node-roles.md + - file: distributed-architecture/reading-and-writing-documents.md + - file: distributed-architecture/shard-allocation-relocation-recovery.md + children: + - file: distributed-architecture/shard-allocation-relocation-recovery/shard-allocation-awareness.md + - file: distributed-architecture/shard-allocation-relocation-recovery/index-level-shard-allocation.md + children: + - file: distributed-architecture/shard-allocation-relocation-recovery/delaying-allocation-when-node-leaves.md + - file: distributed-architecture/discovery-cluster-formation.md + children: + - file: distributed-architecture/discovery-cluster-formation/discovery-hosts-providers.md + - file: distributed-architecture/discovery-cluster-formation/modules-discovery-quorums.md + - file: distributed-architecture/discovery-cluster-formation/modules-discovery-voting.md + - file: distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster.md + - file: distributed-architecture/discovery-cluster-formation/cluster-state-overview.md + - file: distributed-architecture/discovery-cluster-formation/cluster-fault-detection.md + - file: distributed-architecture/kibana-tasks-management.md + - file: deploy.md + children: + - file: deploy/elastic-cloud.md + children: + - file: deploy/elastic-cloud/create-an-organization.md + children: + - file: deploy/elastic-cloud/subscribe-from-marketplace.md + children: + - file: deploy/elastic-cloud/aws-marketplace.md + children: + - file: deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-aws-marketplace.md + - file: deploy/elastic-cloud/azure-native-isv-service.md + children: + - file: deploy/elastic-cloud/azure-marketplace-pricing.md + - file: deploy/elastic-cloud/google-cloud-platform-marketplace.md + children: + - file: deploy/elastic-cloud/create-monthly-pay-as-you-go-subscription-on-gcp-marketplace.md + - file: deploy/elastic-cloud/heroku.md + children: + - file: deploy/elastic-cloud/ech-getting-started.md + children: + - file: deploy/elastic-cloud/ech-getting-started-installing.md + children: + - file: deploy/elastic-cloud/ech-getting-started-installing-version.md + - file: deploy/elastic-cloud/ech-getting-started-removing.md + - file: deploy/elastic-cloud/ech-migrating.md + - file: deploy/elastic-cloud/ech-getting-started-accessing.md + children: + - file: deploy/elastic-cloud/ech-access-kibana.md + - file: deploy/elastic-cloud/ech-working-with-elasticsearch.md + - file: deploy/elastic-cloud/ech-api-console.md + - file: deploy/elastic-cloud/ech-getting-started-next-steps.md + - file: deploy/elastic-cloud/ech-migrate-data2.md + children: + - file: deploy/elastic-cloud/ech-migrate-data-internal.md + - file: deploy/elastic-cloud/ech-about.md + children: + - file: deploy/elastic-cloud/ech-licensing.md + - file: deploy/elastic-cloud/ech-version-policy.md + - file: deploy/elastic-cloud/ech-reference-hardware.md + children: + - file: deploy/elastic-cloud/ech-gcp-instance-configuration.md + - file: deploy/elastic-cloud/ech-default-gcp-configurations.md + - file: deploy/elastic-cloud/ech-aws-instance-configuration.md + - file: deploy/elastic-cloud/ech-default-aws-configurations.md + - file: deploy/elastic-cloud/ech-azure-instance-configuration.md + - file: deploy/elastic-cloud/ech-default-azure-configurations.md + - file: deploy/elastic-cloud/ech-reference-regions.md + - file: deploy/elastic-cloud/ech-service-status.md + children: + - file: deploy/elastic-cloud/echsubscribe_to_individual_regionscomponents.md + - file: deploy/elastic-cloud/echservice_status_api.md + - file: deploy/elastic-cloud/ech-get-help.md + - file: deploy/elastic-cloud/ech-restrictions.md + - file: deploy/elastic-cloud/ech-whats-new.md + - file: deploy/elastic-cloud/serverless.md + children: + - file: deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md + - file: deploy/elastic-cloud/create-serverless-project.md + - file: deploy/elastic-cloud/regions.md + - file: deploy/elastic-cloud/project-settings.md + - file: deploy/elastic-cloud/cloud-hosted.md + children: + - file: deploy/elastic-cloud/create-an-elastic-cloud-hosted-deployment.md + children: + - file: deploy/elastic-cloud/available-stack-versions.md + - file: deploy/elastic-cloud/access-kibana.md + - file: deploy/elastic-cloud/manage-deployments.md + children: + - file: deploy/elastic-cloud/configure.md + children: + - file: deploy/elastic-cloud/ec-customize-deployment.md + children: + - file: deploy/elastic-cloud/ec-configure-deployment-settings.md + - file: deploy/elastic-cloud/ec-change-hardware-profile.md + - file: deploy/elastic-cloud/ec-customize-deployment-components.md + - file: deploy/elastic-cloud/ech-configure-settings.md + children: + - file: deploy/elastic-cloud/ech-configure-deployment-settings.md + - file: deploy/elastic-cloud/ech-customize-deployment-components.md + - file: deploy/elastic-cloud/edit-stack-settings.md + - file: deploy/elastic-cloud/add-plugins-extensions.md + children: + - file: deploy/elastic-cloud/add-plugins-provided-with-elastic-cloud-hosted.md + - file: deploy/elastic-cloud/upload-custom-plugins-bundles.md + - file: deploy/elastic-cloud/manage-plugins-extensions-through-api.md + - file: deploy/elastic-cloud/custom-endpoint-aliases.md + - file: deploy/elastic-cloud/manage-integrations-server.md + children: + - file: deploy/elastic-cloud/switch-from-apm-to-integrations-server-payload.md + - file: deploy/elastic-cloud/find-cloud-id.md + - file: deploy/elastic-cloud/change-hardware.md + - file: deploy/elastic-cloud/manage-deployments-using-elastic-cloud-api.md + - file: deploy/elastic-cloud/keep-track-of-deployment-activity.md + - file: deploy/elastic-cloud/tools-apis.md + - file: deploy/elastic-cloud/restrictions-known-problems.md + - file: deploy/cloud-enterprise.md + children: + - file: deploy/cloud-enterprise/ece-architecture.md + - file: deploy/cloud-enterprise/ece-containerization.md + - file: deploy/cloud-enterprise/prepare-environment.md + children: + - file: deploy/cloud-enterprise/ece-hardware-prereq.md + - file: deploy/cloud-enterprise/ece-software-prereq.md + - file: deploy/cloud-enterprise/ece-sysconfig.md + - file: deploy/cloud-enterprise/ece-networking-prereq.md + - file: deploy/cloud-enterprise/ece-ha.md + - file: deploy/cloud-enterprise/ece-roles.md + - file: deploy/cloud-enterprise/ece-load-balancers.md + - file: deploy/cloud-enterprise/ece-users-permissions.md + - file: deploy/cloud-enterprise/ece-jvm.md + - file: deploy/cloud-enterprise/ece-wildcard-dns.md + - file: deploy/cloud-enterprise/ece-manage-capacity.md + - file: deploy/cloud-enterprise/deploy-an-orchestrator.md + children: + - file: deploy/cloud-enterprise/install.md + children: + - file: deploy/cloud-enterprise/identify-deployment-scenario.md + - file: deploy/cloud-enterprise/install-ece-on-public-cloud.md + children: + - file: deploy/cloud-enterprise/configure-operating-system-cloud.md + children: + - file: deploy/cloud-enterprise/configure-host-ubuntu-cloud.md + - file: deploy/cloud-enterprise/configure-host-rhel-cloud.md + - file: deploy/cloud-enterprise/configure-host-suse-cloud.md + - file: deploy/cloud-enterprise/install-ece-cloud.md + children: + - file: deploy/cloud-enterprise/deploy-small-installation-cloud.md + - file: deploy/cloud-enterprise/deploy-medium-installation-cloud.md + - file: deploy/cloud-enterprise/deploy-large-installation-cloud.md + - file: deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-cloud.md + - file: deploy/cloud-enterprise/install-ece-on-own-premises.md + children: + - file: deploy/cloud-enterprise/configure-operating-system-onprem.md + children: + - file: deploy/cloud-enterprise/configure-host-ubuntu-onprem.md + - file: deploy/cloud-enterprise/configure-host-rhel-onprem.md + - file: deploy/cloud-enterprise/configure-host-suse-onprem.md + - file: deploy/cloud-enterprise/install-ece-onprem.md + children: + - file: deploy/cloud-enterprise/deploy-small-installation-onprem.md + - file: deploy/cloud-enterprise/deploy-medium-installation-onprem.md + - file: deploy/cloud-enterprise/deploy-large-installation-onprem.md + - file: deploy/cloud-enterprise/fresh-installation-of-ece-using-podman-hosts-onprem.md + - file: deploy/cloud-enterprise/alternative-install-ece-with-ansible.md + - file: deploy/cloud-enterprise/log-into-cloud-ui.md + - file: deploy/cloud-enterprise/install-ece-on-additional-hosts.md + children: + - file: deploy/cloud-enterprise/generate-roles-tokens.md + - file: deploy/cloud-enterprise/migrate-ece-to-podman-hosts.md + - file: deploy/cloud-enterprise/post-installation-steps.md + - file: deploy/cloud-enterprise/statistics-collected-by-cloud-enterprise.md + - file: deploy/cloud-enterprise/air-gapped-install.md + children: + - file: deploy/cloud-enterprise/ece-install-offline-with-registry.md + - file: deploy/cloud-enterprise/ece-install-offline-no-registry.md + - file: deploy/cloud-enterprise/ece-install-offline-images.md + - file: deploy/cloud-enterprise/configure.md + children: + - file: deploy/cloud-enterprise/assign-roles-to-hosts.md + - file: deploy/cloud-enterprise/system-deployments-configuration.md + children: + - file: deploy/cloud-enterprise/default-system-deployment-versions.md + - file: deploy/cloud-enterprise/configure-deployment-templates.md + children: + - file: deploy/cloud-enterprise/ece-configuring-ece-tag-allocators.md + - file: deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-edit.md + - file: deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-create.md + - file: deploy/cloud-enterprise/ece-configuring-ece-create-templates.md + - file: deploy/cloud-enterprise/ece-configuring-ece-configure-system-templates.md + - file: deploy/cloud-enterprise/ece-configure-templates-index-management.md + - file: deploy/cloud-enterprise/ce-add-support-for-node-roles-autoscaling.md + - file: deploy/cloud-enterprise/ece-ce-add-support-for-integrations-server.md + - file: deploy/cloud-enterprise/ece-configuring-ece-instance-configurations-default.md + - file: deploy/cloud-enterprise/ece-include-additional-kibana-plugin.md + - file: deploy/cloud-enterprise/change-ece-api-url.md + - file: deploy/cloud-enterprise/change-endpoint-urls.md + - file: deploy/cloud-enterprise/enable-custom-endpoint-aliases.md + children: + - file: deploy/cloud-enterprise/ece-regional-deployment-aliases.md + - file: deploy/cloud-enterprise/configure-allocator-affinity.md + - file: deploy/cloud-enterprise/change-allocator-disconnect-timeout.md + - file: deploy/cloud-enterprise/manage-elastic-stack-versions.md + - file: deploy/cloud-enterprise/migrate-ece-on-podman-hosts-to-selinux-enforce.md + - file: deploy/cloud-enterprise/working-with-deployments.md + children: + - file: deploy/cloud-enterprise/deployment-templates.md + - file: deploy/cloud-enterprise/create-deployment.md + - file: deploy/cloud-enterprise/edit-stack-settings.md + - file: deploy/cloud-enterprise/customize-deployment.md + - file: deploy/cloud-enterprise/resize-deployment.md + children: + - file: deploy/cloud-enterprise/resource-overrides.md + - file: deploy/cloud-enterprise/manage-integrations-server.md + children: + - file: deploy/cloud-enterprise/switch-from-apm-to-integrations-server-payload.md + - file: deploy/cloud-enterprise/find-cloud-id.md + - file: deploy/cloud-enterprise/find-endpoint-url.md + - file: deploy/cloud-enterprise/advanced-cluster-configuration.md + - file: deploy/cloud-enterprise/search-filter-deployments.md + - file: deploy/cloud-enterprise/keep-track-of-deployment-activity.md + - file: deploy/cloud-enterprise/tools-apis.md + - file: deploy/cloud-on-k8s.md + children: + - file: deploy/cloud-on-k8s/deploy-an-orchestrator.md + children: + - file: deploy/cloud-on-k8s/install.md + children: + - file: deploy/cloud-on-k8s/install-using-yaml-manifest-quickstart.md + - file: deploy/cloud-on-k8s/install-using-helm-chart.md + - file: deploy/cloud-on-k8s/deploy-eck-on-openshift.md + children: + - file: deploy/cloud-on-k8s/k8s-openshift-deploy-operator.md + - file: deploy/cloud-on-k8s/k8s-openshift-deploy-elasticsearch.md + - file: deploy/cloud-on-k8s/k8s-openshift-deploy-kibana.md + - file: deploy/cloud-on-k8s/k8s-openshift-anyuid-workaround.md + - file: deploy/cloud-on-k8s/k8s-openshift-beats.md + - file: deploy/cloud-on-k8s/k8s-openshift-agent.md + - file: deploy/cloud-on-k8s/deploy-eck-on-gke-autopilot.md + children: + - file: deploy/cloud-on-k8s/k8s-autopilot-setting-virtual-memory.md + - file: deploy/cloud-on-k8s/k8s-autopilot-deploy-operator.md + - file: deploy/cloud-on-k8s/k8s-autopilot-deploy-elasticsearch.md + - file: deploy/cloud-on-k8s/k8s-autopilot-deploy-agent-beats.md + - file: deploy/cloud-on-k8s/deploy-fips-compatible-version-of-eck.md + - file: deploy/cloud-on-k8s/air-gapped-install.md + - file: deploy/cloud-on-k8s/configure.md + children: + - file: deploy/cloud-on-k8s/configure-eck.md + - file: deploy/cloud-on-k8s/required-rbac-permissions.md + - file: deploy/cloud-on-k8s/configure-validating-webhook.md + - file: deploy/cloud-on-k8s/restrict-cross-namespace-resource-associations.md + - file: deploy/cloud-on-k8s/create-custom-images.md + - file: deploy/cloud-on-k8s/service-meshes.md + children: + - file: deploy/cloud-on-k8s/k8s-service-mesh-istio.md + - file: deploy/cloud-on-k8s/k8s-service-mesh-linkerd.md + - file: deploy/cloud-on-k8s/network-policies.md + children: + - file: deploy/cloud-on-k8s/k8s_prerequisites.md + - file: deploy/cloud-on-k8s/webhook-namespace-selectors.md + - file: deploy/cloud-on-k8s/manage-deployments.md + children: + - file: deploy/cloud-on-k8s/elasticsearch-deployment-quickstart.md + - file: deploy/cloud-on-k8s/kibana-instance-quickstart.md + - file: deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md + - file: deploy/cloud-on-k8s/update-deployments.md + - file: deploy/cloud-on-k8s/accessing-services.md + - file: deploy/cloud-on-k8s/configure-deployments.md + children: + - file: deploy/cloud-on-k8s/elasticsearch-configuration.md + children: + - file: deploy/cloud-on-k8s/node-configuration.md + - file: deploy/cloud-on-k8s/volume-claim-templates.md + - file: deploy/cloud-on-k8s/storage-recommendations.md + - file: deploy/cloud-on-k8s/transport-settings.md + - file: deploy/cloud-on-k8s/virtual-memory.md + - file: deploy/cloud-on-k8s/settings-managed-by-eck.md + - file: deploy/cloud-on-k8s/custom-configuration-files-plugins.md + - file: deploy/cloud-on-k8s/init-containers-for-plugin-downloads.md + - file: deploy/cloud-on-k8s/update-strategy.md + - file: deploy/cloud-on-k8s/pod-disruption-budget.md + - file: deploy/cloud-on-k8s/nodes-orchestration.md + - file: deploy/cloud-on-k8s/advanced-elasticsearch-node-scheduling.md + - file: deploy/cloud-on-k8s/readiness-probe.md + - file: deploy/cloud-on-k8s/pod-prestop-hook.md + - file: deploy/cloud-on-k8s/security-context.md + - file: deploy/cloud-on-k8s/kibana-configuration.md + children: + - file: deploy/cloud-on-k8s/k8s-kibana-es.md + - file: deploy/cloud-on-k8s/k8s-kibana-advanced-configuration.md + - file: deploy/cloud-on-k8s/k8s-kibana-secure-settings.md + - file: deploy/cloud-on-k8s/k8s-kibana-http-configuration.md + - file: deploy/cloud-on-k8s/k8s-kibana-plugins.md + - file: deploy/cloud-on-k8s/tls-certificates.md + - file: deploy/cloud-on-k8s/recipes.md + - file: deploy/cloud-on-k8s/requests-routing-to-elasticsearch-nodes.md + - file: deploy/cloud-on-k8s/customize-pods.md + - file: deploy/cloud-on-k8s/manage-compute-resources.md + - file: deploy/cloud-on-k8s/elastic-stack-configuration-policies.md + - file: deploy/cloud-on-k8s/connect-to-external-elastic-resources.md + - file: deploy/cloud-on-k8s/orchestrate-other-elastic-applications.md + children: + - file: deploy/cloud-on-k8s/apm-server.md + children: + - file: deploy/cloud-on-k8s/use-an-elasticsearch-cluster-managed-by-eck.md + - file: deploy/cloud-on-k8s/advanced-configuration.md + - file: deploy/cloud-on-k8s/connect-to-apm-server.md + - file: deploy/cloud-on-k8s/standalone-elastic-agent.md + children: + - file: deploy/cloud-on-k8s/quickstart-standalone.md + - file: deploy/cloud-on-k8s/configuration-standalone.md + - file: deploy/cloud-on-k8s/configuration-examples-standalone.md + - file: deploy/cloud-on-k8s/fleet-managed-elastic-agent.md + children: + - file: deploy/cloud-on-k8s/quickstart-fleet.md + - file: deploy/cloud-on-k8s/configuration-fleet.md + - file: deploy/cloud-on-k8s/configuration-examples-fleet.md + - file: deploy/cloud-on-k8s/known-limitations.md + - file: deploy/cloud-on-k8s/elastic-maps-server.md + children: + - file: deploy/cloud-on-k8s/deploy-elastic-maps-server.md + - file: deploy/cloud-on-k8s/map-data.md + - file: deploy/cloud-on-k8s/advanced-configuration-maps-server.md + - file: deploy/cloud-on-k8s/http-configuration.md + - file: deploy/cloud-on-k8s/enterprise-search.md + children: + - file: deploy/cloud-on-k8s/quickstart-enterprise-search.md + - file: deploy/cloud-on-k8s/configuration-enterprise-search.md + - file: deploy/cloud-on-k8s/troubleshooting-enterprise-search.md + - file: deploy/cloud-on-k8s/beats.md + children: + - file: deploy/cloud-on-k8s/quickstart-beats.md + - file: deploy/cloud-on-k8s/configuration-beats.md + - file: deploy/cloud-on-k8s/configuration-examples-beats.md + - file: deploy/cloud-on-k8s/troubleshooting-beats.md + - file: deploy/cloud-on-k8s/logstash.md + children: + - file: deploy/cloud-on-k8s/quickstart-logstash.md + - file: deploy/cloud-on-k8s/configuration-logstash.md + - file: deploy/cloud-on-k8s/securing-logstash-api.md + - file: deploy/cloud-on-k8s/logstash-plugins.md + - file: deploy/cloud-on-k8s/configuration-examples-logstash.md + - file: deploy/cloud-on-k8s/update-strategy-logstash.md + - file: deploy/cloud-on-k8s/advanced-configuration-logstash.md + - file: deploy/cloud-on-k8s/tools-apis.md + - file: deploy/self-managed.md + children: + - file: deploy/self-managed/deploy-cluster.md + children: + - file: deploy/self-managed/important-system-configuration.md + children: + - file: deploy/self-managed/setting-system-settings.md + - file: deploy/self-managed/setup-configuration-memory.md + - file: deploy/self-managed/file-descriptors.md + - file: deploy/self-managed/vm-max-map-count.md + - file: deploy/self-managed/max-number-of-threads.md + - file: deploy/self-managed/networkaddress-cache-ttl.md + - file: deploy/self-managed/executable-jna-tmpdir.md + - file: deploy/self-managed/system-config-tcpretries.md + - file: deploy/self-managed/installing-elasticsearch.md + children: + - file: deploy/self-managed/install-elasticsearch-from-archive-on-linux-macos.md + - file: deploy/self-managed/install-elasticsearch-with-zip-on-windows.md + - file: deploy/self-managed/install-elasticsearch-with-debian-package.md + - file: deploy/self-managed/install-elasticsearch-with-rpm.md + - file: deploy/self-managed/install-elasticsearch-with-docker.md + - file: deploy/self-managed/local-development-installation-quickstart.md + - file: deploy/self-managed/bootstrap-checks.md + children: + - file: deploy/self-managed/bootstrap-checks-heap-size.md + - file: deploy/self-managed/bootstrap-checks-file-descriptor.md + - file: deploy/self-managed/bootstrap-checks-memory-lock.md + - file: deploy/self-managed/max-number-threads-check.md + - file: deploy/self-managed/bootstrap-checks-max-file-size.md + - file: deploy/self-managed/max-size-virtual-memory-check.md + - file: deploy/self-managed/bootstrap-checks-max-map-count.md + - file: deploy/self-managed/bootstrap-checks-client-jvm.md + - file: deploy/self-managed/bootstrap-checks-serial-collector.md + - file: deploy/self-managed/bootstrap-checks-syscall-filter.md + - file: deploy/self-managed/bootstrap-checks-onerror.md + - file: deploy/self-managed/bootstrap-checks-early-access.md + - file: deploy/self-managed/bootstrap-checks-all-permission.md + - file: deploy/self-managed/bootstrap-checks-discovery-configuration.md + - file: deploy/self-managed/configure-elasticsearch.md + children: + - file: deploy/self-managed/important-settings-configuration.md + - file: deploy/self-managed/other-configuration-settings.md + - file: deploy/self-managed/plugins.md + - file: deploy/self-managed/install-kibana.md + children: + - file: deploy/self-managed/install-from-archive-on-linux-macos.md + - file: deploy/self-managed/install-on-windows.md + - file: deploy/self-managed/install-with-debian-package.md + - file: deploy/self-managed/install-with-rpm.md + - file: deploy/self-managed/install-with-docker.md + - file: deploy/self-managed/configure.md + - file: deploy/self-managed/access.md + - file: deploy/self-managed/air-gapped-install.md + - file: deploy/self-managed/tools-apis.md + - file: deploy/kibana-reporting-configuration.md + - file: production-guidance.md + children: + - file: production-guidance/getting-ready-for-production-elasticsearch.md + - file: production-guidance/kibana-in-production-environments.md + - file: production-guidance/plan-for-production-elastic-cloud.md + - file: production-guidance/availability-and-resilience.md + children: + - file: production-guidance/availability-and-resilience/resilience-in-small-clusters.md + - file: production-guidance/availability-and-resilience/resilience-in-larger-clusters.md + - file: production-guidance/optimize-performance.md + children: + - file: production-guidance/optimize-performance/indexing-speed.md + - file: production-guidance/optimize-performance/search-speed.md + - file: production-guidance/optimize-performance/approximate-knn-search.md + - file: production-guidance/optimize-performance/disk-usage.md + - file: production-guidance/optimize-performance/size-shards.md + - file: production-guidance/kibana-task-manager-scaling-considerations.md + - file: production-guidance/kibana-alerting-production-considerations.md + - file: production-guidance/general-recommendations.md + - file: reference-architectures.md + children: + - file: reference-architectures/hotfrozen-high-availability.md + - file: tools.md + children: + - file: tools/snapshot-and-restore.md + children: + - file: tools/snapshot-and-restore/manage-snapshot-repositories.md + children: + - file: tools/snapshot-and-restore/self-managed.md + children: + - file: tools/snapshot-and-restore/azure-repository.md + - file: tools/snapshot-and-restore/google-cloud-storage-repository.md + - file: tools/snapshot-and-restore/s3-repository.md + - file: tools/snapshot-and-restore/shared-file-system-repository.md + - file: tools/snapshot-and-restore/read-only-url-repository.md + - file: tools/snapshot-and-restore/source-only-repository.md + - file: tools/snapshot-and-restore/elastic-cloud-hosted.md + children: + - file: tools/snapshot-and-restore/ec-custom-repository.md + children: + - file: tools/snapshot-and-restore/ec-aws-custom-repository.md + - file: tools/snapshot-and-restore/ec-gcs-snapshotting.md + - file: tools/snapshot-and-restore/ec-azure-snapshotting.md + - file: tools/snapshot-and-restore/ech-custom-repository.md + children: + - file: tools/snapshot-and-restore/ech-aws-custom-repository.md + - file: tools/snapshot-and-restore/ech-gcs-snapshotting.md + - file: tools/snapshot-and-restore/ech-azure-snapshotting.md + - file: tools/snapshot-and-restore/access-isolation-for-found-snapshots-repository.md + children: + - file: tools/snapshot-and-restore/repository-isolation-on-azure.md + - file: tools/snapshot-and-restore/repository-isolation-on-aws-gcp.md + - file: tools/snapshot-and-restore/cloud-enterprise.md + children: + - file: tools/snapshot-and-restore/google-cloud-storage-gcs-repository.md + - file: tools/snapshot-and-restore/azure-storage-repository.md + - file: tools/snapshot-and-restore/minio-on-premise-repository.md + - file: tools/snapshot-and-restore/cloud-on-k8s.md + - file: tools/snapshot-and-restore/create-snapshots.md + - file: tools/snapshot-and-restore/restore-snapshot.md + children: + # Duplicate? + # - file: tools/snapshot-and-restore/ec-restore-across-clusters.md + # children: + # - file: tools/snapshot-and-restore/ec-restore-snapshots-into-new-deployment.md + # - file: tools/snapshot-and-restore/ec-restore-snapshots-into-existing-deployment.md + # - file: tools/snapshot-and-restore/ec-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md + - file: tools/snapshot-and-restore/ece-restore-across-clusters.md + children: + - file: tools/snapshot-and-restore/ece-restore-snapshots-into-new-deployment.md + - file: tools/snapshot-and-restore/ece-restore-snapshots-into-existing-deployment.md + - file: tools/snapshot-and-restore/ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md + - file: tools/snapshot-and-restore/searchable-snapshots.md + - file: tools/cross-cluster-replication.md + children: + - file: tools/cross-cluster-replication/set-up-cross-cluster-replication.md + children: + - file: tools/cross-cluster-replication/ccr-getting-started-prerequisites.md + - file: tools/cross-cluster-replication/_connect_to_a_remote_cluster.md + - file: tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md + - file: tools/cross-cluster-replication/ccr-getting-started-follower-index.md + - file: tools/cross-cluster-replication/ccr-getting-started-auto-follow.md + - file: tools/cross-cluster-replication/manage-cross-cluster-replication.md + children: + - file: tools/cross-cluster-replication/ccr-inspect-progress.md + - file: tools/cross-cluster-replication/ccr-pause-replication.md + - file: tools/cross-cluster-replication/ccr-recreate-follower-index.md + - file: tools/cross-cluster-replication/ccr-terminate-replication.md + - file: tools/cross-cluster-replication/manage-auto-follow-patterns.md + children: + - file: tools/cross-cluster-replication/ccr-auto-follow-create.md + - file: tools/cross-cluster-replication/ccr-auto-follow-retrieve.md + - file: tools/cross-cluster-replication/ccr-auto-follow-pause.md + - file: tools/cross-cluster-replication/ccr-auto-follow-delete.md + - file: tools/cross-cluster-replication/upgrading-clusters.md + children: + - file: tools/cross-cluster-replication/ccr-uni-directional-upgrade.md + - file: tools/cross-cluster-replication/ccr-bi-directional-upgrade.md + - file: tools/cross-cluster-replication/uni-directional-disaster-recovery.md + children: + - file: tools/cross-cluster-replication/_prerequisites_14.md + - file: tools/cross-cluster-replication/_failover_when_clustera_is_down.md + - file: tools/cross-cluster-replication/_failback_when_clustera_comes_back.md + - file: tools/cross-cluster-replication/bi-directional-disaster-recovery.md + children: + - file: tools/cross-cluster-replication/ccr-tutorial-initial-setup.md + - file: tools/cross-cluster-replication/_failover_when_clustera_is_down_2.md + - file: tools/cross-cluster-replication/_failback_when_clustera_comes_back_2.md + - file: tools/cross-cluster-replication/_perform_update_or_delete_by_query.md + - file: autoscaling.md + children: + - file: autoscaling/ech-autoscaling.md + children: + - file: autoscaling/ech-autoscaling-example.md + - file: autoscaling/ec-autoscaling.md + children: + - file: autoscaling/ec-autoscaling-example.md + - file: autoscaling/ec-autoscaling-api-example.md + - file: autoscaling/ece-autoscaling.md + children: + - file: autoscaling/ece-autoscaling-example.md + - file: autoscaling/ece-autoscaling-api-example.md + - file: autoscaling/autoscaling-stateless-applications-on-eck.md + - file: autoscaling/deployments-autoscaling-on-eck.md + - file: autoscaling/autoscaling-deciders.md + - file: autoscaling/trained-model-autoscaling.md + - file: remote-clusters.md + children: + - file: remote-clusters/ec-enable-ccs.md + children: + - file: remote-clusters/ec-remote-cluster-same-ess.md + - file: remote-clusters/ec-remote-cluster-other-ess.md + - file: remote-clusters/ec-remote-cluster-ece.md + - file: remote-clusters/ec-remote-cluster-self-managed.md + - file: remote-clusters/ec-enable-ccs-for-eck.md + - file: remote-clusters/ec-edit-remove-trusted-environment.md + - file: remote-clusters/ec-migrate-ccs.md + - file: remote-clusters/ece-enable-ccs.md + children: + - file: remote-clusters/ece-remote-cluster-same-ece.md + - file: remote-clusters/ece-remote-cluster-other-ece.md + - file: remote-clusters/ece-remote-cluster-ece-ess.md + - file: remote-clusters/ece-remote-cluster-self-managed.md + - file: remote-clusters/ece-enable-ccs-for-eck.md + - file: remote-clusters/ece-edit-remove-trusted-environment.md + - file: remote-clusters/ece-migrate-ccs.md + - file: remote-clusters/remote-clusters-self-managed.md + children: + - file: remote-clusters/remote-clusters-api-key.md + - file: remote-clusters/remote-clusters-cert.md + - file: remote-clusters/remote-clusters-migrate.md + - file: remote-clusters/remote-clusters-settings.md + - file: remote-clusters/remote-clusters-troubleshooting.md + - file: remote-clusters/eck-remote-clusters.md + - file: security.md + children: + - file: security/secure-your-elastic-cloud-enterprise-installation.md + children: + - file: security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md + - file: security/secure-your-elastic-cloud-enterprise-installation/allow-x509-certificates-signed-with-sha-1.md + - file: security/secure-your-elastic-cloud-enterprise-installation/configure-tls-version.md + - file: security/secure-your-cluster-deployment.md + children: + - file: security/secure-endpoints.md + children: + - file: security/secure-http-communications.md + - file: security/traffic-filtering.md + children: + - file: security/ip-traffic-filtering.md + - file: security/private-link-traffic-filters.md + children: + - file: security/aws-privatelink-traffic-filters.md + - file: security/azure-private-link-traffic-filters.md + - file: security/gcp-private-service-connect-traffic-filters.md + - file: security/claim-traffic-filter-link-id-ownership-through-api.md + - file: security/manage-traffic-filtering-through-api.md + - file: security/elastic-cloud-static-ips.md + - file: security/kibana-session-management.md + - file: security/secure-cluster-communications.md + children: + - file: security/security-certificates-keys.md + children: + - file: security/updating-certificates.md + children: + - file: security/same-ca.md + - file: security/different-ca.md + - file: security/secure-clients-integrations.md + children: + - file: security/httprest-clients-security.md + - file: security/encrypt-deployment.md + children: + - file: security/encrypt-deployment-with-customer-managed-encryption-key.md + - file: security/secure-settings.md + - file: security/secure-saved-objects.md + - file: security/manually-configure-security-in-self-managed-cluster.md + children: + - file: security/set-up-minimal-security.md + - file: security/set-up-basic-security.md + - file: security/set-up-basic-security-plus-https.md + - file: security/enabling-cipher-suites-for-stronger-encryption.md + - file: security/supported-ssltls-versions-by-jdk-version.md + - file: security/fips-140-2.md + - file: users-roles.md + children: + - file: users-roles/cloud-enterprise-orchestrator.md + children: + - file: users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md + - file: users-roles/cloud-enterprise-orchestrator/manage-users-roles.md + children: + - file: users-roles/cloud-enterprise-orchestrator/native-user-authentication.md + - file: users-roles/cloud-enterprise-orchestrator/active-directory.md + - file: users-roles/cloud-enterprise-orchestrator/ldap.md + - file: users-roles/cloud-enterprise-orchestrator/saml.md + - file: users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md + - file: users-roles/cloud-organization.md + children: + - file: users-roles/cloud-organization/manage-users.md + - file: users-roles/cloud-organization/user-roles.md + - file: users-roles/cloud-organization/configure-saml-authentication.md + children: + - file: users-roles/cloud-organization/register-elastic-cloud-saml-in-okta.md + - file: users-roles/cloud-organization/register-elastic-cloud-saml-in-microsoft-entra-id.md + - file: users-roles/cluster-or-deployment-auth.md + children: + - file: users-roles/cluster-or-deployment-auth/quickstart.md + - file: users-roles/cluster-or-deployment-auth/user-authentication.md + children: + - file: users-roles/cluster-or-deployment-auth/authentication-realms.md + children: + - file: users-roles/cluster-or-deployment-auth/realm-chains.md + - file: users-roles/cluster-or-deployment-auth/security-domains.md + - file: users-roles/cluster-or-deployment-auth/internal-authentication.md + children: + - file: users-roles/cluster-or-deployment-auth/native.md + - file: users-roles/cluster-or-deployment-auth/file-based.md + - file: users-roles/cluster-or-deployment-auth/external-authentication.md + children: + - file: users-roles/cluster-or-deployment-auth/active-directory.md + - file: users-roles/cluster-or-deployment-auth/jwt.md + - file: users-roles/cluster-or-deployment-auth/kerberos.md + - file: users-roles/cluster-or-deployment-auth/ldap.md + - file: users-roles/cluster-or-deployment-auth/openid-connect.md + - file: users-roles/cluster-or-deployment-auth/saml.md + - file: users-roles/cluster-or-deployment-auth/pki.md + - file: users-roles/cluster-or-deployment-auth/custom.md + - file: users-roles/cluster-or-deployment-auth/built-in-users.md + - file: users-roles/cluster-or-deployment-auth/user-profiles.md + - file: users-roles/cluster-or-deployment-auth/access-agreement.md + - file: users-roles/cluster-or-deployment-auth/anonymous-access.md + - file: users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md + - file: users-roles/cluster-or-deployment-auth/token-based-authentication-services.md + - file: users-roles/cluster-or-deployment-auth/service-accounts.md + - file: users-roles/cluster-or-deployment-auth/internal-users.md + - file: users-roles/cluster-or-deployment-auth/operator-privileges.md + children: + - file: users-roles/cluster-or-deployment-auth/configure-operator-privileges.md + - file: users-roles/cluster-or-deployment-auth/operator-only-functionality.md + - file: users-roles/cluster-or-deployment-auth/operator-privileges-for-snapshot-restore.md + - file: users-roles/cluster-or-deployment-auth/looking-up-users-without-authentication.md + - file: users-roles/cluster-or-deployment-auth/controlling-user-cache.md + - file: users-roles/cluster-or-deployment-auth/user-roles.md + children: + - file: users-roles/cluster-or-deployment-auth/defining-roles.md + children: + - file: users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md + - file: users-roles/cluster-or-deployment-auth/role-restriction.md + - file: users-roles/cluster-or-deployment-auth/built-in-roles.md + - file: users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md + - file: users-roles/cluster-or-deployment-auth/kibana-privileges.md + - file: users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md + - file: users-roles/cluster-or-deployment-auth/authorization-delegation.md + - file: users-roles/cluster-or-deployment-auth/authorization-plugins.md + - file: users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md + - file: users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md + - file: manage-spaces.md + - file: api-keys.md + children: + - file: api-keys/elasticsearch-api-keys.md + - file: api-keys/serverless-project-api-keys.md + - file: api-keys/elastic-cloud-api-keys.md + - file: api-keys/elastic-cloud-enterprise-api-keys.md + - file: manage-connectors.md + - file: monitor.md + children: + - file: monitor/monitoring-overview.md + - file: monitor/autoops.md + children: + - file: monitor/autoops/ec-autoops-how-to-access.md + - file: monitor/autoops/ec-autoops-events.md + - file: monitor/autoops/ec-autoops-overview-view.md + - file: monitor/autoops/ec-autoops-deployment-view.md + - file: monitor/autoops/ec-autoops-nodes-view.md + - file: monitor/autoops/ec-autoops-index-view.md + - file: monitor/autoops/ec-autoops-shards-view.md + - file: monitor/autoops/ec-autoops-template-optimizer.md + - file: monitor/autoops/ec-autoops-notifications-settings.md + - file: monitor/autoops/ec-autoops-event-settings.md + - file: monitor/autoops/ec-autoops-dismiss-event.md + - file: monitor/autoops/ec-autoops-regions.md + - file: monitor/autoops/ec-autoops-faq.md + - file: monitor/stack-monitoring.md + children: + - file: monitor/stack-monitoring/stack-monitoring-on-elastic-cloud-deployments.md + - file: monitor/stack-monitoring/enable-stack-monitoring-on-eck-deployments.md + children: + - file: monitor/stack-monitoring/k8s_connect_to_an_external_monitoring_elasticsearch_cluster.md + - file: monitor/stack-monitoring/k8s_when_to_use_it.md + - file: monitor/stack-monitoring/k8s_how_it_works.md + - file: monitor/stack-monitoring/k8s_audit_logging.md + - file: monitor/stack-monitoring/k8s_override_the_beats_pod_template.md + - file: monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md + children: + - file: monitor/stack-monitoring/ece-restrictions-monitoring.md + - file: monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md + children: + - file: monitor/stack-monitoring/collecting-monitoring-data-with-elastic-agent.md + - file: monitor/stack-monitoring/collecting-monitoring-data-with-metricbeat.md + - file: monitor/stack-monitoring/collecting-log-data-with-filebeat.md + - file: monitor/stack-monitoring/legacy-collection-methods.md + children: + - file: monitor/stack-monitoring/es-monitoring-collectors.md + - file: monitor/stack-monitoring/es-monitoring-exporters.md + - file: monitor/stack-monitoring/local-exporter.md + - file: monitor/stack-monitoring/http-exporter.md + - file: monitor/stack-monitoring/pause-export.md + - file: monitor/stack-monitoring/kibana-monitoring-self-managed.md + children: + - file: monitor/stack-monitoring/monitoring-elastic-agent.md + - file: monitor/stack-monitoring/monitoring-metricbeat.md + - file: monitor/stack-monitoring/monitoring-data.md + - file: monitor/stack-monitoring/monitoring-kibana.md + - file: monitor/orchestrators.md + children: + - file: monitor/orchestrators/eck-metrics-configuration.md + children: + - file: monitor/orchestrators/k8s-enabling-metrics-endpoint.md + - file: monitor/orchestrators/k8s-securing-metrics-endpoint.md + - file: monitor/orchestrators/k8s-prometheus-requirements.md + - file: monitor/orchestrators/ece-platform-monitoring.md + children: + - file: monitor/orchestrators/ece-monitoring-ece-access.md + - file: monitor/orchestrators/ece-proxy-log-fields.md + - file: monitor/orchestrators/ece-monitoring-ece-set-retention.md + - file: monitor/monitoring-data.md + children: + - file: monitor/monitoring-data/visualizing-monitoring-data.md + children: + - file: monitor/monitoring-data/beats-page.md + - file: monitor/monitoring-data/elasticsearch-metrics.md + - file: monitor/monitoring-data/kibana-alerts.md + - file: monitor/monitoring-data/kibana-page.md + - file: monitor/monitoring-data/logstash-page.md + - file: monitor/monitoring-data/monitor-troubleshooting.md + - file: monitor/monitoring-data/access-performance-metrics-on-elastic-cloud.md + children: + - file: monitor/monitoring-data/ec-saas-metrics-accessing.md + children: + - file: monitor/monitoring-data/ec-memory-pressure.md + - file: monitor/monitoring-data/ec-vcpu-boost-instance.md + - file: monitor/monitoring-data/ech-saas-metrics-accessing.md + children: + - file: monitor/monitoring-data/ech-memory-pressure.md + - file: monitor/monitoring-data/ech-vcpu-boost-instance.md + - file: monitor/monitoring-data/configure-stack-monitoring-alerts.md + - file: monitor/monitoring-data/configuring-data-streamsindices-for-monitoring.md + children: + - file: monitor/monitoring-data/config-monitoring-data-streams-elastic-agent.md + - file: monitor/monitoring-data/config-monitoring-data-streams-metricbeat-8.md + - file: monitor/monitoring-data/config-monitoring-indices-metricbeat-7-internal-collection.md + - file: monitor/kibana-task-manager-health-monitoring.md + - file: monitor/logging-configuration.md + children: + - file: monitor/logging-configuration/elasticsearch-log4j-configuration-self-managed.md + - file: monitor/logging-configuration/update-elasticsearch-logging-levels.md + - file: monitor/logging-configuration/elasticsearch-deprecation-logs.md + - file: monitor/logging-configuration/kibana-logging.md + children: + - file: monitor/logging-configuration/log-settings-examples.md + - file: monitor/logging-configuration/_cli_configuration.md + - file: monitor/logging-configuration/security-event-audit-logging.md + children: + - file: monitor/logging-configuration/enabling-elasticsearch-audit-logs.md + children: + - file: monitor/logging-configuration/elasticsearch-audit-events.md + - file: monitor/logging-configuration/logfile-audit-output.md + - file: monitor/logging-configuration/logfile-audit-events-ignore-policies.md + - file: monitor/logging-configuration/auditing-search-queries.md + - file: monitor/logging-configuration/enabling-kibana-audit-logs.md + - file: monitor/logging-configuration/enabling-audit-logs-in-orchestrated-deployments.md + - file: monitor/logging-configuration/correlating-kibana-elasticsearch-audit-logs.md + - file: cloud-organization.md + children: + - file: cloud-organization/billing.md + children: + - file: cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.md + - file: cloud-organization/billing/serverless-project-billing-dimensions.md + children: + - file: cloud-organization/billing/elastic-observability-billing-dimensions.md + - file: cloud-organization/billing/elasticsearch-billing-dimensions.md + - file: cloud-organization/billing/security-billing-dimensions.md + - file: cloud-organization/billing/billing-models.md + - file: cloud-organization/billing/monitor-analyze-usage.md + - file: cloud-organization/billing/view-billing-history.md + - file: cloud-organization/billing/add-billing-details.md + - file: cloud-organization/billing/update-billing-operational-contacts.md + - file: cloud-organization/billing/billing-faq.md + - file: cloud-organization/billing/stop-charges-for-project-deployment.md + - file: cloud-organization/billing/manage-subscription.md + - file: cloud-organization/operational-emails.md + - file: cloud-organization/service-status.md + - file: cloud-organization/tools-and-apis.md + - file: license.md + children: + - file: license/manage-your-license-in-eck.md + - file: license/manage-your-license-in-ece.md + - file: license/manage-your-license-in-self-managed-cluster.md + - file: maintenance.md + children: + - file: maintenance/ece.md + children: + - file: maintenance/ece/deployments-maintenance.md + children: + - file: maintenance/ece/start-stop-routing-requests.md + - file: maintenance/ece/pause-instance.md + - file: maintenance/ece/maintenance-activities.md + children: + - file: maintenance/ece/enable-maintenance-mode.md + - file: maintenance/ece/scale-out-installation.md + - file: maintenance/ece/move-nodes-instances-from-allocators.md + - file: maintenance/ece/perform-ece-hosts-maintenance.md + - file: maintenance/ece/delete-ece-hosts.md + - file: maintenance/start-stop-services.md + children: + - file: maintenance/start-stop-services/start-stop-elasticsearch.md + - file: maintenance/start-stop-services/start-stop-kibana.md + - file: maintenance/start-stop-services/restart-cloud-hosted-deployment.md + - file: maintenance/start-stop-services/restart-an-ece-deployment.md + - file: maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md + - file: maintenance/add-and-remove-elasticsearch-nodes.md + - file: upgrade.md + children: + - file: upgrade/prepare-to-upgrade.md + children: + - file: upgrade/prepare-to-upgrade/upgrade-assistant.md + - file: upgrade/prepare-to-upgrade/index-compatibility.md + - file: upgrade/orchestrator.md + children: + - file: upgrade/orchestrator/upgrade-cloud-enterprise.md + - file: upgrade/orchestrator/upgrade-cloud-on-k8s.md + - file: upgrade/deployment-or-cluster.md + children: + - file: upgrade/deployment-or-cluster/archived-settings.md + children: + - file: upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md + - file: upgrade/internal-upgrade-processes.md + children: + - file: upgrade/internal-upgrade-processes/saved-object-migrations.md + - file: uninstall.md + children: + - file: uninstall/uninstall-elastic-cloud-enterprise.md + - file: uninstall/uninstall-elastic-cloud-on-kubernetes.md + - file: uninstall/uninstall-a-self-managed-cluster.md + - file: uninstall/delete-a-cloud-deployment.md \ No newline at end of file diff --git a/deploy-manage/tools.md b/deploy-manage/tools.md new file mode 100644 index 000000000..dbbe87b9f --- /dev/null +++ b/deploy-manage/tools.md @@ -0,0 +1,32 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/high-availability.html +--- + +# Backup, high availability, and resilience tools [high-availability] + +Your data is important to you. Keeping it safe and available is important to Elastic. Sometimes your cluster may experience hardware failure or a power loss. To help you plan for this, {{es}} offers a number of features to achieve high availability despite failures. Depending on your deployment type, you might need to provision servers in different zones or configure external repositories to meet your organization’s availability needs. + +* **[Design for resilience](production-guidance/availability-and-resilience.md)** + + Distributed systems like Elasticsearch are designed to keep working even if some of their components have failed. An Elasticsearch cluster can continue operating normally if some of its nodes are unavailable or disconnected, as long as there are enough well-connected nodes to take over the unavailable node’s responsibilities. + + If you’re designing a smaller cluster, you might focus on making your cluster resilient to single-node failures. Designers of larger clusters must also consider cases where multiple nodes fail at the same time. + +* **[Cross-cluster replication](tools/cross-cluster-replication.md)** + + To effectively distribute read and write operations across nodes, the nodes in a cluster need good, reliable connections to each other. To provide better connections, you typically co-locate the nodes in the same data center or nearby data centers. + + Co-locating nodes in a single location exposes you to the risk of a single outage taking your entire cluster offline. To maintain high availability, you can prepare a second cluster that can take over in case of disaster by implementing {{ccr}} (CCR). + + CCR provides a way to automatically synchronize indices from a leader cluster to a follower cluster. This cluster could be in a different data center or even a different content from the leader cluster. If the primary cluster fails, the secondary cluster can take over. + + ::::{tip} + You can also use CCR to create secondary clusters to serve read requests in geo-proximity to your users. + :::: + +* **[Snapshots](tools/snapshot-and-restore.md)** + + Take snapshots of your cluster that can be restored in case of failure. + + diff --git a/deploy-manage/tools/cross-cluster-replication.md b/deploy-manage/tools/cross-cluster-replication.md new file mode 100644 index 000000000..0f32c02a4 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication.md @@ -0,0 +1,231 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html +--- + +# Cross-cluster replication [xpack-ccr] + +With {{ccr}}, you can replicate indices across clusters to: + +* Continue handling search requests in the event of a datacenter outage +* Prevent search volume from impacting indexing throughput +* Reduce search latency by processing search requests in geo-proximity to the user + +{{ccr-cap}} uses an active-passive model. You index to a *leader* index, and the data is replicated to one or more read-only *follower* indices. Before you can add a follower index to a cluster, you must configure the *remote cluster* that contains the leader index. + +When the leader index receives writes, the follower indices pull changes from the leader index on the remote cluster. You can manually create follower indices, or configure auto-follow patterns to automatically create follower indices for new time series indices. + +You configure {{ccr}} clusters in a uni-directional or bi-directional setup: + +* In a uni-directional configuration, one cluster contains only leader indices, and the other cluster contains only follower indices. +* In a bi-directional configuration, each cluster contains both leader and follower indices. + +In a uni-directional configuration, the cluster containing follower indices must be running **the same or newer** version of {{es}} as the remote cluster. If newer, the versions must also be compatible as outlined in the following matrix. + +:::::{dropdown} Version compatibility matrix +:name: ccr-version-compatibility + +| | | +| --- | --- | +| | Local cluster | +| Remote cluster | 5.0–5.5 | 5.6 | 6.0–6.6 | 6.7 | 6.8 | 7.0 | 7.1–7.16 | 7.17 | 8.0–9.0 | +| 5.0–5.5 | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 5.6 | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 6.0–6.6 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 6.7 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 6.8 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 7.0 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 7.1–7.16 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | +| 7.17 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | +| 8.0–9.0 | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![No](https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | ![Yes](https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png "") | + +::::{note} +This documentation is for {{es}} version 9.0.0-beta1, which is not yet released. The above compatibility table applies if both clusters are running a released version of {{es}}, or if one of the clusters is running a released version and the other is running a pre-release build with a later build date. A cluster running a pre-release build of {{es}} can also communicate with remote clusters running the same pre-release build. Running a mix of pre-release builds is unsupported and typically will not work, even if the builds have the same version number. +:::: + + +::::: + + + +## Multi-cluster architectures [ccr-multi-cluster-architectures] + +Use {{ccr}} to construct several multi-cluster architectures within the Elastic Stack: + +* [Disaster recovery](#ccr-disaster-recovery) in case a primary cluster fails, with a secondary cluster serving as a hot backup +* [Data locality](#ccr-data-locality) to maintain multiple copies of the dataset close to the application servers (and users), and reduce costly latency +* [Centralized reporting](#ccr-centralized-reporting) for minimizing network traffic and latency in querying multiple geo-distributed {{es}} clusters, or for preventing search load from interfering with indexing by offloading search to a secondary cluster + +Watch the [{{ccr}} webinar](https://www.elastic.co/webinars/replicate-elasticsearch-data-with-cross-cluster-replication-ccr) to learn more about the following use cases. Then, [set up {{ccr}}](cross-cluster-replication/set-up-cross-cluster-replication.md) on your local machine and work through the demo from the webinar. + +::::{important} +In all of these use cases, you must [configure security](../security/manually-configure-security-in-self-managed-cluster.md) independently on every cluster. The security configuration is not replicated when configuring {{ccr}} for disaster recovery. To ensure that the {{es}} `security` feature state is backed up, [take snapshots](snapshot-and-restore/create-snapshots.md#back-up-specific-feature-state) regularly. You can then restore the native users, roles, and tokens from your security configuration. +:::: + + + +### Disaster recovery and high availability [ccr-disaster-recovery] + +Disaster recovery provides your mission-critical applications with the tolerance to withstand datacenter or region outages. This use case is the most common deployment of {{ccr}}. You can configure clusters in different architectures to support disaster recovery and high availability: + +* [Single disaster recovery datacenter](#ccr-single-datacenter-recovery) +* [Multiple disaster recovery datacenters](#ccr-multiple-datacenter-recovery) +* [Chained replication](#ccr-chained-replication) +* [Bi-directional replication](#ccr-bi-directional-replication) + + +#### Single disaster recovery datacenter [ccr-single-datacenter-recovery] + +In this configuration, data is replicated from the production datacenter to the disaster recovery datacenter. Because the follower indices replicate the leader index, your application can use the disaster recovery datacenter if the production datacenter is unavailable. + +:::{image} ../../images/elasticsearch-reference-ccr-arch-disaster-recovery.png +:alt: Production datacenter that replicates data to a disaster recovery datacenter +::: + + +#### Multiple disaster recovery datacenters [ccr-multiple-datacenter-recovery] + +You can replicate data from one datacenter to multiple datacenters. This configuration provides both disaster recovery and high availability, ensuring that data is replicated in two datacenters if the primary datacenter is down or unavailable. + +In the following diagram, data from Datacenter A is replicated to Datacenter B and Datacenter C, which both have a read-only copy of the leader index from Datacenter A. + +:::{image} ../../images/elasticsearch-reference-ccr-arch-multiple-dcs.png +:alt: Production datacenter that replicates data to two other datacenters +::: + + +#### Chained replication [ccr-chained-replication] + +You can replicate data across multiple datacenters to form a replication chain. In the following diagram, Datacenter A contains the leader index. Datacenter B replicates data from Datacenter A, and Datacenter C replicates from the follower indices in Datacenter B. The connection between these datacenters forms a chained replication pattern. + +:::{image} ../../images/elasticsearch-reference-ccr-arch-chain-dcs.png +:alt: Three datacenters connected to form a replication chain +::: + + +#### Bi-directional replication [ccr-bi-directional-replication] + +In a [bi-directional replication](https://www.elastic.co/blog/bi-directional-replication-with-elasticsearch-cross-cluster-replication-ccr) setup, all clusters have access to view all data, and all clusters have an index to write to without manually implementing failover. Applications can write to the local index within each datacenter, and read across multiple indices for a global view of all information. + +This configuration requires no manual intervention when a cluster or datacenter is unavailable. In the following diagram, if Datacenter A is unavailable, you can continue using Datacenter B without manual failover. When Datacenter A comes online, replication resumes between the clusters. + +:::{image} ../../images/elasticsearch-reference-ccr-arch-bi-directional.png +:alt: Bi-directional configuration where each cluster contains both a leader index and follower indices +::: + +This configuration is particularly useful for index-only workloads, where no updates to document values occur. In this configuration, documents indexed by {{es}} are immutable. Clients are located in each datacenter alongside the {{es}} cluster, and do not communicate with clusters in different datacenters. + + +### Data locality [ccr-data-locality] + +Bringing data closer to your users or application server can reduce latency and response time. This methodology also applies when replicating data in {{es}}. For example, you can replicate a product catalog or reference dataset to 20 or more datacenters around the world to minimize the distance between the data and the application server. + +In the following diagram, data is replicated from one datacenter to three additional datacenters, each in their own region. The central datacenter contains the leader index, and the additional datacenters contain follower indices that replicate data in that particular region. This configuration puts data closer to the application accessing it. + +:::{image} ../../images/elasticsearch-reference-ccr-arch-data-locality.png +:alt: A centralized datacenter replicated across three other datacenters +::: + + +### Centralized reporting [ccr-centralized-reporting] + +Using a centralized reporting cluster is useful when querying across a large network is inefficient. In this configuration, you replicate data from many smaller clusters to the centralized reporting cluster. + +For example, a large global bank might have 100 {{es}} clusters around the world that are distributed across different regions for each bank branch. Using {{ccr}}, the bank can replicate events from all 100 banks to a central cluster to analyze and aggregate events locally for reporting. Rather than maintaining a mirrored cluster, the bank can use {{ccr}} to replicate specific indices. + +In the following diagram, data from three datacenters in different regions is replicated to a centralized reporting cluster. This configuration enables you to copy data from regional hubs to a central cluster, where you can run all reports locally. + +:::{image} ../../images/elasticsearch-reference-ccr-arch-central-reporting.png +:alt: Three clusters in different regions sending data to a centralized reporting cluster for analysis +::: + + +## Replication mechanics [ccr-replication-mechanics] + +Although you [set up {{ccr}}](cross-cluster-replication/set-up-cross-cluster-replication.md) at the index level, {{es}} achieves replication at the shard level. When a follower index is created, each shard in that index pulls changes from its corresponding shard in the leader index, which means that a follower index has the same number of shards as its leader index. All operations on the leader are replicated by the follower, such as operations to create, update, or delete a document. These requests can be served from any copy of the leader shard (primary or replica). + +When a follower shard sends a read request, the leader shard responds with any new operations, limited by the read parameters that you establish when configuring the follower index. If no new operations are available, the leader shard waits up to the configured timeout for new operations. If the timeout elapses, the leader shard responds to the follower shard that there are no new operations. The follower shard updates shard statistics and immediately sends another read request to the leader shard. This communication model ensures that network connections between the remote cluster and the local cluster are continually in use, avoiding forceful termination by an external source such as a firewall. + +If a read request fails, the cause of the failure is inspected. If the cause of the failure is deemed to be recoverable (such as a network failure), the follower shard enters into a retry loop. Otherwise, the follower shard pauses [until you resume it](cross-cluster-replication/ccr-pause-replication.md). + + +### Processing updates [ccr-update-leader-index] + +You can’t manually modify a follower index’s mappings or aliases. To make changes, you must update the leader index. Because they are read-only, follower indices reject writes in all configurations. + +::::{note} +Although changes to aliases on the leader index are replicated to follower indices, write indices are ignored. Follower indices can’t accept direct writes, so if any leader aliases have `is_write_index` set to `true`, that value is forced to `false`. +:::: + + +For example, you index a document named `doc_1` in Datacenter A, which replicates to Datacenter B. If a client connects to Datacenter B and attempts to update `doc_1`, the request fails. To update `doc_1`, the client must connect to Datacenter A and update the document in the leader index. + +When a follower shard receives operations from the leader shard, it places those operations in a write buffer. The follower shard submits bulk write requests using operations from the write buffer. If the write buffer exceeds its configured limits, no additional read requests are sent. This configuration provides a back-pressure against read requests, allowing the follower shard to resume sending read requests when the write buffer is no longer full. + +To manage how operations are replicated from the leader index, you can configure settings when [creating the follower index](cross-cluster-replication/ccr-getting-started-follower-index.md). + +Changes in the index mapping on the leader index are replicated to the follower index as soon as possible. This behavior is true for index settings as well, except for some settings that are local to the leader index. For example, changing the number of replicas on the leader index is not replicated by the follower index, so that setting might not be retrieved. + +If you apply a non-dynamic settings change to the leader index that is needed by the follower index, the follower index closes itself, applies the settings update, and then re-opens itself. The follower index is unavailable for reads and cannot replicate writes during this cycle. + + +## Initializing followers using remote recovery [ccr-remote-recovery] + +When you create a follower index, you cannot use it until it is fully initialized. The *remote recovery* process builds a new copy of a shard on a follower node by copying data from the primary shard in the leader cluster. + +{{es}} uses this remote recovery process to bootstrap a follower index using the data from the leader index. This process provides the follower with a copy of the current state of the leader index, even if a complete history of changes is not available on the leader due to Lucene segment merging. + +Remote recovery is a network intensive process that transfers all of the Lucene segment files from the leader cluster to the follower cluster. The follower requests that a recovery session be initiated on the primary shard in the leader cluster. The follower then requests file chunks concurrently from the leader. By default, the process concurrently requests five 1MB file chunks. This default behavior is designed to support leader and follower clusters with high network latency between them. + +::::{tip} +You can modify dynamic [remote recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-settings.html#ccr-recovery-settings) to rate-limit the transmitted data and manage the resources consumed by remote recoveries. +:::: + + +Use the [recovery API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-recovery.html) on the cluster containing the follower index to obtain information about an in-progress remote recovery. Because {{es}} implements remote recoveries using the [snapshot and restore](snapshot-and-restore.md) infrastructure, running remote recoveries are labelled as type `snapshot` in the recovery API. + + +## Replicating a leader requires soft deletes [ccr-leader-requirements] + +{{ccr-cap}} works by replaying the history of individual write operations that were performed on the shards of the leader index. {{es}} needs to retain the [history of these operations](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-history-retention.html) on the leader shards so that they can be pulled by the follower shard tasks. The underlying mechanism used to retain these operations is *soft deletes*. + +A soft delete occurs whenever an existing document is deleted or updated. By retaining these soft deletes up to configurable limits, the history of operations can be retained on the leader shards and made available to the follower shard tasks as it replays the history of operations. + +The [`index.soft_deletes.retention_lease.period`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#ccr-index-soft-deletes-retention-period) setting defines the maximum time to retain a shard history retention lease before it is considered expired. This setting determines how long the cluster containing your follower index can be offline, which is 12 hours by default. If a shard copy recovers after its retention lease expires, but the missing operations are still available on the leader index, then {{es}} will establish a new lease and copy the missing operations. However {{es}} does not guarantee to retain unleased operations, so it is also possible that some of the missing operations have been discarded by the leader and are now completely unavailable. If this happens then the follower cannot recover automatically so you must [recreate it](cross-cluster-replication/ccr-recreate-follower-index.md). + +Soft deletes must be enabled for indices that you want to use as leader indices. Soft deletes are enabled by default on new indices created on or after {{es}} 7.0.0. + +::::{important} +{{ccr-cap}} cannot be used on existing indices created using {{es}} 7.0.0 or earlier, where soft deletes are disabled. You must [reindex](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) your data into a new index with soft deletes enabled. +:::: + + + +## Use {{ccr}} [ccr-learn-more] + +This following sections provide more information about how to configure and use {{ccr}}: + +* [Set up {{ccr}}](cross-cluster-replication/set-up-cross-cluster-replication.md) +* [*Manage {{ccr}}*](cross-cluster-replication/manage-cross-cluster-replication.md) +* [*Manage auto-follow patterns*](cross-cluster-replication/manage-auto-follow-patterns.md) +* [Upgrading clusters](cross-cluster-replication/upgrading-clusters.md) + + +## {{ccr-cap}} limitations [ccr-limitations] + +{{ccr-cap}} is designed to replicate user-generated indices only, and doesn’t currently replicate any of the following: + +* [System indices](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#system-indices) +* [Machine learning jobs](../../explore-analyze/machine-learning.md) +* [index templates](../../manage-data/data-store/templates.md) +* [{{ilm-cap}}](../../manage-data/lifecycle/index-lifecycle-management.md) and [{{slm}}](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management-api.html) polices +* [User permissions and role mappings](../users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) +* [Snapshot repository settings](snapshot-and-restore/self-managed.md) +* [Cluster settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html) +* [Searchable snapshot](snapshot-and-restore/searchable-snapshots.md) + +If you want to replicate any of this data, you must replicate it to a remote cluster manually. + +::::{note} +Data for [searchable snapshot](snapshot-and-restore/searchable-snapshots.md) indices is stored in the snapshot repository. {{ccr-cap}} won’t replicate these indices completely, even though they’re either partially or fully-cached on the {{es}} nodes. To achieve searchable snapshots in a remote cluster, configure snapshot repositories on the remote cluster and use the same {{ilm}} policy from the local cluster to move data into the cold or frozen tiers on the remote cluster. +:::: diff --git a/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md b/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md new file mode 100644 index 000000000..b3f31f78b --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md @@ -0,0 +1,88 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_configure_privileges_for_cross_cluster_replication_2.html +--- + +# Configure privileges for cross-cluster replication [_configure_privileges_for_ccr_2] + +The {{ccr}} user requires different cluster and index privileges on the remote cluster and local cluster. Use the following requests to create separate roles on the local and remote clusters, and then create a user with the required roles. + + +## Remote cluster [_remote_cluster_4] + +On the remote cluster that contains the leader index, the {{ccr}} role requires the `read_ccr` cluster privilege, and `monitor` and `read` privileges on the leader index. + +::::{note} +If requests are authenticated with an [API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), the API key requires the above privileges on the **local** cluster, instead of the remote. +:::: + + +::::{note} +If requests are issued [on behalf of other users](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the `run_as` privilege on the remote cluster. +:::: + + +The following request creates a `remote-replication` role on the remote cluster: + +```console +POST /_security/role/remote-replication +{ + "cluster": [ + "read_ccr" + ], + "indices": [ + { + "names": [ + "leader-index-name" + ], + "privileges": [ + "monitor", + "read" + ] + } + ] +} +``` + + +## Local cluster [_local_cluster_4] + +On the local cluster that contains the follower index, the `remote-replication` role requires the `manage_ccr` cluster privilege, and `monitor`, `read`, `write`, and `manage_follow_index` privileges on the follower index. + +The following request creates a `remote-replication` role on the local cluster: + +```console +POST /_security/role/remote-replication +{ + "cluster": [ + "manage_ccr" + ], + "indices": [ + { + "names": [ + "follower-index-name" + ], + "privileges": [ + "monitor", + "read", + "write", + "manage_follow_index" + ] + } + ] +} +``` + +After creating the `remote-replication` role on each cluster, use the [create or update users API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html) to create a user on the local cluster cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: + +```console +POST /_security/user/cross-cluster-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-replication" ] +} +``` + +::::{note} +You only need to create this user on the **local** cluster. +:::: diff --git a/deploy-manage/tools/cross-cluster-replication/_connect_to_a_remote_cluster.md b/deploy-manage/tools/cross-cluster-replication/_connect_to_a_remote_cluster.md new file mode 100644 index 000000000..5fc01b35a --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_connect_to_a_remote_cluster.md @@ -0,0 +1,72 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_connect_to_a_remote_cluster.html +--- + +# Connect to a remote cluster [_connect_to_a_remote_cluster] + +To replicate an index on a remote cluster (Cluster A) to a local cluster (Cluster B), you configure Cluster A as a remote on Cluster B. + +:::{image} ../../../images/elasticsearch-reference-ccr-tutorial-clusters.png +:alt: ClusterA contains the leader index and ClusterB contains the follower index +::: + +To configure a remote cluster from Stack Management in {{kib}}: + +1. Set up a [secure connection](https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters.html#add-remote-clusters) as needed. +2. Select **Remote Clusters** from the side navigation. +3. Specify the {{es}} endpoint URL, or the IP address or host name of the remote cluster (`ClusterA`) followed by the transport port (defaults to `9300`). For example, `cluster.es.eastus2.staging.azure.foundit.no:9400` or `192.168.1.1:9300`. + +::::{dropdown} API example +You can also use the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) to add a remote cluster: + +```console +PUT /_cluster/settings +{ + "persistent" : { + "cluster" : { + "remote" : { + "leader" : { + "seeds" : [ + "127.0.0.1:9300" <1> + ] + } + } + } + } +} +``` + +1. Specifies the hostname and transport port of a seed node in the remote cluster. + + +You can verify that the local cluster is successfully connected to the remote cluster. + +```console +GET /_remote/info +``` + +The API response indicates that the local cluster is connected to the remote cluster with cluster alias `leader`. + +```console-result +{ + "leader" : { + "seeds" : [ + "127.0.0.1:9300" + ], + "connected" : true, + "num_nodes_connected" : 1, <1> + "max_connections_per_cluster" : 3, + "initial_connect_timeout" : "30s", + "skip_unavailable" : true, + "mode" : "sniff" + } +} +``` + +1. The number of nodes in the remote cluster the local cluster is connected to. + + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/_failback_when_clustera_comes_back.md b/deploy-manage/tools/cross-cluster-replication/_failback_when_clustera_comes_back.md new file mode 100644 index 000000000..86a31375b --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_failback_when_clustera_comes_back.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_failback_when_clustera_comes_back.html +--- + +# Failback when clusterA comes back [_failback_when_clustera_comes_back] + +When `clusterA` comes back, `clusterB` becomes the new leader and `clusterA` becomes the follower. + +1. Set up remote cluster `clusterB` on `clusterA`. + + ```console + ### On clusterA ### + PUT _cluster/settings + { + "persistent": { + "cluster": { + "remote": { + "clusterB": { + "mode": "proxy", + "skip_unavailable": "true", + "server_name": "clusterb.es.region-b.gcp.elastic-cloud.com", + "proxy_socket_connections": "18", + "proxy_address": "clusterb.es.region-b.gcp.elastic-cloud.com:9400" + } + } + } + } + } + ``` + +2. Existing data needs to be discarded before you can turn any index into a follower. Ensure the most up-to-date data is available on `clusterB` prior to deleting any indices on `clusterA`. + + ```console + ### On clusterA ### + DELETE kibana_sample_data_ecommerce + ``` + +3. Create a follower index on `clusterA`, now following the leader index in `clusterB`. + + ```console + ### On clusterA ### + PUT /kibana_sample_data_ecommerce/_ccr/follow?wait_for_active_shards=1 + { + "remote_cluster": "clusterB", + "leader_index": "kibana_sample_data_ecommerce2" + } + ``` + +4. The index on the follower cluster now contains the updated documents. + + ```console + ### On clusterA ### + GET kibana_sample_data_ecommerce/_search?q=kimchy + ``` + + ::::{tip} + If a soft delete is merged away before it can be replicated to a follower the following process will fail due to incomplete history on the leader, see [index.soft_deletes.retention_lease.period](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#ccr-index-soft-deletes-retention-period) for more details. + :::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/_failback_when_clustera_comes_back_2.md b/deploy-manage/tools/cross-cluster-replication/_failback_when_clustera_comes_back_2.md new file mode 100644 index 000000000..e8bea8a79 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_failback_when_clustera_comes_back_2.md @@ -0,0 +1,22 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_failback_when_clustera_comes_back_2.html +--- + +# Failback when clusterA comes back [_failback_when_clustera_comes_back_2] + +1. You can simulate this by turning `cluster A` back on. +2. Data ingested to `cluster B` during `cluster A` 's downtime will be automatically replicated. + + * data streams on cluster A + + * 150 documents in `logs-generic-default-replicated_from_clusterb` + * 50 documents in `logs-generic-default` + + * data streams on cluster B + + * 50 documents in `logs-generic-default-replicated_from_clustera` + * 150 documents in `logs-generic-default` + +3. If you have {{ls}} running at this time, you will also observe traffic is sent to both clusters. + diff --git a/deploy-manage/tools/cross-cluster-replication/_failover_when_clustera_is_down.md b/deploy-manage/tools/cross-cluster-replication/_failover_when_clustera_is_down.md new file mode 100644 index 000000000..784cb8960 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_failover_when_clustera_is_down.md @@ -0,0 +1,33 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_failover_when_clustera_is_down.html +--- + +# Failover when clusterA is down [_failover_when_clustera_is_down] + +1. Promote the follower indices in `clusterB` into regular indices so that they accept writes. This can be achieved by: + + * First, pause indexing following for the follower index. + * Next, close the follower index. + * Unfollow the leader index. + * Finally, open the follower index (which at this point is a regular index). + + ```console + ### On clusterB ### + POST /kibana_sample_data_ecommerce2/_ccr/pause_follow + POST /kibana_sample_data_ecommerce2/_close + POST /kibana_sample_data_ecommerce2/_ccr/unfollow + POST /kibana_sample_data_ecommerce2/_open + ``` + +2. On the client side ({{ls}}, {{beats}}, {{agent}}), manually re-enable ingestion of `kibana_sample_data_ecommerce2` and redirect traffic to the `clusterB`. You should also redirect all search traffic to the `clusterB` cluster during this time. You can simulate this by ingesting documents into this index. You should notice this index is now writable. + + ```console + ### On clusterB ### + POST kibana_sample_data_ecommerce2/_doc/ + { + "user": "kimchy" + } + ``` + + diff --git a/deploy-manage/tools/cross-cluster-replication/_failover_when_clustera_is_down_2.md b/deploy-manage/tools/cross-cluster-replication/_failover_when_clustera_is_down_2.md new file mode 100644 index 000000000..36b6b2693 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_failover_when_clustera_is_down_2.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_failover_when_clustera_is_down_2.html +--- + +# Failover when clusterA is down [_failover_when_clustera_is_down_2] + +1. You can simulate this by shutting down either of the clusters. Let’s shut down `cluster A` in this tutorial. +2. Start {{ls}} with the same configuration file. (This step is not required in real use cases where {{ls}} ingests continuously.) + + ```sh + ### On Logstash server ### + bin/logstash -f multiple_hosts.conf + ``` + +3. Observe all {{ls}} traffic will be redirected to `cluster B` automatically. + + ::::{tip} + You should also redirect all search traffic to the `clusterB` cluster during this time. + :::: + +4. The two data streams on `cluster B` now contain a different number of documents. + + * data streams on cluster A (down) + + * 50 documents in `logs-generic-default-replicated_from_clusterb` + * 50 documents in `logs-generic-default` + + * data streams On cluster B (up) + + * 50 documents in `logs-generic-default-replicated_from_clustera` + * 150 documents in `logs-generic-default` + + diff --git a/deploy-manage/tools/cross-cluster-replication/_perform_update_or_delete_by_query.md b/deploy-manage/tools/cross-cluster-replication/_perform_update_or_delete_by_query.md new file mode 100644 index 000000000..e2e7fabcb --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_perform_update_or_delete_by_query.md @@ -0,0 +1,53 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_perform_update_or_delete_by_query.html +--- + +# Perform update or delete by query [_perform_update_or_delete_by_query] + +It is possible to update or delete the documents but you can only perform these actions on the leader index. + +1. First identify which backing index contains the document you want to update. + + ```console + ### On either of the cluster ### + GET logs-generic-default*/_search?filter_path=hits.hits._index + { + "query": { + "match": { + "event.sequence": "97" + } + } + } + ``` + + * If the hits returns `"_index": ".ds-logs-generic-default-replicated_from_clustera--*"`, then you need to proceed to the next step on `cluster A`. + * If the hits returns `"_index": ".ds-logs-generic-default-replicated_from_clusterb--*"`, then you need to proceed to the next step on `cluster B`. + * If the hits returns `"_index": ".ds-logs-generic-default--*"`, then you need to proceed to the next step on the same cluster where you performed the search query. + +2. Perform the update (or delete) by query: + + ```console + ### On the cluster identified from the previous step ### + POST logs-generic-default/_update_by_query + { + "query": { + "match": { + "event.sequence": "97" + } + }, + "script": { + "source": "ctx._source.event.original = params.new_event", + "lang": "painless", + "params": { + "new_event": "FOOBAR" + } + } + } + ``` + + ::::{tip} + If a soft delete is merged away before it can be replicated to a follower the following process will fail due to incomplete history on the leader, see [index.soft_deletes.retention_lease.period](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#ccr-index-soft-deletes-retention-period) for more details. + :::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/_prerequisites_14.md b/deploy-manage/tools/cross-cluster-replication/_prerequisites_14.md new file mode 100644 index 000000000..3a0cc99e7 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/_prerequisites_14.md @@ -0,0 +1,45 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_prerequisites_14.html +--- + +# Prerequisites [_prerequisites_14] + +Before completing this tutorial, [set up cross-cluster replication](set-up-cross-cluster-replication.md) to connect two clusters and configure a follower index. + +In this tutorial, `kibana_sample_data_ecommerce` is replicated from `clusterA` to `clusterB`. + +```console +## On clusterB ### +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "clusterA": { + "mode": "proxy", + "skip_unavailable": "true", + "server_name": "clustera.es.region-a.gcp.elastic-cloud.com", + "proxy_socket_connections": "18", + "proxy_address": "clustera.es.region-a.gcp.elastic-cloud.com:9400" + } + } + } + } +} +``` + +```console +## On clusterB ### +PUT /kibana_sample_data_ecommerce2/_ccr/follow?wait_for_active_shards=1 +{ + "remote_cluster": "clusterA", + "leader_index": "kibana_sample_data_ecommerce" +} +``` + +::::{important} +Writes (such as ingestion or updates) should occur only on the leader index. Follower indices are read-only and will reject any writes. +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/bi-directional-disaster-recovery.md b/deploy-manage/tools/cross-cluster-replication/bi-directional-disaster-recovery.md new file mode 100644 index 000000000..ca37398a2 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/bi-directional-disaster-recovery.md @@ -0,0 +1,27 @@ +--- +navigation_title: "Bi-directional disaster recovery" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-disaster-recovery-bi-directional-tutorial.html +--- + + + +# Bi-directional disaster recovery [ccr-disaster-recovery-bi-directional-tutorial] + + +Learn how to set up disaster recovery between two clusters based on bi-directional {{ccr}}. The following tutorial is designed for data streams which support [update by query](../../../manage-data/data-store/index-types/use-data-stream.md#update-docs-in-a-data-stream-by-query) and [delete by query](../../../manage-data/data-store/index-types/use-data-stream.md#delete-docs-in-a-data-stream-by-query). You can only perform these actions on the leader index. + +This tutorial works with {{ls}} as the source of ingestion. It takes advantage of a {{ls}} feature where [the {{ls}} output to {{es}}](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-elasticsearch.html) can be load balanced across an array of hosts specified. {{beats}} and {{agents}} currently do not support multiple outputs. It should also be possible to set up a proxy (load balancer) to redirect traffic without {{ls}} in this tutorial. + +* Setting up a remote cluster on `clusterA` and `clusterB`. +* Setting up bi-directional cross-cluster replication with exclusion patterns. +* Setting up {{ls}} with multiple hosts to allow automatic load balancing and switching during disasters. + +:::{image} ../../../images/elasticsearch-reference-ccr-bi-directional-disaster-recovery.png +:alt: Bi-directional cross cluster replication failover and failback +::: + + + + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-create.md b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-create.md new file mode 100644 index 000000000..f356aadfd --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-create.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow-create.html +--- + +# Create auto-follow patterns [ccr-auto-follow-create] + +When you [create an auto-follow pattern](ccr-getting-started-auto-follow.md), you are configuring a collection of patterns against a single remote cluster. When an index is created in the remote cluster with a name that matches one of the patterns in the collection, a follower index is configured in the local cluster. The follower index uses the new index as its leader index. + +Use the [create auto-follow pattern API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-auto-follow-pattern.html) to add a new auto-follow pattern configuration. + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-delete.md b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-delete.md new file mode 100644 index 000000000..0dcdb8d92 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-delete.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow-delete.html +--- + +# Delete auto-follow patterns [ccr-auto-follow-delete] + +To delete an auto-follow pattern collection, [access {{kib}}](manage-auto-follow-patterns.md#ccr-access-ccr-auto-follow), select the auto-follow pattern, and pause replication. + +When the pattern status changes to Paused, choose **Manage pattern > Delete pattern**. + +Use the [delete auto-follow pattern API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-delete-auto-follow-pattern.html) to delete a configured auto-follow pattern collection. + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-pause.md b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-pause.md new file mode 100644 index 000000000..882f05593 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-pause.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow-pause.html +--- + +# Pause and resume auto-follow patterns [ccr-auto-follow-pause] + +To pause and resume replication of auto-follow pattern collections, [access {{kib}}](manage-auto-follow-patterns.md#ccr-access-ccr-auto-follow), select the auto-follow pattern, and pause replication. + +To resume replication, select the pattern and choose **Manage pattern > Resume replication**. + +Use the [pause auto-follow pattern API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-pause-auto-follow-pattern.html) to pause auto-follow patterns. Use the [resume auto-follow pattern API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-resume-auto-follow-pattern.html) to resume auto-follow patterns. + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-retrieve.md b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-retrieve.md new file mode 100644 index 000000000..ffdac7ddb --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-auto-follow-retrieve.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow-retrieve.html +--- + +# Retrieve auto-follow patterns [ccr-auto-follow-retrieve] + +To view existing auto-follow patterns and make changes to the backing patterns, [access {{kib}}](manage-auto-follow-patterns.md#ccr-access-ccr-auto-follow) on your *remote* cluster. + +Select the auto-follow pattern that you want to view details about. From there, you can make changes to the auto-follow pattern. You can also view your follower indices included in the auto-follow pattern. + +Use the [get auto-follow pattern API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-auto-follow-pattern.html) to inspect all configured auto-follow pattern collections. + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-bi-directional-upgrade.md b/deploy-manage/tools/cross-cluster-replication/ccr-bi-directional-upgrade.md new file mode 100644 index 000000000..c5ffe3757 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-bi-directional-upgrade.md @@ -0,0 +1,13 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-bi-directional-upgrade.html +--- + +# Bi-directional index following [ccr-bi-directional-upgrade] + +In a bi-directional configuration, each cluster contains both leader and follower indices. + +When upgrading clusters in this configuration, [pause all index following](ccr-pause-replication.md) and [pause auto-follow patterns](ccr-auto-follow-pause.md) prior to upgrading both clusters. + +After upgrading both clusters, resume index following and resume replication of auto-follow patterns. + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-auto-follow.md b/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-auto-follow.md new file mode 100644 index 000000000..c015a003b --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-auto-follow.md @@ -0,0 +1,50 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-getting-started-auto-follow.html +--- + +# Create an auto-follow pattern to replicate time series indices [ccr-getting-started-auto-follow] + +You use [auto-follow patterns](manage-auto-follow-patterns.md) to automatically create new followers for rolling time series indices. Whenever the name of a new index on the remote cluster matches the auto-follow pattern, a corresponding follower index is added to the local cluster. Note that only indices created on the remote cluster after the auto-follow pattern is created will be auto-followed: existing indices on the remote cluster are ignored even if they match the pattern. + +An auto-follow pattern specifies the remote cluster you want to replicate from, and one or more index patterns that specify the rolling time series indices you want to replicate. + +To create an auto-follow pattern from Stack Management in {{kib}}: + +1. Select **Cross Cluster Replication** in the side navigation and choose the **Auto-follow patterns** tab. +2. Enter a name for the auto-follow pattern, such as `beats`. +3. Choose the remote cluster that contains the index you want to replicate, which in the example scenario is Cluster A. +4. Enter one or more index patterns that identify the indices you want to replicate from the remote cluster. For example, enter `metricbeat-* packetbeat-*` to automatically create followers for {{metricbeat}} and {{packetbeat}} indices. +5. Enter **follower-** as the prefix to apply to the names of the follower indices so you can more easily identify replicated indices. + +As new indices matching these patterns are created on the remote, {{es}} automatically replicates them to local follower indices. + +:::{image} ../../../images/elasticsearch-reference-auto-follow-patterns.png +:alt: The Auto-follow patterns page in {kib} +:class: screenshot +::: + +::::{dropdown} API example +Use the [create auto-follow pattern API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-auto-follow-pattern.html) to configure auto-follow patterns. + +```console +PUT /_ccr/auto_follow/beats +{ + "remote_cluster" : "leader", + "leader_index_patterns" : + [ + "metricbeat-*", <1> + "packetbeat-*" <2> + ], + "follow_index_pattern" : "{{leader_index}}-copy" <3> +} +``` + +1. Automatically follow new {{metricbeat}} indices. +2. Automatically follow new {{packetbeat}} indices. +3. The name of the follower index is derived from the name of the leader index by adding the suffix `-copy` to the name of the leader index. + + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-follower-index.md b/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-follower-index.md new file mode 100644 index 000000000..ae41820f2 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-follower-index.md @@ -0,0 +1,43 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-getting-started-follower-index.html +--- + +# Create a follower index to replicate a specific index [ccr-getting-started-follower-index] + +When you create a follower index, you reference the remote cluster and the leader index in your remote cluster. + +To create a follower index from Stack Management in {{kib}}: + +1. Select **Cross-Cluster Replication** in the side navigation and choose the **Follower Indices** tab. +2. Choose the cluster (ClusterA) containing the leader index you want to replicate. +3. Enter the name of the leader index, which is `kibana_sample_data_ecommerce` if you are following the tutorial. +4. Enter a name for your follower index, such as `follower-kibana-sample-data`. + +{{es}} initializes the follower using the [remote recovery](../cross-cluster-replication.md#ccr-remote-recovery) process, which transfers the existing Lucene segment files from the leader index to the follower index. The index status changes to **Paused**. When the remote recovery process is complete, the index following begins and the status changes to **Active**. + +When you index documents into your leader index, {{es}} replicates the documents in the follower index. + +:::{image} ../../../images/elasticsearch-reference-ccr-follower-index.png +:alt: The Cross-Cluster Replication page in {kib} +:class: screenshot +::: + +::::{dropdown} API example +You can also use the [create follower API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-follow.html) to create follower indices. When you create a follower index, you must reference the remote cluster and the leader index that you created in the remote cluster. + +When initiating the follower request, the response returns before the [remote recovery](../cross-cluster-replication.md#ccr-remote-recovery) process completes. To wait for the process to complete, add the `wait_for_active_shards` parameter to your request. + +```console +PUT /server-metrics-follower/_ccr/follow?wait_for_active_shards=1 +{ + "remote_cluster" : "leader", + "leader_index" : "server-metrics" +} +``` + +Use the [get follower stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-stats.html) to inspect the status of replication. + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-prerequisites.md b/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-prerequisites.md new file mode 100644 index 000000000..4453460fc --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-getting-started-prerequisites.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-getting-started-prerequisites.html +--- + +# Prerequisites [ccr-getting-started-prerequisites] + +To complete this tutorial, you need: + +* The `manage` cluster privilege on the local cluster. +* A license on both clusters that includes {{ccr}}. [Activate a free 30-day trial](../../license/manage-your-license-in-self-managed-cluster.md). +* An index on the remote cluster that contains the data you want to replicate. This tutorial uses the sample eCommerce orders data set. [Load sample data](../../../explore-analyze/overview/kibana-quickstart.md#gs-get-data-into-kibana). +* In the local cluster, all nodes with the `master` [node role](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#node-roles) must also have the [`remote_cluster_client`](../../distributed-architecture/clusters-nodes-shards/node-roles.md#remote-node) role. The local cluster must also have at least one node with both a data role and the [`remote_cluster_client`](../../distributed-architecture/clusters-nodes-shards/node-roles.md#remote-node) role. Individual tasks for coordinating replication scale based on the number of data nodes with the `remote_cluster_client` role in the local cluster. + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-inspect-progress.md b/deploy-manage/tools/cross-cluster-replication/ccr-inspect-progress.md new file mode 100644 index 000000000..faab724e4 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-inspect-progress.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-inspect-progress.html +--- + +# Inspect replication statistics [ccr-inspect-progress] + +To inspect the progress of replication for a follower index and view detailed shard statistics, [access Cross-Cluster Replication](manage-cross-cluster-replication.md#ccr-access-ccr) and choose the **Follower indices** tab. + +Select the name of the follower index you want to view replication details for. The slide-out panel shows settings and replication statistics for the follower index, including read and write operations that are managed by the follower shard. + +To view more detailed statistics, click **View in Index Management**, and then select the name of the follower index in Index Management. Open the tabs for detailed statistics about the follower index. + +::::{dropdown} API example +Use the [get follower stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-stats.html) to inspect replication progress at the shard level. This API provides insight into the read and writes managed by the follower shard. The API also reports read exceptions that can be retried and fatal exceptions that require user intervention. + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-pause-replication.md b/deploy-manage/tools/cross-cluster-replication/ccr-pause-replication.md new file mode 100644 index 000000000..ee532bf24 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-pause-replication.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-pause-replication.html +--- + +# Pause and resume replication [ccr-pause-replication] + +To pause and resume replication of the leader index, [access Cross-Cluster Replication](manage-cross-cluster-replication.md#ccr-access-ccr) and choose the **Follower indices** tab. + +Select the follower index you want to pause and choose **Manage > Pause Replication**. The follower index status changes to Paused. + +To resume replication, select the follower index and choose **Resume replication**. + +::::{dropdown} API example +You can pause replication with the [pause follower API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-pause-follow.html) and then later resume replication with the [resume follower API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-resume-follow.html). Using these APIs in tandem enables you to adjust the read and write parameters on the follower shard task if your initial configuration is not suitable for your use case. + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-recreate-follower-index.md b/deploy-manage/tools/cross-cluster-replication/ccr-recreate-follower-index.md new file mode 100644 index 000000000..115469d84 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-recreate-follower-index.md @@ -0,0 +1,46 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-recreate-follower-index.html +--- + +# Recreate a follower index [ccr-recreate-follower-index] + +When a document is updated or deleted, the underlying operation is retained in the Lucene index for a period of time defined by the [`index.soft_deletes.retention_lease.period`](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#ccr-index-soft-deletes-retention-period) parameter. You configure this setting on the [leader index](../cross-cluster-replication.md#ccr-leader-requirements). + +When a follower index starts, it acquires a retention lease from the leader index. This lease informs the leader that it should not allow a soft delete to be pruned until either the follower indicates that it has received the operation, or until the lease expires. + +If a follower index falls sufficiently behind a leader and cannot replicate operations, {{es}} reports an `indices[].fatal_exception` error. To resolve the issue, recreate the follower index. When the new follow index starts, the [remote recovery](../cross-cluster-replication.md#ccr-remote-recovery) process recopies the Lucene segment files from the leader. + +::::{important} +Recreating the follower index is a destructive action. All existing Lucene segment files are deleted on the cluster containing the follower index. +:::: + + +To recreate a follower index, [access Cross-Cluster Replication](manage-cross-cluster-replication.md#ccr-access-ccr) and choose the **Follower indices** tab. + +Select the follower index and pause replication. When the follower index status changes to Paused, reselect the follower index and choose to unfollow the leader index. + +The follower index will be converted to a standard index and will no longer display on the Cross-Cluster Replication page. + +In the side navigation, choose **Index Management**. Select the follower index from the previous steps and close the follower index. + +You can then [recreate the follower index](ccr-getting-started-follower-index.md) to restart the replication process. + +::::{dropdown} Use the API +Use the [pause follow API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-pause-follow.html) to pause the replication process. Then, close the follower index and recreate it. For example: + +```console +POST /follower_index/_ccr/pause_follow + +POST /follower_index/_close + +PUT /follower_index/_ccr/follow?wait_for_active_shards=1 +{ + "remote_cluster" : "remote_cluster", + "leader_index" : "leader_index" +} +``` + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-terminate-replication.md b/deploy-manage/tools/cross-cluster-replication/ccr-terminate-replication.md new file mode 100644 index 000000000..9f653287d --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-terminate-replication.md @@ -0,0 +1,23 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-terminate-replication.html +--- + +# Terminate replication [ccr-terminate-replication] + +You can unfollow a leader index to terminate replication and convert the follower index to a standard index. + +[Access Cross-Cluster Replication](manage-cross-cluster-replication.md#ccr-access-ccr) and choose the **Follower indices** tab. + +Select the follower index and pause replication. When the follower index status changes to Paused, reselect the follower index and choose to unfollow the leader index. + +The follower index will be converted to a standard index and will no longer display on the Cross-Cluster Replication page. + +You can then choose **Index Management**, select the follower index from the previous steps, and close the follower index. + +::::{dropdown} Use the API +You can terminate replication with the [unfollow API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-unfollow.html). This API converts a follower index to a standard (non-follower) index. + +:::: + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-tutorial-initial-setup.md b/deploy-manage/tools/cross-cluster-replication/ccr-tutorial-initial-setup.md new file mode 100644 index 000000000..1bb5907c4 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-tutorial-initial-setup.md @@ -0,0 +1,152 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-tutorial-initial-setup.html +--- + +# Initial setup [ccr-tutorial-initial-setup] + +1. Set up a remote cluster on both clusters. + + ```console + ### On cluster A ### + PUT _cluster/settings + { + "persistent": { + "cluster": { + "remote": { + "clusterB": { + "mode": "proxy", + "skip_unavailable": true, + "server_name": "clusterb.es.region-b.gcp.elastic-cloud.com", + "proxy_socket_connections": 18, + "proxy_address": "clusterb.es.region-b.gcp.elastic-cloud.com:9400" + } + } + } + } + } + ### On cluster B ### + PUT _cluster/settings + { + "persistent": { + "cluster": { + "remote": { + "clusterA": { + "mode": "proxy", + "skip_unavailable": true, + "server_name": "clustera.es.region-a.gcp.elastic-cloud.com", + "proxy_socket_connections": 18, + "proxy_address": "clustera.es.region-a.gcp.elastic-cloud.com:9400" + } + } + } + } + } + ``` + +2. Set up bi-directional cross-cluster replication. + + ```console + ### On cluster A ### + PUT /_ccr/auto_follow/logs-generic-default + { + "remote_cluster": "clusterB", + "leader_index_patterns": [ + ".ds-logs-generic-default-20*" + ], + "leader_index_exclusion_patterns":"*-replicated_from_clustera", + "follow_index_pattern": "{{leader_index}}-replicated_from_clusterb" + } + + ### On cluster B ### + PUT /_ccr/auto_follow/logs-generic-default + { + "remote_cluster": "clusterA", + "leader_index_patterns": [ + ".ds-logs-generic-default-20*" + ], + "leader_index_exclusion_patterns":"*-replicated_from_clusterb", + "follow_index_pattern": "{{leader_index}}-replicated_from_clustera" + } + ``` + + ::::{important} + Existing data on the cluster will not be replicated by `_ccr/auto_follow` even though the patterns may match. This function will only replicate newly created backing indices (as part of the data stream). + :::: + + + ::::{important} + Use `leader_index_exclusion_patterns` to avoid recursion. + :::: + + + ::::{tip} + `follow_index_pattern` allows lowercase characters only. + :::: + + + ::::{tip} + This step cannot be executed via the {{kib}} UI due to the lack of an exclusion pattern in the UI. Use the API in this step. + :::: + +3. Set up the {{ls}} configuration file. + + This example uses the input generator to demonstrate the document count in the clusters. Reconfigure this section to suit your own use case. + + ```logstash + ### On Logstash server ### + ### This is a logstash config file ### + input { + generator{ + message => 'Hello World' + count => 100 + } + } + output { + elasticsearch { + hosts => ["https://clustera.es.region-a.gcp.elastic-cloud.com:9243","https://clusterb.es.region-b.gcp.elastic-cloud.com:9243"] + user => "logstash-user" + password => "same_password_for_both_clusters" + } + } + ``` + + ::::{important} + The key point is that when `cluster A` is down, all traffic will be automatically redirected to `cluster B`. Once `cluster A` comes back, traffic is automatically redirected back to `cluster A` again. This is achieved by the option `hosts` where multiple ES cluster endpoints are specified in the array `[clusterA, clusterB]`. + :::: + + + ::::{tip} + Set up the same password for the same user on both clusters to use this load-balancing feature. + :::: + +4. Start {{ls}} with the earlier configuration file. + + ```sh + ### On Logstash server ### + bin/logstash -f multiple_hosts.conf + ``` + +5. Observe document counts in data streams. + + The setup creates a data stream named `logs-generic-default` on each of the clusters. {{ls}} will write 50% of the documents to `cluster A` and 50% of the documents to `cluster B` when both clusters are up. + + Bi-directional {{ccr}} will create one more data stream on each of the clusters with the `-replication_from_cluster{a|b}` suffix. At the end of this step: + + * data streams on cluster A contain: + + * 50 documents in `logs-generic-default-replicated_from_clusterb` + * 50 documents in `logs-generic-default` + + * data streams on cluster B contain: + + * 50 documents in `logs-generic-default-replicated_from_clustera` + * 50 documents in `logs-generic-default` + +6. Queries should be set up to search across both data streams. A query on `logs*`, on either of the clusters, returns 100 hits in total. + + ```console + GET logs*/_search?size=0 + ``` + + diff --git a/deploy-manage/tools/cross-cluster-replication/ccr-uni-directional-upgrade.md b/deploy-manage/tools/cross-cluster-replication/ccr-uni-directional-upgrade.md new file mode 100644 index 000000000..6ab0ce2a2 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/ccr-uni-directional-upgrade.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-uni-directional-upgrade.html +--- + +# Uni-directional index following [ccr-uni-directional-upgrade] + +In a uni-directional configuration, one cluster contains only leader indices, and the other cluster contains only follower indices that replicate the leader indices. + +In this strategy, the cluster with follower indices should be upgraded first and the cluster with leader indices should be upgraded last. Upgrading the clusters in this order ensures that index following can continue during the upgrade without downtime. + +You can also use this strategy to upgrade a [replication chain](../cross-cluster-replication.md#ccr-chained-replication). Start by upgrading clusters at the end of the chain and working your way back to the cluster that contains the leader indices. + +For example, consider a configuration where Cluster A contains all leader indices. Cluster B follows indices in Cluster A, and Cluster C follows indices in Cluster B. + +``` +Cluster A + ^--Cluster B + ^--Cluster C +``` +In this configuration, upgrade the clusters in the following order: + +1. Cluster C +2. Cluster B +3. Cluster A + diff --git a/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns.md b/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns.md new file mode 100644 index 000000000..a13251440 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow.html +--- + +# Manage auto-follow patterns [ccr-auto-follow] + +To replicate time series indices, you configure an auto-follow pattern so that each new index in the series is replicated automatically. Whenever the name of a new index on the remote cluster matches the auto-follow pattern, a corresponding follower index is added to the local cluster. + +::::{note} +Auto-follow patterns only match open indices on the remote cluster that have all primary shards started. Auto-follow patterns do not match indices that can’t be used for {{ccr-init}} such as [closed indices](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-open-close.html#open-index-api-desc) or [{{search-snaps}}](../snapshot-and-restore/searchable-snapshots.md). Avoid using an auto-follow pattern that matches indices with a [read or write block](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-blocks.html#index-block-settings). These blocks prevent follower indices from replicating such indices. +:::: + + +You can also create auto-follow patterns for data streams. When a new backing index is generated on a remote cluster, that index and its data stream are automatically followed if the data stream name matches an auto-follow pattern. If you create a data stream after creating the auto-follow pattern, all backing indices are followed automatically. + +The data streams replicated from a remote cluster by CCR are protected from local rollovers. The [promote data stream API](https://www.elastic.co/guide/en/elasticsearch/reference/current/promote-data-stream-api.html) can be used to turn these data streams into regular data streams. + +Auto-follow patterns are especially useful with [{{ilm-cap}}](../../../manage-data/lifecycle/index-lifecycle-management.md), which might continually create new indices on the cluster containing the leader index. + +$$$ccr-access-ccr-auto-follow$$$ +To start using {{ccr}} auto-follow patterns from Stack Management in {{kib}}, select **Cross-Cluster Replication** from the side navigation and choose the **Auto-follow patterns** tab. + + + + + diff --git a/deploy-manage/tools/cross-cluster-replication/manage-cross-cluster-replication.md b/deploy-manage/tools/cross-cluster-replication/manage-cross-cluster-replication.md new file mode 100644 index 000000000..011ececb6 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/manage-cross-cluster-replication.md @@ -0,0 +1,16 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-managing.html +--- + +# Manage cross-cluster replication [ccr-managing] + +Use the following information to manage {{ccr}} tasks, such as inspecting replication progress, pausing and resuming replication, recreating a follower index, and terminating replication. + +$$$ccr-access-ccr$$$ +To start using {{ccr}}, access {{kib}} and go to **Management > Stack Management**. In the side navigation, select **Cross-Cluster Replication**. + + + + + diff --git a/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md b/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md new file mode 100644 index 000000000..56a271c44 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md @@ -0,0 +1,34 @@ +--- +navigation_title: "Set up {{ccr}}" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-getting-started-tutorial.html +--- + + + +# Set up cross-cluster replication [ccr-getting-started-tutorial] + + +Use this guide to set up {{ccr}} (CCR) between clusters in two datacenters. Replicating your data across datacenters provides several benefits: + +* Brings data closer to your users or application server to reduce latency and response time +* Provides your mission-critical applications with the tolerance to withstand datacenter or region outages + +In this guide, you’ll learn how to: + +* Configure a [remote cluster](../../remote-clusters.md) with a leader index +* Create a follower index on a local cluster +* Create an auto-follow pattern to automatically follow time series indices that are periodically created in a remote cluster + +You can manually create follower indices to replicate specific indices on a remote cluster, or configure auto-follow patterns to replicate rolling time series indices. + +::::{tip} +If you want to replicate data across clusters in the cloud, you can [configure remote clusters on {{ess}}](https://www.elastic.co/guide/en/cloud/current/ec-enable-ccs.html). Then, you can [search across clusters](../../../solutions/search/cross-cluster-search.md) and set up {{ccr}}. +:::: + + + + + + + diff --git a/deploy-manage/tools/cross-cluster-replication/uni-directional-disaster-recovery.md b/deploy-manage/tools/cross-cluster-replication/uni-directional-disaster-recovery.md new file mode 100644 index 000000000..82f75dbb3 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/uni-directional-disaster-recovery.md @@ -0,0 +1,29 @@ +--- +navigation_title: "Uni-directional disaster recovery" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-disaster-recovery-uni-directional-tutorial.html +--- + + + +# Uni-directional disaster recovery [ccr-disaster-recovery-uni-directional-tutorial] + + +Learn how to failover and failback between two clusters based on uni-directional {{ccr}}. You can also visit [Bi-directional disaster recovery](bi-directional-disaster-recovery.md) to set up replicating data streams that automatically failover and failback without human intervention. + +* Setting up uni-directional {{ccr}} replicated from `clusterA` to `clusterB`. +* Failover - If `clusterA` goes offline, `clusterB` needs to "promote" follower indices to regular indices to allow write operations. All ingestion will need to be redirected to `clusterB`, this is controlled by the clients ({{ls}}, {{beats}}, {{agents}}, etc). +* Failback - When `clusterA` is back online, it assumes the role of a follower and replicates the leader indices from `clusterB`. + +:::{image} ../../../images/elasticsearch-reference-ccr-uni-directional-disaster-recovery.png +:alt: Uni-directional cross cluster replication failover and failback +::: + +::::{note} +{{ccr-cap}} provides functionality to replicate user-generated indices only. {{ccr-cap}} isn’t designed for replicating system-generated indices or snapshot settings, and can’t replicate {{ilm-init}} or {{slm-init}} policies across clusters. Learn more in {{ccr}} [limitations](../cross-cluster-replication.md#ccr-limitations). +:::: + + + + + diff --git a/deploy-manage/tools/cross-cluster-replication/upgrading-clusters.md b/deploy-manage/tools/cross-cluster-replication/upgrading-clusters.md new file mode 100644 index 000000000..00c221492 --- /dev/null +++ b/deploy-manage/tools/cross-cluster-replication/upgrading-clusters.md @@ -0,0 +1,20 @@ +--- +navigation_title: "Upgrading clusters" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-upgrading.html +--- + + + +# Upgrading clusters [ccr-upgrading] + + +Clusters that are actively using {{ccr}} require a careful approach to upgrades. The following conditions could cause index following to fail during rolling upgrades: + +* Clusters that have not yet been upgraded will reject new index settings or mapping types that are replicated from an upgraded cluster. +* Nodes in a cluster that has not been upgraded will reject index files from a node in an upgraded cluster when index following tries to fall back to file-based recovery. This limitation is due to Lucene not being forward compatible. + +The approach to running a rolling upgrade on clusters where {{ccr}} is enabled differs based on uni-directional and bi-directional index following. + + + diff --git a/deploy-manage/tools/snapshot-and-restore.md b/deploy-manage/tools/snapshot-and-restore.md new file mode 100644 index 000000000..05dad92d1 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore.md @@ -0,0 +1,39 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html + - https://www.elastic.co/guide/en/cloud/current/ec-snapshot-restore.html + - https://www.elastic.co/guide/en/cloud/current/ec-restoring-snapshots.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-snapshot-restore.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-restoring-snapshots.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-snapshots.html +--- + +# Snapshot and restore + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/343 + +% Scope notes: Merge all articles to be relevant for all deployment types. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/snapshot-restore.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-snapshot-restore.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-restoring-snapshots.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-snapshot-restore.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-restoring-snapshots.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-snapshots.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$snapshot-repository-contents$$$ + +$$$feature-state$$$ + +$$$snapshot-restore-version-compatibility$$$ + +$$$snapshots-shard-allocation$$$ + +$$$fn-archive$$$ \ No newline at end of file diff --git a/deploy-manage/tools/snapshot-and-restore/access-isolation-for-found-snapshots-repository.md b/deploy-manage/tools/snapshot-and-restore/access-isolation-for-found-snapshots-repository.md new file mode 100644 index 000000000..1e289e7cc --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/access-isolation-for-found-snapshots-repository.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-snapshot-repository-migration.html +--- + +# Access isolation for the found-snapshots repository [ec-snapshot-repository-migration] + +::::{note} +The guides in this section are only relevant for some deployments. Any newly created deployment will have access isolation set up by default. If a deployment’s repository can be updated, a notification will show up in the deployments menu under **Elasticsearch** > **Snapshots**. +:::: + + + + diff --git a/deploy-manage/tools/snapshot-and-restore/azure-repository.md b/deploy-manage/tools/snapshot-and-restore/azure-repository.md new file mode 100644 index 000000000..7b78c514b --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/azure-repository.md @@ -0,0 +1,220 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-azure.html +--- + +# Azure repository [repository-azure] + +You can use [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) as a repository for [Snapshot and restore](../snapshot-and-restore.md). + +## Setup [repository-azure-usage] + +To enable Azure repositories, first configure an Azure repository client by specifying one or more settings of the form `azure.client.CLIENT_NAME.SETTING_NAME`. By default, `azure` repositories use a client named `default`, but you may specify a different client name when registering each repository. + +The only mandatory Azure repository client setting is `account`, which is a [secure setting](../../security/secure-settings.md) defined in the [{{es}} keystore](../../security/secure-settings.md). To provide this setting, use the `elasticsearch-keystore` tool on each node: + +```sh +bin/elasticsearch-keystore add azure.client.default.account +``` + +If you adjust this setting after a node has started, call the [Nodes reload secure settings API](../../security/secure-settings.md) to reload the new value. + +You may define more than one client by setting their `account` values. For instance, to set the `default` client and another client called `secondary`, run the following commands on each node: + +```sh +bin/elasticsearch-keystore add azure.client.default.account +bin/elasticsearch-keystore add azure.client.secondary.account +``` + +The `key` and `sas_token` settings are also secure settings and can be set using commands like the following: + +```sh +bin/elasticsearch-keystore add azure.client.default.key +bin/elasticsearch-keystore add azure.client.secondary.sas_token +``` + +Other Azure repository client settings must be set in `elasticsearch.yml` before the node starts. For example: + +```yaml +azure.client.default.timeout: 10s +azure.client.default.max_retries: 7 +azure.client.default.endpoint_suffix: core.chinacloudapi.cn +azure.client.secondary.timeout: 30s +``` + +In this example, the client side timeout is `10s` per try for repositories which use the `default` client, with `7` retries before failing and an endpoint suffix of `core.chinacloudapi.cn`. Repositories which use the `secondary` client will have a timeout of `30s` per try, but will use the default endpoint and will fail after the default number of retries. + +Once an Azure repository client is configured correctly, register an Azure repository as follows, providing the client name using the `client` [repository setting](#repository-azure-repository-settings): + +```console +PUT _snapshot/my_backup +{ + "type": "azure", + "settings": { + "client": "secondary" + } +} +``` + +If you are using the `default` client, you may omit the `client` repository setting: + +```console +PUT _snapshot/my_backup +{ + "type": "azure" +} +``` + +::::{note} +In progress snapshot or restore jobs will not be preempted by a **reload** of the storage secure settings. They will complete using the client as it was built when the operation started. +:::: + + + +## Client settings [repository-azure-client-settings] + +The following list describes the available client settings. Those that must be stored in the keystore are marked as ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)); the other settings must be stored in the `elasticsearch.yml` file. The default `CLIENT_NAME` is `default` but you may configure a client with a different name and specify that client by name when registering a repository. + +`azure.client.CLIENT_NAME.account` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: The Azure account name, which is used by the repository’s internal Azure client. This setting is required for all clients. + +`azure.client.CLIENT_NAME.endpoint_suffix` +: The Azure endpoint suffix to connect to. The default value is `core.windows.net`. + +`azure.client.CLIENT_NAME.key` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: The Azure secret key, which is used by the repository’s internal Azure client. Alternatively, use `sas_token`. + +`azure.client.CLIENT_NAME.max_retries` +: The number of retries to use when an Azure request fails. This setting helps control the exponential backoff policy. It specifies the number of retries that must occur before the snapshot fails. The default value is `3`. The initial backoff period is defined by Azure SDK as `30s`. Thus there is `30s` of wait time before retrying after a first timeout or failure. The maximum backoff period is defined by Azure SDK as `90s`. + +`azure.client.CLIENT_NAME.proxy.host` +: The host name of a proxy to connect to Azure through. By default, no proxy is used. + +`azure.client.CLIENT_NAME.proxy.port` +: The port of a proxy to connect to Azure through. By default, no proxy is used. + +`azure.client.CLIENT_NAME.proxy.type` +: Register a proxy type for the client. Supported values are `direct`, `http`, and `socks`. For example: `azure.client.default.proxy.type: http`. When `proxy.type` is set to `http` or `socks`, `proxy.host` and `proxy.port` must also be provided. The default value is `direct`. + +`azure.client.CLIENT_NAME.sas_token` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: A shared access signatures (SAS) token, which the repository’s internal Azure client uses for authentication. The SAS token must have read (r), write (w), list (l), and delete (d) permissions for the repository base path and all its contents. These permissions must be granted for the blob service (b) and apply to resource types service (s), container (c), and object (o). Alternatively, use `key`. + +`azure.client.CLIENT_NAME.timeout` +: The client side timeout for any single request to Azure, as a [time unit](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units). For example, a value of `5s` specifies a 5 second timeout. There is no default value, which means that {{es}} uses the [default value](https://azure.github.io/azure-storage-java/com/microsoft/azure/storage/RequestOptions.md#setTimeoutIntervalInMs(java.lang.Integer)) set by the Azure client. + +`azure.client.CLIENT_NAME.endpoint` +: The Azure endpoint to connect to. It must include the protocol used to connect to Azure. + +`azure.client.CLIENT_NAME.secondary_endpoint` +: The Azure secondary endpoint to connect to. It must include the protocol used to connect to Azure. + +::::{admonition} Obtaining credentials from the environment +:class: note + +:name: repository-azure-default-credentials + +If you specify neither the `key` nor the `sas_token` settings for a client then {{es}} will attempt to automatically obtain credentials from the environment in which it is running using mechanisms built into the Azure SDK. This is ideal for when running {{es}} on the Azure platform. + +When running {{es}} on an [Azure Virtual Machine](https://azure.microsoft.com/en-gb/products/virtual-machines), you should use [Azure Managed Identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) to provide credentials to {{es}}. To use Azure Managed Identity, assign a suitably authorized identity to the Azure Virtual Machine on which {{es}} is running. + +When running {{es}} in [Azure Kubernetes Service](https://azure.microsoft.com/en-gb/products/kubernetes-service), for instance using [{{eck}}](cloud-on-k8s.md#k8s-azure-workload-identity), you should use [Azure Workload Identity](https://azure.github.io/azure-workload-identity/docs/introduction.md) to provide credentials to {{es}}. To use Azure Workload Identity, mount the `azure-identity-token` volume as a subdirectory of the [{{es}} config directory](../../deploy/self-managed/configure-elasticsearch.md#config-files-location) and set the `AZURE_FEDERATED_TOKEN_FILE` environment variable to point to a file called `azure-identity-token` within the mounted volume. + +The Azure SDK has several other mechanisms to automatically obtain credentials from its environment, but the two methods described above are the only ones that are tested and supported for use in {{es}}. + +:::: + + + +## Repository settings [repository-azure-repository-settings] + +The Azure repository supports the following settings, which may be specified when registering an Azure repository as follows: + +```console +PUT _snapshot/my_backup +{ + "type": "azure", + "settings": { + "client": "secondary", + "container": "my_container", + "base_path": "snapshots_prefix" + } +} +``` + +`client` +: The name of the Azure repository client to use. Defaults to `default`. + +`container` +: Container name. You must create the azure container before creating the repository. Defaults to `elasticsearch-snapshots`. + +`base_path` +: Specifies the path within container to repository data. Defaults to empty (root directory). + + ::::{note} + Don’t set `base_path` when configuring a snapshot repository for {{ECE}}. {{ECE}} automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket. + :::: + + +`chunk_size` +: Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the Azure blob store during snapshot create as well as restore operations compared to using the default value and thus make both operations slower as well as more costly. Specify the chunk size as a [byte unit](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units), for example: `10MB`, `5KB`, `500B`. Defaults to the maximum size of a blob in the Azure blob store which is `5TB`. + +`compress` +: When set to `true` metadata files are stored in compressed format. This setting doesn’t affect index files that are already compressed by default. Defaults to `true`. + +`max_restore_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`max_snapshot_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot creation rate per node. Defaults to `40mb` per second. Note that if the [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services) are set, then it defaults to unlimited, and the rate is additionally throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`readonly` +: (Optional, Boolean) If `true`, the repository is read-only. The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + + Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the `readonly` parameter set to `true`. + + If `false`, the cluster can write to the repository and create snapshots in it. Defaults to `false`. + + ::::{important} + If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + + :::: + + +`location_mode` +: `primary_only` or `secondary_only`. Defaults to `primary_only`. Note that if you set it to `secondary_only`, it will force `readonly` to true. + +`delete_objects_max_size` +: (integer) Sets the maxmimum batch size, betewen 1 and 256, used for `BlobBatch` requests. Defaults to 256 which is the maximum number supported by the [Azure blob batch API](https://learn.microsoft.com/en-us/rest/api/storageservices/blob-batch#remarks). + +`max_concurrent_batch_deletes` +: (integer) Sets the maximum number of concurrent batch delete requests that will be submitted for any individual bulk delete with `BlobBatch`. Note that the effective number of concurrent deletes is further limited by the Azure client connection and event loop thread limits. Defaults to 10, minimum is 1, maximum is 100. + + +## Repository validation rules [repository-azure-validation] + +According to the [containers naming guide](https://docs.microsoft.com/en-us/rest/api/storageservices/Naming-and-Referencing-Containers—​Blobs—​and-Metadata), a container name must be a valid DNS name, conforming to the following naming rules: + +* Container names must start with a letter or number, and can contain only letters, numbers, and the dash (-) character. +* Every dash (-) character must be immediately preceded and followed by a letter or number; consecutive dashes are not permitted in container names. +* All letters in a container name must be lowercase. +* Container names must be from 3 through 63 characters long. + +::::{admonition} Supported Azure Storage Account types +:class: important + +The Azure repository type works with all Standard storage accounts + +* Standard Locally Redundant Storage - `Standard_LRS` +* Standard Zone-Redundant Storage - `Standard_ZRS` +* Standard Geo-Redundant Storage - `Standard_GRS` +* Standard Read Access Geo-Redundant Storage - `Standard_RAGRS` + +[Premium Locally Redundant Storage](https://azure.microsoft.com/en-gb/documentation/articles/storage-premium-storage) (`Premium_LRS`) is **not supported** as it is only usable as VM disk storage, not as general storage. + +:::: + + + +## Linearizable register implementation [repository-azure-linearizable-registers] + +The linearizable register implementation for Azure repositories is based on Azure’s support for strongly consistent leases. Each lease may only be held by a single node at any time. The node presents its lease when performing a read or write operation on a protected blob. Lease-protected operations fail if the lease is invalid or expired. To perform a compare-and-exchange operation on a register, {{es}} first obtains a lease on the blob, then reads the blob contents under the lease, and finally uploads the updated blob under the same lease. This process ensures that the read and write operations happen atomically. diff --git a/deploy-manage/tools/snapshot-and-restore/azure-storage-repository.md b/deploy-manage/tools/snapshot-and-restore/azure-storage-repository.md new file mode 100644 index 000000000..8154f2566 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/azure-storage-repository.md @@ -0,0 +1,42 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-azure-snapshotting.html +--- + +# Azure Storage repository [ece-configure-azure-snapshotting] + +With Elastic Cloud Enterprise, you can enable your Elasticsearch clusters to regularly snapshot data to Microsoft Azure Storage. + + +## Add the Azure repository [ece_add_the_azure_repository] + +Add your Azure Storage Container as a repository to the platform: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Platform > Repositories** and add the following snapshot repository configuration under the advanced mode: + + If needed, set additional options for configuring chunk_size, compressions, and retries. Check the [supported settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-azure.html#repository-azure-repository-settings). + + ```json + { + "type": "azure", + "settings": { + "account": "AZURE STORAGE ACCOUNT NAME", + "sas_token": "AZURE SAS_TOKEN", + "container": "BACKUP-CONTAINER" + } + } + ``` + + +Snapshots are stored in the container you provide. Use the repository name you define here to configure your Elasticsearch clusters for snapshotting to this repository. + + +## Configure your deployment for Azure snapshots [ece_configure_your_deployment_for_azure_snapshots] + +To save deployment snapshots to the Azure repository: + +1. Configure your deployment to [snapshot to the Azure repository](cloud-enterprise.md). + +The cluster should then have snapshots enabled and and begins snapshotting immediately. You can configure the how frequently snapshotting occurs on the **Snapshots** in the **Elasticsearch** menu. + diff --git a/deploy-manage/tools/snapshot-and-restore/cloud-enterprise.md b/deploy-manage/tools/snapshot-and-restore/cloud-enterprise.md new file mode 100644 index 000000000..cc300cee0 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/cloud-enterprise.md @@ -0,0 +1,151 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-repositories.html +--- + +# Elastic Cloud Enterprise [ece-manage-repositories] + +Snapshot repositories are managed for your entire Elastic Cloud Enterprise installation and can be specified for an Elasticsearch cluster when you create or manage it. + +When a repository is specified, a snapshot is taken every 30 minutes by default. The interval can be adjusted on per deployment basis. + +Snapshots are configured and restored using the [snapshot and restore feature](../snapshot-and-restore.md). + +Elastic Cloud Enterprise installations support the following {{es}} [snapshot repository types](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html#ess-repo-types): + +* [Azure](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-azure.html) +* [Google Cloud Storage](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html) +* [AWS S3](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-s3.html) + +::::{note} +No repository types other than those listed are supported in the Elastic Cloud Enterprise platform, even if they are supported by {{es}}. +:::: + + +To configure Google Cloud Storage (GCS) as a snapshot repository, you must use [Google Default Authentication](https://developers.google.com/identity/protocols/application-default-credentials). To learn more, check [Snapshotting to Google Cloud Storage](google-cloud-storage-gcs-repository.md). + +To configure Microsoft Azure Storage as a snapshot repository, refer to [Snapshotting to Azure Storage](azure-storage-repository.md). + +For more details about how snapshots are used with Elasticsearch, check [Snapshot and Restore](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html). You can also review the official documentation for these storage repository options: + +* [Amazon S3 documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.md) +* [Microsoft Azure storage documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account) +* [Google Cloud Storage documentation](https://cloud.google.com/storage/docs/) + +::::{tip} +If you are installing ECE without internet access (commonly called an offline or air-gapped installation), you will need to use an on-premise storage service. We suggest that you use [Minio](https://www.minio.io/). For our installation notes, check [Snapshotting to Minio On-Premise Storage](minio-on-premise-repository.md). +:::: + + + +## Add snapshot repository configurations [ece-manage-repositories-add] + +Before any snapshot or restore operation can be performed for Elasticsearch clusters, at least one snapshot repository configuration needs to be added to your Elastic Cloud Enterprise installation. + +To add a snapshot repository: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Repositories**. +3. Select **Add Repository** to add an existing repository. +4. Provide a name for the repository configuration. + + ECE Snapshot Repository names are now required to meet the same standards as S3 buckets. Refer to the official AWS documentation on [Bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.md). + +5. Select one of the supported repository types and specify the necessary settings: + + * Amazon S3 configuration: + + All repository options must be specified, as there are no default values. + + Region + : The region where the bucket is located. + + Bucket + : The name of the bucket to be used for snapshots. + + Access key + : The access key to use for authentication. + + Secret key + : The secret key to use for authentication. + + * Advanced configuration: + + Used for Microsoft Azure, Google Cloud Platform, or for some Amazon S3 repositories where you need to provide additional configuration parameters not supported by the S3 repository option. Configurations must be specified in a valid JSON format. For example: + + Amazon S3 (check [supported settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-s3.html#repository-s3-repository)): + + ```json + { + "type": "s3", + "settings": { + "bucket": "my_bucket_name", + "region": "us-west" + } + } + ``` + + ::::{note} + Don’t set `base_path` when configuring a snapshot repository for {{ECE}}. {{ECE}} automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket. + :::: + +6. Select **Save**. + + +## Edit snapshot repository configurations [ece_edit_snapshot_repository_configurations] + +To edit a snapshot repository configuration from your Elastic Cloud Enterprise installation: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Repositories**. +3. Select **Edit** to modify a snapshot repository configuration. + + For available options that you can change, check [Add Snapshot Repository Configurations](). + +4. Select **Save**. + + +## Delete snapshot repository configurations [ece_delete_snapshot_repository_configurations] + +Deleting a snapshot repository configuration does not remove the snapshot repository itself from S3. Only the configuration that enables Elastic Cloud Enterprise to access the repository is removed. Existing snapshots are also retained and need to be deleted separately if you no longer need them. + +To delete a snapshot repository configuration from your Elastic Cloud Enterprise installation: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Repositories**. +3. Find the repository name that you want to remove. +4. Run the following command against the repository name: + + ```sh + curl -s -XDELETE -u USER:PASSWORD https://COORDINATOR_HOST:12443/api/v1/platform/configuration/snapshots/repositories/REPOSITORY_NAME + ``` + + ::::{note} + The user must have sufficient privileges, such as the `admin` user. + :::: + + + +## Manage Elasticsearch cluster repositories [ece-manage-repositories-clusters] + +You might need to update existing Elasticsearch clusters to use a different snapshot repository for one of the following reasons: + +* If you do not want all snapshots for a specific Elasticsearch cluster to go into the same bucket as your other clusters, you can add a new snapshot repository configuration with separate permissions and then change your Elasticsearch cluster to use the new repository. +* If you created an Elasticsearch cluster with no snapshot repository configured, you can add a repository later on. Elastic Cloud Enterprise will start taking snapshots of the cluster automatically. + +To change the snapshot repository for an existing Elasticsearch cluster: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Optional: If you need to use a repository that is not yet listed, [add a snapshot repository configuration]() first. +3. From the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + +4. From the **Elasticsearch** menu, select **Snapshots**. +5. Under **Snapshot repository**, choose a different repository and select **Save repository**. + +Future snapshots will be sent to the new repository. + + + + diff --git a/deploy-manage/tools/snapshot-and-restore/cloud-on-k8s.md b/deploy-manage/tools/snapshot-and-restore/cloud-on-k8s.md new file mode 100644 index 000000000..d31812bcc --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/cloud-on-k8s.md @@ -0,0 +1,544 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-snapshots.html +--- + +# Elastic Cloud on Kubernetes [k8s-snapshots] + +::::{note} +Snapshots are essential for recovering Elasticsearch indices in case of accidental deletion or for migrating data between clusters. +:::: + + +To set up automated snapshots for Elasticsearch on Kubernetes you have to: + +1. Register the snapshot repository with the Elasticsearch API. +2. Set up a Snapshot Lifecycle Management Policy through [API](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management-api.html) or the [Kibana UI](https://www.elastic.co/guide/en/kibana/current/snapshot-repositories.html) + +::::{note} +Support for S3, GCS and Azure repositories is bundled in Elasticsearch by default from version 8.0. On older versions of Elasticsearch, or if another snapshot repository plugin should be used, you have to [Install a snapshot repository plugin](#k8s-install-plugin). +:::: + + +For more information on Elasticsearch snapshots, check [Snapshot and Restore](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html) in the Elasticsearch documentation. + +## Configuration examples [k8s_configuration_examples] + +What follows is a non-exhaustive list of configuration examples. The first example might be worth reading even if you are targeting a Cloud provider other than GCP as it covers adding snapshot repository credentials to the Elasticsearch keystore and illustrates the basic workflow of setting up a snapshot repository: + +* [Basic snapshot repository setup using GCS as an example](#k8s-basic-snapshot-gcs) + +The following examples cover approaches that use Cloud-provider specific means to leverage Kubernetes service accounts to avoid having to configure snapshot repository credentials in Elasticsearch: + +* [Use GKE Workload Identity](#k8s-gke-workload-identiy) +* [Use AWS IAM roles for service accounts (IRSA)](#k8s-iam-service-accounts) +* [Use Azure Workload Identity](#k8s-azure-workload-identity) + +The final example illustrates how to configure secure and trusted communication when you + +* [Use S3-compatible services](#k8s-s3-compatible) + +### Basic snapshot repository setup using GCS as an example [k8s-basic-snapshot-gcs] + +#### Configure GCS credentials through the Elasticsearch keystore [k8s-secure-settings] + +The Elasticsearch GCS repository plugin requires a JSON file that contains service account credentials. These need to be added as secure settings to the Elasticsearch keystore. For more details, check [Google Cloud Storage Repository](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html). + +Using ECK, you can automatically inject secure settings into a cluster node by providing them through a secret in the Elasticsearch Spec. + +1. Create a file containing the GCS credentials. For this example, name it `gcs.client.default.credentials_file`. The file name is important as it is reflected in the secure setting. + + ```json + { + "type": "service_account", + "project_id": "your-project-id", + "private_key_id": "...", + "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", + "client_email": "service-account-for-your-repository@your-project-id.iam.gserviceaccount.com", + "client_id": "...", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://accounts.google.com/o/oauth2/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-bucket@your-project-id.iam.gserviceaccount.com" + } + ``` + +2. Create a Kubernetes secret from that file: + + ```sh + kubectl create secret generic gcs-credentials --from-file=gcs.client.default.credentials_file + ``` + +3. Edit the `secureSettings` section of the Elasticsearch resource: + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: elasticsearch-sample + spec: + version: 8.16.1 + # Inject secure settings into Elasticsearch nodes from a k8s secret reference + secureSettings: + - secretName: gcs-credentials + ``` + + If you haven’t followed these instructions and named your GCS credentials file differently, you can still map it to the expected name now. Check [Secure Settings](../../security/secure-settings.md) for details. + +4. Apply the modifications: + + ```bash + kubectl apply -f elasticsearch.yml + ``` + + +GCS credentials are automatically propagated into each Elasticsearch node’s keystore. It can take up to a few minutes, depending on the number of secrets in the keystore. You don’t have to restart the nodes. + + +#### Register the repository in Elasticsearch [k8s-create-repository] + +1. Create the GCS snapshot repository in Elasticsearch. You can either use the [Snapshot and Restore UI](https://www.elastic.co/guide/en/kibana/current/snapshot-repositories.html) in Kibana version 7.4.0 or higher, or follow the procedure described in [Snapshot and Restore](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html): + + ```sh + PUT /_snapshot/my_gcs_repository + { + "type": "gcs", + "settings": { + "bucket": "my_bucket", + "client": "default" + } + } + ``` + +2. Take a snapshot with the following HTTP request: + + ```sh + PUT /_snapshot/my_gcs_repository/test-snapshot + ``` + + + + +### Use GKE Workload Identity [k8s-gke-workload-identiy] + +GKE Workload Identity allows a Kubernetes service account to impersonate a Google Cloud IAM service account and therefore to configure a snapshot repository in Elasticsearch without storing Google Cloud credentials in Elasticsearch itself. This feature requires your Kubernetes cluster to run on GKE and your Elasticsearch cluster to run at least [version 7.13](https://github.com/elastic/elasticsearch/pull/71239) and [version 8.1](https://github.com/elastic/elasticsearch/pull/82974) when using searchable snapshots. + +Follow the instructions in the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) to configure workload identity, specifically: + +1. Create or update your Kubernetes cluster with `--workload-pool=PROJECT_ID.svc.id.goog` enabled, where `PROJECT_ID` is your Google project ID +2. Create a namespace and a Kubernetes service account (`test-gcs` and `gcs-sa` in this example) +3. Create the bucket, the Google service account (`gcp-sa` in this example. Note that both Google and Kubernetes have the concept of a service account and this example is referring to the former) and set the relevant permissions through Google Cloud console or gcloud CLI +4. Allow the Kubernetes service account to impersonate the Google service account: + + ```sh + gcloud iam service-accounts add-iam-policy-binding gcp-sa@PROJECT_ID.iam.gserviceaccount.com \ + --role roles/iam.workloadIdentityUser \ + --member "serviceAccount:PROJECT_ID.svc.id.goog[test-gcs/gcs-sa]" + ``` + +5. Add the `iam.gke.io/gcp-service-account` annotation on the Kubernetes service account + + ```sh + kubectl annotate serviceaccount gcs-sa \ + --namespace test-gcs \ + iam.gke.io/gcp-service-account=gcp-sa@PROJECT_ID.iam.gserviceaccount.com + ``` + +6. Create an Elasticsearch cluster, referencing the Kubernetes service account + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: elasticsearch-gcs-sample + namespace: test-gcs + spec: + version: 8.16.1 + nodeSets: + - name: default + podTemplate: + spec: + automountServiceAccountToken: true + serviceAccountName: gcs-sa + count: 3 + ``` + +7. Create the snapshot repository as described in [Register the repository in Elasticsearch](#k8s-create-repository) + + +### Use AWS IAM roles for service accounts (IRSA) [k8s-iam-service-accounts] + +The AWS IAM roles for service accounts feature allows you to give Elasticsearch restricted access to a S3 bucket without having to expose and store AWS credentials directly in Elasticsearch. This requires you to run the ECK operator on Amazon’s EKS offering and an [Elasticsearch cluster running at least version 8.1](https://www.elastic.co/guide/en/elasticsearch/reference/8.1/repository-s3.html#iam-kubernetes-service-accounts). + +Follow [the AWS documentation](https://aws.amazon.com/premiumsupport/knowledge-center/eks-restrict-s3-bucket/) to set this feature up. Specifically you need to: + +1. Define an IAM policy file, called `iam-policy.json` in this example, giving access to an S3 bucket called `my_bucket` + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "s3:ListBucketMultipartUploads", + "s3:ListBucketVersions", + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": "arn:aws:s3:::my_bucket" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:AbortMultipartUpload", + "s3:DeleteObject", + "s3:ListMultipartUploadParts" + ], + "Resource": "arn:aws:s3:::my_bucket/*" + } + ] + } + ``` + +2. Create the policy using AWS CLI tooling, using the name `eck-snapshots` in this example + + ```sh + aws iam create-policy \ + --policy-name eck-snapshots \ + --policy-document file://iam-policy.json + ``` + +3. Use `eksctl` to create an IAM role and create and annotate a Kubernetes service account with it. The service account is called `aws-sa` in the `default` namespace in this example. + + ```sh + eksctl create iamserviceaccount \ + --name aws-sa \ + --namespace default \ + --cluster YOUR_CLUSTER \ <1> + --attach-policy-arn arn:aws:iam::YOUR_IAM_ARN:policy/eck-snapshots \ <2> + --approve + ``` + + 1. Replace `YOUR_CLUSTER` with your actual EKS cluster name + 2. Replace with the actual AWS IAM ARN for the policy you just created + +4. Create an Elasticsearch cluster referencing the service account + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: es + spec: + version: 8.16.1 + nodeSets: + - name: default + count: 3 + podTemplate: + spec: + serviceAccountName: aws-sa + containers: + - name: elasticsearch + env: + - name: AWS_WEB_IDENTITY_TOKEN_FILE + value: "/usr/share/elasticsearch/config/repository-s3/aws-web-identity-token-file" <1> + - name: AWS_ROLE_ARN + value: "arn:aws:iam::YOUR_ROLE_ARN_HERE" <2> + volumeMounts: + - name: aws-iam-token + mountPath: /usr/share/elasticsearch/config/repository-s3 + volumes: + - name: aws-iam-token + projected: + sources: + - serviceAccountToken: + audience: sts.amazonaws.com + expirationSeconds: 86400 + path: aws-web-identity-token-file + ``` + + 1. Elasticsearch expects the service account token to be projected to exactly this path + 2. Replace with the actual `AWS_ROLE_ARN` for the IAM role you created in step 3 + +5. Create the snapshot repository as described in [Register the repository in Elasticsearch](#k8s-create-repository) but of type `s3` + + ```sh + PUT /_snapshot/my_s3_repository + { + "type": "s3", + "settings": { + "bucket": "my_bucket" + } + } + ``` + + + +### Use Azure Workload Identity [k8s-azure-workload-identity] + +Starting with version 8.16 Elasticsearch supports Azure Workload identity which allows the use of Azure blob storage for Elasticsearch snapshots without exposing Azure credentials directly to Elasticsearch. + +Follow the [Azure documentation](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster) for setting up workload identity for the first five steps: + +1. [Create a resource group](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#create-a-resource-group), if it does not exist yet. +2. [Create](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#create-an-aks-cluster) or [update](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#update-an-existing-aks-cluster) your AKS cluster to enable workload identity. +3. [Retrieve the OIDC issuer URL](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#retrieve-the-oidc-issuer-url). +4. [Create a managed identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#create-a-managed-identity) and [link it to a Kubernetes service account](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#create-a-kubernetes-service-account). +5. [Create the federated identity credential](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#create-the-federated-identity-credential). + + ::::{note} + The following steps diverge from the tutorial in the Azure documentation. However, variables initialised as part of the Azure tutorial are still assumed to be present. + :::: + +6. Create an Azure storage account, if it does not exist yet. + + ```sh + az storage account create \ + --name esstorage \ + --resource-group "${RESOURCE_GROUP}" \ + --location "${LOCATION}" \ + --encryption-services blob \ + --sku Standard_ZRS <1> + ``` + + 1. This can be any of the supported storage account types `Standard_LRS`, `Standard_ZRS`, `Standard_GRS`, `Standard_RAGRS` but not `Premium_LRS` see [the Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-azure.html) for details. + +7. Create a container in the storage account, for this example `es-snapshots`. + + ```sh + az storage container create \ + --account-name "${STORAGE_ACCOUNT_NAME}" \ + --name es-snapshots --auth-mode login + ``` + +8. Create a role assignment between the managed identity and the storage account. + + ```sh + IDENTITY_PRINCIPAL_ID=$(az identity show \ + --name "${USER_ASSIGNED_IDENTITY_NAME}" \ + --resource-group "${RESOURCE_GROUP}" \ + --query principalId --o tsv) + + STORAGE_SCOPE=$(az storage account show \ + --resource-group "${RESOURCE_GROUP}" \ + --name "${STORAGE_ACCOUNT_NAME}" --query id -o tsv | sed 's#/##') <1> + + az role assignment create \ + --assignee-object-id "${IDENTITY_PRINCIPAL_ID}" \ + --role "Storage Blob Data Contributor" \ + --scope "${STORAGE_SCOPE}" + ``` + + 1. The storage account ID needs to be specified as the scope for the role assignment without the leading slash returned by the `az storage account show` command. + +9. Create a Kubernetes secret, called `keystore` in this example, with the storage account name. This is necessary to be able to specify the account name as a secure setting in Elasticsearch in the next step. + + ```sh + kubectl create secret generic keystore \ + --from-literal=azure.client.default.account=${STORAGE_ACCOUNT_NAME} + ``` + +10. Create an Elasticsearch cluster that uses the Kubernetes service account created earlier. + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: az-workload-identity-sample + spec: + version: 8.16.0 + secureSettings: + - secretName: keystore <1> + nodeSets: + - name: default + count: 1 + podTemplate: + metadata: + labels: + azure.workload.identity/use: "true" + spec: + serviceAccountName: workload-identity-sa <2> + containers: + - name: elasticsearch + env: + - name: AZURE_FEDERATED_TOKEN_FILE <3> + value: /usr/share/elasticsearch/config/azure/tokens/azure-identity-token + volumeMounts: + - name: azure-identity-token + mountPath: /usr/share/elasticsearch/config/azure/tokens <3> + ``` + + 1. Specify the Kubernetes secret created in the previous step to configure the Azure storage account name as a secure setting. + 2. This is the service account created earlier in the steps from the [Azure Workload Identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#create-a-kubernetes-service-account) tutorial. + 3. The corresponding volume is injected by the [Azure Workload Identity Mutating Admission Webhook](https://azure.github.io/azure-workload-identity/docs/installation/mutating-admission-webhook.md). For Elasticsearch to be able to access the token, the mount needs to be in a sub-directory of the Elasticsearch config directory. The corresponding environment variable needs to be adjusted as well. + +11. Create a snapshot repository of type `azure` through the Elasticsearch API, or through [*Elastic Stack configuration policies*](../../deploy/cloud-on-k8s/elastic-stack-configuration-policies.md). + + ```sh + POST _snapshot/my_azure_repository + { + "type": "azure", + "settings": { + "container": "es-snapshots" + } + } + ``` + + + +### Use S3-compatible services [k8s-s3-compatible] + +The following example assumes that you have deployed and configured a S3 compatible object store like [MinIO](https://min.io) that can be reached from the Kubernetes cluster, and also that you have created a bucket in said service, called `es-repo` in this example. The example also assumes an Elasticsearch cluster named `es` is deployed within the cluster. Most importantly the steps describing how to customize the JVM trust store are only necessary if your S3-compatible service is using TLS certificates that are not issued by a well known certificate authority. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: es +spec: + version: 8.16.1 + nodeSets: + - name: mixed + count: 3 +``` + +1. Extract the cacerts JVM trust store from one of the running Elasticsearch nodes. + + ```sh + kubectl cp es-es-mixed-0:/usr/share/elasticsearch/jdk/lib/security/cacerts cacerts + ``` + + ::::{note} + You can skip this step if you want to create a new trust store that does not contain any well known CAs that Elasticsearch trusts by default. Be aware that this limits Elasticsearch’s ability to communicate with TLS secured endpoints to those for which you add CA certificates in the next steps. + :::: + +2. Obtain the CA certificate used to sign the certificate of your S3-compatible service. We assume it is called `tls.crt` +3. Add the certificate to the JVM trust store from step 1 + + ```sh + keytool -importcert -keystore cacerts -storepass changeit -file tls.crt -alias my-custom-s3-svc + ``` + + ::::{note} + You need to have the Java Runtime environment with the `keytool` installed locally for this step. `changeit` is the default password used by the JVM, but it can be changed with `keytool` as well. + :::: + +4. Create a Kubernetes secret with the amended trust store + + ```sh + kubectl create secret generic custom-truststore --from-file=cacerts + ``` + +5. Create a Kubernetes secret with the credentials for your object store bucket + + ```sh + kubectl create secret generic snapshot-settings \ + --from-literal=s3.client.default.access_key=$YOUR_ACCESS_KEY \ + --from-literal=s3.client.default.secret_key=$YOUR_SECRET_ACCESS_KEY + ``` + +6. Update your Elasticsearch cluster to use the trust store and credentials from the Kubernetes secrets + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: es + spec: + version: 8.16.1 + secureSettings: + - secretName: snapshot-settings + nodeSets: + - name: mixed + count: 3 + podTemplate: + spec: + volumes: + - name: custom-truststore + secret: + secretName: custom-truststore + containers: + - name: elasticsearch + volumeMounts: + - name: custom-truststore + mountPath: /usr/share/elasticsearch/config/custom-truststore + env: + - name: ES_JAVA_OPTS + value: "-Djavax.net.ssl.trustStore=/usr/share/elasticsearch/config/custom-truststore/cacerts -Djavax.net.ssl.keyStorePassword=changeit" + ``` + +7. Create the snapshot repository + + ```sh + POST _snapshot/my_s3_repository + { + "type": "s3", + "settings": { + "bucket": "es-repo", + "path_style_access": true, <1> + "endpoint": "https://mys3service.default.svc.cluster.local/" <2> + } + } + ``` + + 1. Whether or not you need to enable `path_style_access` depends on your choice of S3-compatible storage service and how it is deployed. If it is exposed through a standard Kubernetes service it is likely you need this option + 2. Replace this with the actual endpoint of your S3-compatible service + + + +### Install a snapshot repository plugin [k8s-install-plugin] + +If you are running a version of Elasticsearch before 8.0 or you need a snapshot repository plugin that is not already pre-installed you have to install the plugin yourself. To install the snapshot repository plugin, you can either use a [custom image](../../deploy/cloud-on-k8s/create-custom-images.md) or [add your own init container](../../deploy/cloud-on-k8s/init-containers-for-plugin-downloads.md) which installs the plugin when the Pod is created. + +To use your own custom image with all necessary plugins pre-installed, use an Elasticsearch resource like the following: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + image: your/custom/image:tag + nodeSets: + - name: default + count: 1 +``` + +Alternatively, install the plugin when the Pod is created by using an init container: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + nodeSets: + - name: default + count: 1 + podTemplate: + spec: + initContainers: + - name: install-plugins + command: + - sh + - -c + - | + bin/elasticsearch-plugin remove --purge repository-gcs + bin/elasticsearch-plugin install --batch repository-gcs +``` + +Assuming you stored this in a file called `elasticsearch.yaml` you can in both cases create the Elasticsearch cluster with: + +```sh +kubectl apply -f elasticsearch.yaml +``` + + + diff --git a/deploy-manage/tools/snapshot-and-restore/create-snapshots.md b/deploy-manage/tools/snapshot-and-restore/create-snapshots.md new file mode 100644 index 000000000..2d73c11da --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/create-snapshots.md @@ -0,0 +1,447 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html +--- + +# Create snapshots [snapshots-take-snapshot] + +This guide shows you how to take snapshots of a running cluster. You can later [restore a snapshot](restore-snapshot.md) to recover or transfer its data. + +In this guide, you’ll learn how to: + +* Automate snapshot creation and retention with {{slm}} ({{slm-init}}) +* Manually take a snapshot +* Monitor a snapshot’s progress +* Delete or cancel a snapshot +* Back up cluster configuration files + +The guide also provides tips for creating dedicated cluster state snapshots and taking snapshots at different time intervals. + + +## Prerequisites [create-snapshot-prereqs] + +* To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions: + + * [Cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + * [Index privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index + +* You can only take a snapshot from a running cluster with an elected [master node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role). +* A snapshot repository must be [registered](self-managed.md) and available to the cluster. +* The cluster’s global metadata must be readable. To include an index in a snapshot, the index and its metadata must also be readable. Ensure there aren’t any [cluster blocks](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-read-only) or [index blocks](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules-blocks.html) that prevent read access. + + +## Considerations [create-snapshot-considerations] + +* Each snapshot must have a unique name within its repository. Attempts to create a snapshot with the same name as an existing snapshot will fail. +* Snapshots are automatically deduplicated. You can take frequent snapshots with little impact to your storage overhead. +* Each snapshot is logically independent. You can delete a snapshot without affecting other snapshots. +* Taking a snapshot can temporarily pause shard allocations. See [Snapshots and shard allocation](../snapshot-and-restore.md#snapshots-shard-allocation). +* Taking a snapshot doesn’t block indexing or other requests. However, the snapshot won’t include changes made after the snapshot process starts. +* You can take multiple snapshots at the same time. The [`snapshot.max_concurrent_operations`](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-settings.html#snapshot-max-concurrent-ops) cluster setting limits the maximum number of concurrent snapshot operations. +* If you include a data stream in a snapshot, the snapshot also includes the stream’s backing indices and metadata. + + You can also include only specific backing indices in a snapshot. However, the snapshot won’t include the data stream’s metadata or its other backing indices. + +* A snapshot can include a data stream but exclude specific backing indices. When you restore such a data stream, it will contain only backing indices in the snapshot. If the stream’s original write index is not in the snapshot, the most recent backing index from the snapshot becomes the stream’s write index. + + +## Automate snapshots with {{slm-init}} [automate-snapshots-slm] + +{{slm-cap}} ({{slm-init}}) is the easiest way to regularly back up a cluster. An {{slm-init}} policy automatically takes snapshots on a preset schedule. The policy can also delete snapshots based on retention rules you define. + +::::{tip} +{{ess}} deployments automatically include the `cloud-snapshot-policy` {{slm-init}} policy. {{ess}} uses this policy to take periodic snapshots of your cluster. For more information, see the [{{ess}} snapshot documentation](../snapshot-and-restore.md). +:::: + + + +### {{slm-init}} security [slm-security] + +The following [cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {security-features} are enabled: + +`manage_slm` +: Allows a user to perform all {{slm-init}} actions, including creating and updating policies and starting and stopping {{slm-init}}. + +`read_slm` +: Allows a user to perform all read-only {{slm-init}} actions, such as getting policies and checking the {{slm-init}} status. + +`cluster:admin/snapshot/*` +: Allows a user to take and delete snapshots of any index, whether or not they have access to that index. + +You can create and manage roles to assign these privileges through {{kib}} Management. + +To grant the privileges necessary to create and manage {{slm-init}} policies and snapshots, you can set up a role with the `manage_slm` and `cluster:admin/snapshot/*` cluster privileges and full access to the {{slm-init}} history indices. + +For example, the following request creates an `slm-admin` role: + +```console +POST _security/role/slm-admin +{ + "cluster": [ "manage_slm", "cluster:admin/snapshot/*" ], + "indices": [ + { + "names": [ ".slm-history-*" ], + "privileges": [ "all" ] + } + ] +} +``` + +To grant read-only access to {{slm-init}} policies and the snapshot history, you can set up a role with the `read_slm` cluster privilege and read access to the {{slm}} history indices. + +For example, the following request creates a `slm-read-only` role: + +```console +POST _security/role/slm-read-only +{ + "cluster": [ "read_slm" ], + "indices": [ + { + "names": [ ".slm-history-*" ], + "privileges": [ "read" ] + } + ] +} +``` + + +### Create an {{slm-init}} policy [create-slm-policy] + +To manage {{slm-init}} in {{kib}}, go to the main menu and click **Stack Management** > **Snapshot and Restore*** > ***Policies**. To create a policy, click **Create policy**. + +You can also manage {{slm-init}} using the [{{slm-init}} APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management-api.html). To create a policy, use the [create {{slm-init}} policy API](https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put-policy.html). + +The following request creates a policy that backs up the cluster state, all data streams, and all indices daily at 1:30 a.m. UTC. + +```console +PUT _slm/policy/nightly-snapshots +{ + "schedule": "0 30 1 * * ?", <1> + "name": "", <2> + "repository": "my_repository", <3> + "config": { + "indices": "*", <4> + "include_global_state": true <5> + }, + "retention": { <6> + "expire_after": "30d", + "min_count": 5, + "max_count": 50 + } +} +``` + +1. When to take snapshots, written in [Cron syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/_schedule_types.html#schedule-cron). +2. Snapshot name. Supports [date math](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#api-date-math-index-names). To prevent naming conflicts, the policy also appends a UUID to each snapshot name. +3. [Registered snapshot repository](self-managed.md) used to store the policy’s snapshots. +4. Data streams and indices to include in the policy’s snapshots. +5. If `true`, the policy’s snapshots include the cluster state. This also includes all feature states by default. To only include specific feature states, see [Back up a specific feature state](#back-up-specific-feature-state). +6. Optional retention rules. This configuration keeps snapshots for 30 days, retaining at least 5 and no more than 50 snapshots regardless of age. See [{{slm-init}} retention](#slm-retention-task) and [Snapshot retention limits](#snapshot-retention-limits). + + + +### Manually run an {{slm-init}} policy [manually-run-slm-policy] + +You can manually run an {{slm-init}} policy to immediately create a snapshot. This is useful for testing a new policy or taking a snapshot before an upgrade. Manually running a policy doesn’t affect its snapshot schedule. + +To run a policy in {{kib}}, go to the **Policies** page and click the run icon under the **Actions** column. You can also use the [execute {{slm-init}} policy API](https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-lifecycle.html). + +```console +POST _slm/policy/nightly-snapshots/_execute +``` + +The snapshot process runs in the background. To monitor its progress, see [Monitor a snapshot](#monitor-snapshot). + + +### {{slm-init}} retention [slm-retention-task] + +{{slm-init}} snapshot retention is a cluster-level task that runs separately from a policy’s snapshot schedule. To control when the {{slm-init}} retention task runs, configure the [`slm.retention_schedule`](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-settings.html#slm-retention-schedule) cluster setting. + +```console +PUT _cluster/settings +{ + "persistent" : { + "slm.retention_schedule" : "0 30 1 * * ?" + } +} +``` + +To immediately run the retention task, use the [execute {{slm-init}} retention policy API](https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-retention.html). + +```console +POST _slm/_execute_retention +``` + +An {{slm-init}} policy’s retention rules only apply to snapshots created using the policy. Other snapshots don’t count toward the policy’s retention limits. + + +### Snapshot retention limits [snapshot-retention-limits] + +We recommend you include retention rules in your {{slm-init}} policy to delete snapshots you no longer need. + +A snapshot repository can safely scale to thousands of snapshots. However, to manage its metadata, a large repository requires more memory on the master node. Retention rules ensure a repository’s metadata doesn’t grow to a size that could destabilize the master node. + + +## Manually create a snapshot [manually-create-snapshot] + +To take a snapshot without an {{slm-init}} policy, use the [create snapshot API](https://www.elastic.co/guide/en/elasticsearch/reference/current/create-snapshot-api.html). The snapshot name supports [date math](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#api-date-math-index-names). + +```console +# PUT _snapshot/my_repository/ +PUT _snapshot/my_repository/%3Cmy_snapshot_%7Bnow%2Fd%7D%3E +``` + +Depending on its size, a snapshot can take a while to complete. By default, the create snapshot API only initiates the snapshot process, which runs in the background. To block the client until the snapshot finishes, set the `wait_for_completion` query parameter to `true`. + +```console +PUT _snapshot/my_repository/my_snapshot?wait_for_completion=true +``` + +You can also clone an existing snapshot using [clone snapshot API](https://www.elastic.co/guide/en/elasticsearch/reference/current/clone-snapshot-api.html). + + +## Monitor a snapshot [monitor-snapshot] + +To monitor any currently running snapshots, use the [get snapshot API](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-snapshot-api.html) with the `_current` request path parameter. + +```console +GET _snapshot/my_repository/_current +``` + +To get a complete breakdown of each shard participating in any currently running snapshots, use the [get snapshot status API](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-snapshot-api.html). + +```console +GET _snapshot/_status +``` + + +### Check {{slm-init}} history [check-slm-history] + +To get more information about a cluster’s {{slm-init}} execution history, including stats for each {{slm-init}} policy, use the [get {{slm-init}} stats API](https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-stats.html). The API also returns information about the cluster’s snapshot retention task history. + +```console +GET _slm/stats +``` + +To get information about a specific {{slm-init}} policy’s execution history, use the [get {{slm-init}} policy API](https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-policy.html). The response includes: + +* The next scheduled policy execution. +* The last time the policy successfully started the snapshot process, if applicable. A successful start doesn’t guarantee the snapshot completed. +* The last time policy execution failed, if applicable, and the associated error. + +```console +GET _slm/policy/nightly-snapshots +``` + + +## Delete or cancel a snapshot [delete-snapshot] + +To delete a snapshot in {{kib}}, go to the **Snapshots** page and click the trash icon under the **Actions** column. You can also use the [delete snapshot API](https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-snapshot-api.html). + +```console +DELETE _snapshot/my_repository/my_snapshot_2099.05.06 +``` + +If you delete a snapshot that’s in progress, {{es}} cancels it. The snapshot process halts and deletes any files created for the snapshot. Deleting a snapshot doesn’t delete files used by other snapshots. + + +## Back up configuration files [back-up-config-files] + +If you run {{es}} on your own hardware, we recommend that, in addition to backups, you take regular backups of the files in each node’s [`$ES_PATH_CONF` directory](../../deploy/self-managed/configure-elasticsearch.md#config-files-location) using the file backup software of your choice. Snapshots don’t back up these files. Also note that these files will differ on each node, so each node’s files should be backed up individually. + +::::{important} +The `elasticsearch.keystore`, TLS keys, and [SAML](../../deploy/self-managed/configure-elasticsearch.md#ref-saml-settings), [OIDC](../../deploy/self-managed/configure-elasticsearch.md#ref-oidc-settings), and [Kerberos](../../deploy/self-managed/configure-elasticsearch.md#ref-kerberos-settings) realms private key files contain sensitive information. Consider encrypting your backups of these files. +:::: + + + +## Back up a specific feature state [back-up-specific-feature-state] + +By default, a snapshot that includes the cluster state also includes all [feature states](../snapshot-and-restore.md#feature-state). Similarly, a snapshot that excludes the cluster state excludes all feature states by default. + +You can also configure a snapshot to only include specific feature states, regardless of the cluster state. + +To get a list of available features, use the [get features API](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-features-api.html). + +```console +GET _features +``` + +The API returns: + +```console-result +{ + "features": [ + { + "name": "tasks", + "description": "Manages task results" + }, + { + "name": "kibana", + "description": "Manages Kibana configuration and reports" + }, + { + "name": "security", + "description": "Manages configuration for Security features, such as users and roles" + }, + ... + ] +} +``` + +To include a specific feature state in a snapshot, specify the feature `name` in the `feature_states` array. + +For example, the following {{slm-init}} policy only includes feature states for the {{kib}} and {{es}} security features in its snapshots. + +```console +PUT _slm/policy/nightly-snapshots +{ + "schedule": "0 30 2 * * ?", + "name": "", + "repository": "my_repository", + "config": { + "indices": "*", + "include_global_state": true, + "feature_states": [ + "kibana", + "security" + ] + }, + "retention": { + "expire_after": "30d", + "min_count": 5, + "max_count": 50 + } +} +``` + +Any index or data stream that’s part of the feature state will display in a snapshot’s contents. For example, if you back up the `security` feature state, the `security-*` system indices display in the [get snapshot API](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-snapshot-api.html)'s response under both `indices` and `feature_states`. + + +## Dedicated cluster state snapshots [cluster-state-snapshots] + +Some feature states contain sensitive data. For example, the `security` feature state includes system indices that may contain user names and encrypted password hashes. Because passwords are stored using [cryptographic hashes](../../deploy/self-managed/configure-elasticsearch.md#hashing-settings), the disclosure of a snapshot would not automatically enable a third party to authenticate as one of your users or use API keys. However, it would disclose confidential information, and if a third party can modify snapshots, they could install a back door. + +To better protect this data, consider creating a dedicated repository and {{slm-init}} policy for snapshots of the cluster state. This lets you strictly limit and audit access to the repository. + +For example, the following {{slm-init}} policy only backs up the cluster state. The policy stores these snapshots in a dedicated repository. + +```console +PUT _slm/policy/nightly-cluster-state-snapshots +{ + "schedule": "0 30 2 * * ?", + "name": "", + "repository": "my_secure_repository", + "config": { + "include_global_state": true, <1> + "indices": "-*" <2> + }, + "retention": { + "expire_after": "30d", + "min_count": 5, + "max_count": 50 + } +} +``` + +1. Includes the cluster state. This also includes all feature states by default. +2. Excludes regular data streams and indices. + + +If you take dedicated snapshots of the cluster state, you’ll need to exclude the cluster state from your other snapshots. For example: + +```console +PUT _slm/policy/nightly-snapshots +{ + "schedule": "0 30 2 * * ?", + "name": "", + "repository": "my_repository", + "config": { + "include_global_state": false, <1> + "indices": "*" <2> + }, + "retention": { + "expire_after": "30d", + "min_count": 5, + "max_count": 50 + } +} +``` + +1. Excludes the cluster state. This also excludes all feature states by default. +2. Includes all regular data streams and indices. + + + +## Create snapshots at different time intervals [create-snapshots-different-time-intervals] + +If you only use a single {{slm-init}} policy, it can be difficult to take frequent snapshots and retain snapshots with longer time intervals. + +For example, a policy that takes snapshots every 30 minutes with a maximum of 100 snapshots will only keep snapshots for approximately two days. While this setup is great for backing up recent changes, it doesn’t let you restore data from a previous week or month. + +To fix this, you can create multiple {{slm-init}} policies with the same snapshot repository that run on different schedules. Since a policy’s retention rules only apply to its snapshots, a policy won’t delete a snapshot created by another policy. + +For example, the following {{slm-init}} policy takes hourly snapshots with a maximum of 24 snapshots. The policy keeps its snapshots for one day. + +```console +PUT _slm/policy/hourly-snapshots +{ + "name": "", + "schedule": "0 0 * * * ?", + "repository": "my_repository", + "config": { + "indices": "*", + "include_global_state": true + }, + "retention": { + "expire_after": "1d", + "min_count": 1, + "max_count": 24 + } +} +``` + +The following policy takes nightly snapshots in the same snapshot repository. The policy keeps its snapshots for one month. + +```console +PUT _slm/policy/daily-snapshots +{ + "name": "", + "schedule": "0 45 23 * * ?", <1> + "repository": "my_repository", + "config": { + "indices": "*", + "include_global_state": true + }, + "retention": { + "expire_after": "30d", + "min_count": 1, + "max_count": 31 + } +} +``` + +1. Runs at 11:45 p.m. UTC every day. + + +The following policy creates monthly snapshots in the same repository. The policy keeps its snapshots for one year. + +```console +PUT _slm/policy/monthly-snapshots +{ + "name": "", + "schedule": "0 56 23 1 * ?", <1> + "repository": "my_repository", + "config": { + "indices": "*", + "include_global_state": true + }, + "retention": { + "expire_after": "366d", + "min_count": 1, + "max_count": 12 + } +} +``` + +1. Runs on the first of the month at 11:56 p.m. UTC. diff --git a/deploy-manage/tools/snapshot-and-restore/ec-aws-custom-repository.md b/deploy-manage/tools/snapshot-and-restore/ec-aws-custom-repository.md new file mode 100644 index 000000000..5bb7f5da6 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ec-aws-custom-repository.md @@ -0,0 +1,76 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-aws-custom-repository.html +--- + +# Configure a snapshot repository using AWS S3 [ec-aws-custom-repository] + +Configure a custom snapshot repository using an S3 storage bucket in your AWS account. + + +## Prepare an S3 bucket [ec-prepare-aws-bucket] + +Create the S3 bucket in your custom AWS account. Make sure to reserve this bucket to backup only one cluster, since AWS allows file overwrite for non-unique titles. + +Next, create an IAM user, copy the access key ID and secret, and configure the following user policy. This is important to make sure the access keys, which you will need to provide to your cluster, can only access the intended bucket. + +```json +{ + "Version": "policy-language-YYYY-MM-dd",<1> + "Statement": [ + { + "Action": [ + "s3:*" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::bucket-name", + "arn:aws:s3:::bucket-name/*" + ] + } + ] +} +``` + +1. The version of the policy language syntax rules. For more information, refer to the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-reference-policy-checks.md#access-analyzer-reference-policy-checks-error-invalid-version). + + +For more information on S3 and IAM, refer to AWS' [S3-documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.md) and [IAM-documentation](http://aws.amazon.com/documentation/iam/). + +::::{note} +For a full list of settings that are supported for your S3 bucket, refer to [S3 repository](s3-repository.md) in the {{es}} Guide. +:::: + + + +## Store your secrets in the keystore [ec-snapshot-secrets-keystore] + +You can use the Elasticsearch Service Keystore to store the credentials to access your AWS account. + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Navigate to the **Security** page of the deployment you wish to configure. +3. Locate **Elasticsearch keystore** and select **Add settings**. +4. With **Type** set to **Single string**, add the following keys and their values: + + * `s3.client.secondary.access_key` + * `s3.client.secondary.secret_key` + +5. Perform a cluster restart to [reload the secure settings](https://www.elastic.co/guide/en/cloud/current/ec-configuring-keystore.html#ec-add-secret-values). + + +## Create the repository [ec-create-aws-repository] + +1. Open Kibana and go to **Management** > **Snapshot and Restore**. +2. On the **Repositories** tab, select **Register a repository**. +3. Provide a name for your repository and select type **AWS S3**. +4. Provide the following settings: + + * Client: `secondary` + * Bucket: `YOUR_S3_BUCKET_NAME` + +5. Add any other settings that you wish to configure. +6. Select **Register**. +7. Select **Verify** to confirm that your settings are correct and the deployment can connect to your repository. + +Your snapshot repository is now set up using S3! You can use Kibana to manage your snapshots and begin sending Elasticsearch snapshots to your own bucket. For details refer to the [Snapshot and Restore](create-snapshots.md) documentation. + diff --git a/deploy-manage/tools/snapshot-and-restore/ec-azure-snapshotting.md b/deploy-manage/tools/snapshot-and-restore/ec-azure-snapshotting.md new file mode 100644 index 000000000..b5a9b1079 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ec-azure-snapshotting.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-azure-snapshotting.html +--- + +# Configure a snapshot repository using Azure Blob storage [ec-azure-snapshotting] + +Configure a custom snapshot repository using your Azure Blob storage account. + + +## Prepare a container [ec-prepare-azure-container] + +Follow the Microsoft documentation to [set up an Azure storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create) with an access key, and then [create a container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal). + + +## Enable the `repository-azure` plugin in Elastic Stack 7.17 and earlier [ec-enable-azure-plugin] + +For deployments with **Elastic Stack version 7.17 and earlier**, you’ll need to enable the `repository-azure` plugin to use the Azure repository type. On the Azure platform, the plugin is enabled by default. If your deployment is on AWS or GCP, follow these steps to enable the `repository-azure` plugin: + +1. Refer to [Azure Repository Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/7.17/repository-azure.html) to download the version of the plugin that matches your Elastic Stack version. +2. Upload the plugin to your deployment: + + 1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). + 2. Open the **Features > Extensions** page and select **Upload extension**. + 3. Specify the plugin name (`repository-azure`) and the version. + 4. Select **An installable plugin (Compiled, no source code)**. + 5. Select **Create extension**. + 6. Navigate back to the **Features > Extensions** page. + 7. Select the extension name. + 8. Drag and drop to upload the `repository-azure` plugin zip file. + + + +### Configure the keystore [ec-configure-azure-keystore] + +Create an entry for the Azure client in the Elasticsearch keystore: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Navigate to the **Security** page of the deployment you wish to configure. +3. Locate **Elasticsearch keystore** and select **Add settings**. +4. With **Type** set to **Single string**, add the following keys and their values: + + * `azure.client.secondary.account` + * `azure.client.secondary.key` + +5. Select **Save**. + + +### Create the repository [ec-create-azure-repository] + +1. Open Kibana and go to **Management** > **Snapshot and Restore**. +2. On the **Repositories** tab, select **Register a repository**. +3. Provide a name for your repository and select type **Azure**. +4. Provide the following settings: + + * Client: `secondary` + + * You can also use `default`, but we recommend using `secondary` to ensure that your secure settings are mapped to the correct repository definition. + + * Container: The name of your Azure container + * base_path: A directory to contain the snapshots + + * This setting is optional. Include a `base_path` if you have multiple clusters writing to the same Azure repository. This ensures that a snapshot won’t overwrite the snapshot metadata for another cluster. + +5. Add any other settings that you wish to configure. +6. Select Register. +7. Select **Verify** to confirm that your settings are correct and the deployment can connect to your repository. + +Your snapshot repository is now set up using Azure Blob storage! You can use Kibana to manage your snapshots and begin sending Elasticsearch snapshots to your own container. For details, check the [Snapshot and Restore](create-snapshots.md) documentation. + diff --git a/deploy-manage/tools/snapshot-and-restore/ec-custom-repository.md b/deploy-manage/tools/snapshot-and-restore/ec-custom-repository.md new file mode 100644 index 000000000..89e087c65 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ec-custom-repository.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-custom-repository.html +--- + +# Snapshot and restore with custom repositories [ec-custom-repository] + +Specify your own repositories to snapshot to and restore from. This can be useful, for example, to do long-term archiving of old indexes, restore snapshots across Elastic Cloud accounts, or to be certain you have an exit strategy, should you need to move away from our service. + +Elasticsearch Service supports these repositories: + +* [Amazon Web Services (AWS)](ec-aws-custom-repository.md) +* [Google Cloud Storage (GCS)](ec-gcs-snapshotting.md) +* [Azure Blob Storage](ec-azure-snapshotting.md) + +::::{note} +Automated snapshots are only available in the *found snapshots* repository. You are responsible for the execution and maintenance of the snapshots that you store in custom repositories. Note that the automated snapshot frequency might conflict with manual snapshots. You can enable SLM to automate snapshot management in a custom repository. +:::: + + +::::{tip} +By using a custom repository, you can restore snapshots across regions. +:::: + + + + + diff --git a/deploy-manage/tools/snapshot-and-restore/ec-gcs-snapshotting.md b/deploy-manage/tools/snapshot-and-restore/ec-gcs-snapshotting.md new file mode 100644 index 000000000..ca986a155 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ec-gcs-snapshotting.md @@ -0,0 +1,77 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-gcs-snapshotting.html +--- + +# Configure a snapshot repository using GCS [ec-gcs-snapshotting] + +Configure a custom snapshot repository using your Google Cloud Storage account. + + +## Set up your service account credentials [ec-gcs-service-account-key] + +You’ll need to have an existing Google Cloud account and have the appropriate permissions to generate credentials. + +1. Create a [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) in your Google Cloud project. + + The service account should be configured to have permission to read, write, and list the bucket objects. For more information, refer to [Recommended bucket permission](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html#repository-gcs-bucket-permission) in the Elasticsearch docs. + +2. Save the service account key in JSON file format. You are going to use it later to configure your Elasticsearch deployment for snapshotting. + +For more detailed information on the JSON account service key, refer to [Using a Service Account](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html#repository-gcs-using-service-account). + + +## Prepare a bucket [ec-prepare-gcs-bucket] + +Follow the Google Cloud Storage documentation to [create a GCS bucket](https://cloud.google.com/storage/docs/creating-buckets). + + +## Enable the `repository-gcs` plugin in Elastic Stack 7.17 and earlier [ec-enable-gcs-plugin] + +For deployments with **Elastic Stack version 7.17 and earlier**, you’ll need to enable the `repository-gcs` plugin to use the Google Cloud Storage repository type. On Google Cloud Platform, the plugin is enabled by default. If your deployment is on AWS or Azure, follow these steps to enable the `repository-gcs` plugin: + +1. Refer to [Google Cloud Storage Repository Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/7.17/repository-gcs.html) to download the version of the plugin that matches your Elastic Stack version. +2. Upload the plugin to your deployment: + + 1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). + 2. Open the **Features > Extensions** page and select **Upload extension**. + 3. Specify the plugin name (`repository-gcs`) and the version. + 4. Select **An installable plugin (Compiled, no source code)**. + 5. Select **Create extension**. + 6. Navigate back to the **Features > Extensions** page. + 7. Select the extension name. + 8. Drag and drop to upload the `repository-gcs` plugin zip file. + + + +### Configure the keystore [ec-configure-gcs-keystore] + +Create an entry for the GCS client in the Elasticsearch keystore: + +1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Navigate to the **Security** page of the deployment you wish to configure. +3. Locate **Elasticsearch keystore** and select **Add settings**. +4. Enter the **Setting name** `gcs.client.secondary.credentials_file`. +5. With **Type** set to **JSON block / file**, add your [GCS service account key JSON file](#ec-gcs-service-account-key). +6. Select **Save**. + + +### Create the repository [ec-create-gcs-repository] + +1. Open Kibana and go to **Management** > **Snapshot and Restore**. +2. On the **Repositories** tab, select **Register a repository**. +3. Provide a name for your repository and select type **Google Cloud Storage**. +4. Provide the following settings: + + * Client: `secondary` + * Bucket: Your GCS bucket name + * Base path: A directory to contain the snapshots + + * This setting is optional. Include a `base_path` if you have multiple clusters writing to the same GCS repository. This ensures that a snapshot won’t overwrite the snapshot metadata for another cluster. + +5. Add any other settings that you wish to configure. +6. Select **Register**. +7. Select **Verify** to confirm that your settings are correct and the deployment can connect to your repository. + +Your snapshot repository is now set up using GCS! You can use Kibana to manage your snapshots and begin sending Elasticsearch snapshots to your own bucket. For details, check the [Snapshot and Restore](create-snapshots.md) documentation. + diff --git a/deploy-manage/tools/snapshot-and-restore/ece-restore-across-clusters.md b/deploy-manage/tools/snapshot-and-restore/ece-restore-across-clusters.md new file mode 100644 index 000000000..b3a2f15ce --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ece-restore-across-clusters.md @@ -0,0 +1,53 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restore-across-clusters.html +--- + +# Restore a snapshot across clusters [ece-restore-across-clusters] + +Snapshots can be restored to either the same Elasticsearch cluster or to another cluster. If you are restoring all indices to another cluster, you can *clone* a cluster. + +::::{note} +Users created using the X-Pack security features or using Shield are not included when you restore across clusters, only data from Elasticsearch indices is restored. If you do want to create a cloned cluster with the same users as your old cluster, you need to recreate the users manually on the new cluster. +:::: + + +Restoring to another cluster is useful for scenarios where isolating activities on a separate cluster is beneficial, such as: + +Performing ad hoc analytics +: For most logging and metrics use cases, it is cost prohibitive to have all the data in memory, even if it would provide the best performance for aggregations. Cloning the relevant data to an ad hoc analytics cluster that can be discarded after use is a cost effective way to experiment with your data, without risk to existing clusters used for production. + +Enabling your developers +: Realistic test data is crucial for uncovering unexpected errors early in the development cycle. What can be more realistic than actual data from a production cluster? Giving your developers access to real production data is a great way to break down silos. + +Testing mapping changes +: Mapping changes almost always require reindexing. Unless your data volume is trivial, reindexing requires time and tweaking the parameters to achieve the best reindexing performance usually takes a little trial and error. While this use case could also be handled by running the scan and scroll query directly against the source cluster, a long lived scroll has the side effect of blocking merges even if the scan query is very light weight. + +Integration testing +: Test your application against a real live Elasticsearch cluster with actual data. If you automate this, you could also aggregate performance metrics from the tests and use those metrics to detect if a change in your application has introduced a performance degradation. + +::::{note} +A cluster is eligible as a destination for a built-in snapshot restore if it meets these criteria: + +* The destination cluster is able to read the indices. You can generally restore to your Elasticsearch cluster snapshots of indices created back to the previous major version, but see the [version matrix](../snapshot-and-restore.md#snapshot-restore-version-compatibility) for all the details. + +:::: + + +The list of available snapshots can be found in the [`found-snapshots` repository](self-managed.md#ess-repo-types). + +To restore built-in snapshots across clusters, there are two options: + +* [Restore snapshot into a new deployment](ece-restore-snapshots-into-new-deployment.md) +* [Restore snapshot into an existing deployment](ece-restore-snapshots-into-existing-deployment.md) + +When restoring snapshots across clusters, we create a new repository called `\_clone_{{clusterIdPrefix}}`, which persists until manually deleted. If the repository is still in use, for example by mounted searchable snapshots, it can’t be removed. + +::::{warning} +When restoring from a deployment that’s using searchable snapshots, refer to [Restore snapshots containing searchable snapshots indices across clusters](ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md) +:::: + + + + + diff --git a/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md b/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md new file mode 100644 index 000000000..dc35e9c11 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters.html +--- + +# Restore snapshots containing searchable snapshots indices across clusters [ece-restore-snapshots-containing-searchable-snapshots-indices-across-clusters] + +If you are restoring a snapshot from one cluster to another, and that snapshot contains indices that are backed by searchable snapshots, there are a few more requirements to be aware of. + +The first versions of Elasticsearch that supported searchable snapshots required that the repository name in the destination cluster, where the snapshot is to be restored from, match the repository name in the source cluster, where the snapshot was taken. Beginning with Elasticsearch version 7.12 this requirement is no longer present, but there are other prerequisites that need to be met. + +Pre-requisites for restoring snapshots containing searchable snapshot indices across clusters: + +* The source cluster must have been created as version 7.12.0 or higher. + + To be more precise the requirement is on the `found-snapshots` repository settings at the time the snapshots were taken. The repository must have a `uuid` field, which is supported only in Elasticsearch versions 7.12.0 and higher. If the cluster was created with a previous version and later upgraded to 7.12.0 or higher, the repository may not have the required `uuid` field and therefore cannot be used to restore onto another cluster. + + To be sure, you can send a `GET /_snapshot/found-snapshots` request to your Elasticsearch cluster and check if the `uuid` field is present. + +* The destination cluster must be version 7.13.2 or higher. + + Previous versions had issues restoring the snapshot or recovering searchable snapshot indices in case of, for example, node failure. + + +::::{important} +The snapshot in the source cluster MUST NOT be deleted even after being successfully restored in the destination cluster. In fact, that’s also the case for the searchable snapshots in the source cluster for which there were indices backed by the restored snapshot. These snapshots are required for recovery of the searchable snapshot indices in case of, for example, node failure. + +This means that until you delete the searchable snapshot indices in the destination cluster, you must not delete your source deployment, delete the restored snapshot, or delete any of the searchable snapshots used by the searchable snapshot indices. + +Read [Back up and restore searchable snapshots](searchable-snapshots.md#back-up-restore-searchable-snapshots) for more guidance. + +:::: + + diff --git a/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-into-existing-deployment.md b/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-into-existing-deployment.md new file mode 100644 index 000000000..82a5230d7 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-into-existing-deployment.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restore-snapshots-into-existing-deployment.html +--- + +# Restore snapshot into an existing deployment [ece-restore-snapshots-into-existing-deployment] + +You can restore a snapshot to recover indices and data streams after deletion or as part of disaster recovery. + +1. From your deployment menu, go to **Elasticsearch** and then **Snapshots**. +2. On the **Snapshots** page, click **Restore from another deployment**. +3. Configure the deployment and snapshot to use. +4. Click *Restore snapshot* to start the restore process. + diff --git a/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-into-new-deployment.md b/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-into-new-deployment.md new file mode 100644 index 000000000..7c1d6c875 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ece-restore-snapshots-into-new-deployment.md @@ -0,0 +1,14 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restore-snapshots-into-new-deployment.html +--- + +# Restore snapshot into a new deployment [ece-restore-snapshots-into-new-deployment] + +1. First, [create a new deployment](../../deploy/cloud-enterprise/create-deployment.md) and select **Restore snapshot data**. Select the deployment that you want to restore a snapshot *from*. If you don’t know the exact name, you can enter a few characters and then select from the list of matching deployments. +2. Select the snapshot that you want to restore from. If none is chosen, the latest successful snapshot from the cluster you selected is restored on the new cluster when you create it. + + ![Restoring from a snapshot](../../../images/cloud-enterprise-restore-from-snapshot.png "") + +3. Manually recreate users using the X-Pack security features or using Shield on the new cluster. User information is not included when you restore across clusters. + diff --git a/deploy-manage/tools/snapshot-and-restore/ech-aws-custom-repository.md b/deploy-manage/tools/snapshot-and-restore/ech-aws-custom-repository.md new file mode 100644 index 000000000..f2db5ba59 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ech-aws-custom-repository.md @@ -0,0 +1,76 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-aws-custom-repository.html +--- + +# Configure a snapshot repository using AWS S3 [ech-aws-custom-repository] + +Configure a custom snapshot repository using an S3 storage bucket in your AWS account. + + +## Prepare an S3 bucket [ech-prepare-aws-bucket] + +Create the S3 bucket in your custom AWS account. Make sure to reserve this bucket to backup only one cluster, since AWS allows file overwrite for non-unique titles. + +Next, create an IAM user, copy the access key ID and secret, and configure the following user policy. This is important to make sure the access keys, which you will need to provide to your cluster, can only access the intended bucket. + +```json +{ + "Version": "policy-language-YYYY-MM-dd",<1> + "Statement": [ + { + "Action": [ + "s3:*" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::bucket-name", + "arn:aws:s3:::bucket-name/*" + ] + } + ] +} +``` + +1. The version of the policy language syntax rules. For more information, refer to the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-reference-policy-checks.md#access-analyzer-reference-policy-checks-error-invalid-version). + + +For more information on S3 and IAM, refer to AWS' [S3-documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.md) and [IAM-documentation](http://aws.amazon.com/documentation/iam/). + +::::{note} +For a full list of settings that are supported for your S3 bucket, refer to [S3 repository](s3-repository.md) in the {{es}} Guide. +:::: + + + +## Store your secrets in the keystore [ech-snapshot-secrets-keystore] + +You can use the Elasticsearch Add-On for Heroku Keystore to store the credentials to access your AWS account. + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Navigate to the **Security** page of the deployment you wish to configure. +3. Locate **Elasticsearch keystore** and select **Add settings**. +4. With **Type** set to **Single string**, add the following keys and their values: + + * `s3.client.secondary.access_key` + * `s3.client.secondary.secret_key` + +5. Perform a cluster restart to [reload the secure settings](https://www.elastic.co/guide/en/cloud/current/ec-configuring-keystore.html#ec-add-secret-values). + + +## Create the repository [ech-create-aws-repository] + +1. Open Kibana and go to **Management** > **Snapshot and Restore**. +2. On the **Repositories** tab, select **Register a repository**. +3. Provide a name for your repository and select type **AWS S3**. +4. Provide the following settings: + + * Client: `secondary` + * Bucket: `YOUR_S3_BUCKET_NAME` + +5. Add any other settings that you wish to configure. +6. Select **Register**. +7. Select **Verify** to confirm that your settings are correct and the deployment can connect to your repository. + +Your snapshot repository is now set up using S3! You can use Kibana to manage your snapshots and begin sending Elasticsearch snapshots to your own bucket. For details refer to the [Snapshot and Restore](create-snapshots.md) documentation. + diff --git a/deploy-manage/tools/snapshot-and-restore/ech-azure-snapshotting.md b/deploy-manage/tools/snapshot-and-restore/ech-azure-snapshotting.md new file mode 100644 index 000000000..569fc7df6 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ech-azure-snapshotting.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-azure-snapshotting.html +--- + +# Configure a snapshot repository using Azure Blob storage [ech-azure-snapshotting] + +Configure a custom snapshot repository using your Azure Blob storage account. + + +## Prepare a container [ech-prepare-azure-container] + +Follow the Microsoft documentation to [set up an Azure storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create) with an access key, and then [create a container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal). + + +## Enable the `repository-azure` plugin in Elastic Stack 7.17 and earlier [ech-enable-azure-plugin] + +For deployments with **Elastic Stack version 7.17 and earlier**, you’ll need to enable the `repository-azure` plugin to use the Azure repository type. On the Azure platform, the plugin is enabled by default. If your deployment is on AWS or GCP, follow these steps to enable the `repository-azure` plugin: + +1. Refer to [Azure Repository Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/7.17/repository-azure.html) to download the version of the plugin that matches your Elastic Stack version. +2. Upload the plugin to your deployment: + + 1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). + 2. Open the **Features > Extensions** page and select **Upload extension**. + 3. Specify the plugin name (`repository-azure`) and the version. + 4. Select **An installable plugin (Compiled, no source code)**. + 5. Select **Create extension**. + 6. Navigate back to the **Features > Extensions** page. + 7. Select the extension name. + 8. Drag and drop to upload the `repository-azure` plugin zip file. + + + +### Configure the keystore [ech-configure-azure-keystore] + +Create an entry for the Azure client in the Elasticsearch keystore: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Navigate to the **Security** page of the deployment you wish to configure. +3. Locate **Elasticsearch keystore** and select **Add settings**. +4. With **Type** set to **Single string**, add the following keys and their values: + + * `azure.client.secondary.account` + * `azure.client.secondary.key` + +5. Select **Save**. + + +### Create the repository [ech-create-azure-repository] + +1. Open Kibana and go to **Management** > **Snapshot and Restore**. +2. On the **Repositories** tab, select **Register a repository**. +3. Provide a name for your repository and select type **Azure**. +4. Provide the following settings: + + * Client: `secondary` + + * You can also use `default`, but we recommend using `secondary` to ensure that your secure settings are mapped to the correct repository definition. + + * Container: The name of your Azure container + * base_path: A directory to contain the snapshots + + * This setting is optional. Include a `base_path` if you have multiple clusters writing to the same Azure repository. This ensures that a snapshot won’t overwrite the snapshot metadata for another cluster. + +5. Add any other settings that you wish to configure. +6. Select Register. +7. Select **Verify** to confirm that your settings are correct and the deployment can connect to your repository. + +Your snapshot repository is now set up using Azure Blob storage! You can use Kibana to manage your snapshots and begin sending Elasticsearch snapshots to your own container. For details, check the [Snapshot and Restore](create-snapshots.md) documentation. + diff --git a/deploy-manage/tools/snapshot-and-restore/ech-custom-repository.md b/deploy-manage/tools/snapshot-and-restore/ech-custom-repository.md new file mode 100644 index 000000000..11251740d --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ech-custom-repository.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-custom-repository.html +--- + +# Snapshot and restore with custom repositories [ech-custom-repository] + +Specify your own repositories to snapshot to and restore from. This can be useful, for example, to do long-term archiving of old indexes, restore snapshots across Elastic Cloud accounts, or to be certain you have an exit strategy, should you need to move away from our service. + +Elasticsearch Add-On for Heroku supports these repositories: + +* [Amazon Web Services (AWS)](ech-aws-custom-repository.md) +* [Google Cloud Storage (GCS)](ech-gcs-snapshotting.md) +* [Azure Blob Storage](ech-azure-snapshotting.md) + +::::{note} +Automated snapshots are only available in the *found snapshots* repository. You are responsible for the execution and maintenance of the snapshots that you store in custom repositories. Note that the automated snapshot frequency might conflict with manual snapshots. You can enable SLM to automate snapshot management in a custom repository. +:::: + + +::::{tip} +By using a custom repository, you can restore snapshots across regions. +:::: + + + + + diff --git a/deploy-manage/tools/snapshot-and-restore/ech-gcs-snapshotting.md b/deploy-manage/tools/snapshot-and-restore/ech-gcs-snapshotting.md new file mode 100644 index 000000000..268947843 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/ech-gcs-snapshotting.md @@ -0,0 +1,77 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-gcs-snapshotting.html +--- + +# Configure a snapshot repository using GCS [ech-gcs-snapshotting] + +Configure a custom snapshot repository using your Google Cloud Storage account. + + +## Set up your service account credentials [ech-gcs-service-account-key] + +You’ll need to have an existing Google Cloud account and have the appropriate permissions to generate credentials. + +1. Create a [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) in your Google Cloud project. + + The service account should be configured to have permission to read, write, and list the bucket objects. For more information, refer to [Recommended bucket permission](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html#repository-gcs-bucket-permission) in the Elasticsearch docs. + +2. Save the service account key in JSON file format. You are going to use it later to configure your Elasticsearch deployment for snapshotting. + +For more detailed information on the JSON account service key, refer to [Using a Service Account](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html#repository-gcs-using-service-account). + + +## Prepare a bucket [ech-prepare-gcs-bucket] + +Follow the Google Cloud Storage documentation to [create a GCS bucket](https://cloud.google.com/storage/docs/creating-buckets). + + +## Enable the `repository-gcs` plugin in Elastic Stack 7.17 and earlier [ech-enable-gcs-plugin] + +For deployments with **Elastic Stack version 7.17 and earlier**, you’ll need to enable the `repository-gcs` plugin to use the Google Cloud Storage repository type. On Google Cloud Platform, the plugin is enabled by default. If your deployment is on AWS or Azure, follow these steps to enable the `repository-gcs` plugin: + +1. Refer to [Google Cloud Storage Repository Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/7.17/repository-gcs.html) to download the version of the plugin that matches your Elastic Stack version. +2. Upload the plugin to your deployment: + + 1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). + 2. Open the **Features > Extensions** page and select **Upload extension**. + 3. Specify the plugin name (`repository-gcs`) and the version. + 4. Select **An installable plugin (Compiled, no source code)**. + 5. Select **Create extension**. + 6. Navigate back to the **Features > Extensions** page. + 7. Select the extension name. + 8. Drag and drop to upload the `repository-gcs` plugin zip file. + + + +### Configure the keystore [ech-configure-gcs-keystore] + +Create an entry for the GCS client in the Elasticsearch keystore: + +1. Log in to the [Elasticsearch Add-On for Heroku console](https://cloud.elastic.co?page=docs&placement=docs-body). +2. Navigate to the **Security** page of the deployment you wish to configure. +3. Locate **Elasticsearch keystore** and select **Add settings**. +4. Enter the **Setting name** `gcs.client.secondary.credentials_file`. +5. With **Type** set to **JSON block / file**, add your [GCS service account key JSON file](#ech-gcs-service-account-key). +6. Select **Save**. + + +### Create the repository [ech-create-gcs-repository] + +1. Open Kibana and go to **Management** > **Snapshot and Restore**. +2. On the **Repositories** tab, select **Register a repository**. +3. Provide a name for your repository and select type **Google Cloud Storage**. +4. Provide the following settings: + + * Client: `secondary` + * Bucket: Your GCS bucket name + * Base path: A directory to contain the snapshots + + * This setting is optional. Include a `base_path` if you have multiple clusters writing to the same GCS repository. This ensures that a snapshot won’t overwrite the snapshot metadata for another cluster. + +5. Add any other settings that you wish to configure. +6. Select **Register**. +7. Select **Verify** to confirm that your settings are correct and the deployment can connect to your repository. + +Your snapshot repository is now set up using GCS! You can use Kibana to manage your snapshots and begin sending Elasticsearch snapshots to your own bucket. For details, check the [Snapshot and Restore](create-snapshots.md) documentation. + diff --git a/deploy-manage/tools/snapshot-and-restore/elastic-cloud-hosted.md b/deploy-manage/tools/snapshot-and-restore/elastic-cloud-hosted.md new file mode 100644 index 000000000..eef2e7d74 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/elastic-cloud-hosted.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-custom-repository.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-custom-repository.html +--- + +# Elastic Cloud Hosted + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-custom-repository.md +% Notes: 3 children +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-custom-repository.md +% Notes: redirects only \ No newline at end of file diff --git a/deploy-manage/tools/snapshot-and-restore/google-cloud-storage-gcs-repository.md b/deploy-manage/tools/snapshot-and-restore/google-cloud-storage-gcs-repository.md new file mode 100644 index 000000000..edcb16406 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/google-cloud-storage-gcs-repository.md @@ -0,0 +1,62 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-gcp-snapshotting.html +--- + +# Google Cloud Storage (GCS) repository [ece-configure-gcp-snapshotting] + +Snapshots to GCS are supported using an [advanced repository configuration](cloud-enterprise.md#ece-manage-repositories-add) and service account credentials that can administer your GCS bucket. + + +## Set up your service account credentials [ece_set_up_your_service_account_credentials] + +You’ll need to have an existing Google Cloud account and have the appropriate permissions to generate credentials: + +1. Create [service account credentials](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) in your Google Cloud project where Elastic Cloud Enterprise is running. + + The service account should be [granted the role of `storage.admin`](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts) so that Elasticsearch clusters can read, write, and list the bucket objects. + +2. Save the service account key in JSON file format. You are going to use it later to configure your Elasticsearch deployment for snapshotting. + + +## Add the GCS repository [ece_add_the_gcs_repository] + +Add your Google Cloud Storage bucket as a repository to the platform: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Platform > Repositories** and add the following snapshot repository configuration under the advanced mode: + + Repository GCS (check: [supported settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html#repository-gcs-repository)) + + ```json + { + "type": "gcs", + "settings": { + "bucket": "acme-snapshot-repo", + "bucket": "acme-snapshots" + } + } + ``` + + +Snapshots are stored in the bucket you provide. Use the repository name you define here to configure your Elasticsearch clusters for snapshotting to this repository. + + +## Configure your deployment for GCS snapshots [ece_configure_your_deployment_for_gcs_snapshots] + +To save deployment snapshots to the custom GCS repository: + +1. Add a [secure setting](../../security/secure-settings.md) named `gcs.client.acme-snapshots.credentials_file` as a JSON block. Make sure that the client name is the same one you provided when configuring the snapshot repository. + + :::{image} ../../../images/cloud-enterprise-ece-secure-settings.png + :alt: GCS client secret configuration + ::: + + ::::{note} + The contents within *credentials_file* must be the exact contents of your GCS credentials file. + :::: + +2. Configure your deployment to [snapshot to the GCS repository](cloud-enterprise.md). + +After you enable snapshots, snapshotting will begin within 30 minutes (the default snapshot interval). + diff --git a/deploy-manage/tools/snapshot-and-restore/google-cloud-storage-repository.md b/deploy-manage/tools/snapshot-and-restore/google-cloud-storage-repository.md new file mode 100644 index 000000000..eb2afdd9a --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/google-cloud-storage-repository.md @@ -0,0 +1,229 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html +--- + +# Google Cloud Storage repository [repository-gcs] + +You can use the [Google Cloud Storage](https://cloud.google.com/storage/) service as a repository for [Snapshot/Restore](../snapshot-and-restore.md). + +## Getting started [repository-gcs-usage] + +This repository type uses the [Google Cloud Java Client for Storage](https://github.com/GoogleCloudPlatform/google-cloud-java/tree/master/google-cloud-clients/google-cloud-storage) to connect to the Storage service. If you are using [Google Cloud Storage](https://cloud.google.com/storage/) for the first time, you must connect to the [Google Cloud Platform Console](https://console.cloud.google.com/) and create a new project. After your project is created, you must enable the Cloud Storage Service for your project. + +### Creating a bucket [repository-gcs-creating-bucket] + +The Google Cloud Storage service uses the concept of a [bucket](https://cloud.google.com/storage/docs/key-terms) as a container for all the data. Buckets are usually created using the [Google Cloud Platform Console](https://console.cloud.google.com/). This repository type does not automatically create buckets. + +To create a new bucket: + +1. Connect to the [Google Cloud Platform Console](https://console.cloud.google.com/). +2. Select your project. +3. Go to the [Storage Browser](https://console.cloud.google.com/storage/browser). +4. Click the **Create Bucket** button. +5. Enter the name of the new bucket. +6. Select a storage class. +7. Select a location. +8. Click the **Create** button. + +For more detailed instructions, see the [Google Cloud documentation](https://cloud.google.com/storage/docs/quickstart-console#create_a_bucket). + + +### Service authentication [repository-gcs-service-authentication] + +The repository must authenticate the requests it makes to the Google Cloud Storage service. It is common for Google client libraries to employ a strategy named [application default credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application). However, that strategy is only **partially supported** by Elasticsearch. The repository operates under the Elasticsearch process, which runs with the security manager enabled. The security manager obstructs the "automatic" credential discovery when the environment variable `GOOGLE_APPLICATION_CREDENTIALS` is used to point to a local file on disk. It can, however, retrieve the service account that is attached to the resource that is running Elasticsearch, or fall back to the default service account that Compute Engine, Kubernetes Engine or App Engine provide. Alternatively, you must configure [service account](#repository-gcs-using-service-account) credentials if you are using an environment that does not support automatic credential discovery. + + +### Using a service account [repository-gcs-using-service-account] + +You have to obtain and provide [service account credentials](https://cloud.google.com/iam/docs/overview#service_account) manually. + +For detailed information about generating JSON service account files, see the [Google Cloud documentation](https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts). Note that the PKCS12 format is not supported by this repository type. + +Here is a summary of the steps: + +1. Connect to the [Google Cloud Platform Console](https://console.cloud.google.com/). +2. Select your project. +3. Select the [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) tab. +4. Click **Create service account**. +5. After the account is created, select it and go to **Keys**. +6. Select **Add Key** and then **Create new key**. +7. Select Key Type **JSON** as P12 is unsupported. + +A JSON service account file looks like this: + +```js +{ + "type": "service_account", + "project_id": "your-project-id", + "private_key_id": "...", + "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", + "client_email": "service-account-for-your-repository@your-project-id.iam.gserviceaccount.com", + "client_id": "...", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://accounts.google.com/o/oauth2/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-bucket@your-project-id.iam.gserviceaccount.com" +} +``` + +To provide this file to the repository, it must be stored in the [Elasticsearch keystore](../../security/secure-settings.md). You must add a `file` setting with the name `gcs.client.NAME.credentials_file` using the `add-file` subcommand. `NAME` is the name of the client configuration for the repository. The implicit client name is `default`, but a different client name can be specified in the repository settings with the `client` key. + +::::{note} +Passing the file path via the GOOGLE_APPLICATION_CREDENTIALS environment variable is **not** supported. +:::: + + +For example, if you added a `gcs.client.my_alternate_client.credentials_file` setting in the keystore, you can configure a repository to use those credentials like this: + +```console +PUT _snapshot/my_gcs_repository +{ + "type": "gcs", + "settings": { + "bucket": "my_bucket", + "client": "my_alternate_client" + } +} +``` + +The `credentials_file` settings are [reloadable](../../security/secure-settings.md#reloadable-secure-settings). You can define these settings before the node is started, or call the [Nodes reload secure settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) after the settings are defined to apply them to a running node. + +After you reload the settings, the internal `gcs` clients, which are used to transfer the snapshot contents, utilize the latest settings from the keystore. + +::::{note} +Snapshot or restore jobs that are in progress are not preempted by a **reload** of the client’s `credentials_file` settings. They complete using the client as it was built when the operation started. +:::: + + + + +## Client settings [repository-gcs-client] + +The client used to connect to Google Cloud Storage has a number of settings available. Client setting names are of the form `gcs.client.CLIENT_NAME.SETTING_NAME` and are specified inside `elasticsearch.yml`. The default client name looked up by a `gcs` repository is called `default`, but can be customized with the repository setting `client`. + +For example: + +```console +PUT _snapshot/my_gcs_repository +{ + "type": "gcs", + "settings": { + "bucket": "my_bucket", + "client": "my_alternate_client" + } +} +``` + +Some settings are sensitive and must be stored in the [Elasticsearch keystore](../../security/secure-settings.md). This is the case for the service account file: + +```sh +bin/elasticsearch-keystore add-file gcs.client.default.credentials_file /path/service-account.json +``` + +The following are the available client settings. Those that must be stored in the keystore are marked as `Secure`. + +`credentials_file` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: The service account file that is used to authenticate to the Google Cloud Storage service. + +`endpoint` +: The Google Cloud Storage service endpoint to connect to. This will be automatically determined by the Google Cloud Storage client but can be specified explicitly. + +`connect_timeout` +: The timeout to establish a connection to the Google Cloud Storage service. The value should specify the unit. For example, a value of `5s` specifies a 5 second timeout. The value of `-1` corresponds to an infinite timeout. The default value is 20 seconds. + +`read_timeout` +: The timeout to read data from an established connection. The value should specify the unit. For example, a value of `5s` specifies a 5 second timeout. The value of `-1` corresponds to an infinite timeout. The default value is 20 seconds. + +`application_name` +: Name used by the client when it uses the Google Cloud Storage service. Setting a custom name can be useful to authenticate your cluster when requests statistics are logged in the Google Cloud Platform. Default to `repository-gcs` + +`project_id` +: The Google Cloud project id. This will be automatically inferred from the credentials file but can be specified explicitly. For example, it can be used to switch between projects when the same credentials are usable for both the production and the development projects. + +`proxy.host` +: Host name of a proxy to connect to the Google Cloud Storage through. + +`proxy.port` +: Port of a proxy to connect to the Google Cloud Storage through. + +`proxy.type` +: Proxy type for the client. Supported values are `direct` (no proxy), `http`, and `socks`. Defaults to `direct`. + + +## Repository settings [repository-gcs-repository] + +The `gcs` repository type supports a number of settings to customize how data is stored in Google Cloud Storage. + +These can be specified when creating the repository. For example: + +```console +PUT _snapshot/my_gcs_repository +{ + "type": "gcs", + "settings": { + "bucket": "my_other_bucket", + "base_path": "dev" + } +} +``` + +The following settings are supported: + +`bucket` +: The name of the bucket to be used for snapshots. (Mandatory) + +`client` +: The name of the client to use to connect to Google Cloud Storage. Defaults to `default`. + +`base_path` +: Specifies the path within bucket to repository data. Defaults to the root of the bucket. + + ::::{note} + Don’t set `base_path` when configuring a snapshot repository for {{ECE}}. {{ECE}} automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket. + :::: + + +`chunk_size` +: Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the Google Cloud Storage Service during snapshot create as well as restore operations compared to using the default value and thus make both operations slower as well as more costly. Specify the chunk size as a value and unit, for example: `10MB`, `5KB`, `500B`. Defaults to the maximum size of a blob in the Google Cloud Storage Service which is `5TB`. + +`compress` +: When set to `true` metadata files are stored in compressed format. This setting doesn’t affect index files that are already compressed by default. Defaults to `true`. + +`max_restore_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`max_snapshot_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot creation rate per node. Defaults to `40mb` per second. Note that if the [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services) are set, then it defaults to unlimited, and the rate is additionally throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`readonly` +: (Optional, Boolean) If `true`, the repository is read-only. The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + + Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the `readonly` parameter set to `true`. + + If `false`, the cluster can write to the repository and create snapshots in it. Defaults to `false`. + + ::::{important} + If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + + :::: + + +`application_name` +: [6.3.0] Name used by the client when it uses the Google Cloud Storage service. + +### Recommended bucket permission [repository-gcs-bucket-permission] + +The service account used to access the bucket must have the "Writer" access to the bucket: + +1. Connect to the [Google Cloud Platform Console](https://console.cloud.google.com/). +2. Select your project. +3. Go to the [Storage Browser](https://console.cloud.google.com/storage/browser). +4. Select the bucket and "Edit bucket permission". +5. The service account must be configured as a "User" with "Writer" access. + + + +## Linearizable register implementation [repository-gcs-linearizable-registers] + +The linearizable register implementation for GCS repositories is based on GCS’s support for strongly consistent preconditions on put-blob operations. To perform a compare-and-exchange operation on a register, {{es}} retrieves the register blob and its current generation, and then uploads the updated blob using the observed generation as its precondition. The precondition ensures that the generation has not changed in the meantime. diff --git a/deploy-manage/tools/snapshot-and-restore/manage-snapshot-repositories.md b/deploy-manage/tools/snapshot-and-restore/manage-snapshot-repositories.md new file mode 100644 index 000000000..fa4c3e669 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/manage-snapshot-repositories.md @@ -0,0 +1,7 @@ +# Manage snapshot repositories + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/343 + +% Scope notes: Landing page for this containing links for Cloud and ECE \ No newline at end of file diff --git a/deploy-manage/tools/snapshot-and-restore/minio-on-premise-repository.md b/deploy-manage/tools/snapshot-and-restore/minio-on-premise-repository.md new file mode 100644 index 000000000..de92dbe89 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/minio-on-premise-repository.md @@ -0,0 +1,167 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configuring-minio.html +--- + +# Minio on-premise repository [ece-configuring-minio] + +Minio is a popular, open-source distributed object storage server compatible with the Amazon AWS S3 API. You can use it with Elastic Cloud Enterprise installations when you want to store your Elasticsearch snapshots locally. + + +## Create a test environment [ece-minio-test] + +We recommend following the [Minio Quickstart Guide Docker Container instructions](https://docs.minio.io/docs/minio-docker-quickstart-guide) to create a simple Minio standalone installation for your initial evaluation and development. + +Be sure to use the `docker -v` option to map persistent storage to the container. + + +## Production environment prerequisites [ece-minio-requirements] + +Installing Minio for production requires a high-availability configuration where Minio is running in [Distributed mode](https://docs.minio.io/docs/distributed-minio-quickstart-guide). + +As mentioned in the Minio documentation, you will need to have 4-16 Minio drive mounts. There is no hard limit on the number of Minio nodes. It might be convenient to place the Minio node containers on your ECE hosts to ensure you have a suitable level of availability, but those can not be located on the same hosts as ECE proxies since they both listen on the same port. + +The following illustration is a sample architecture for a [large ECE installation](../../deploy/cloud-enterprise/deploy-large-installation-onprem.md). Note that there is at least one MinIO container in *each* availability zone. + +There are a number of different ways of orchestrating the Minio deployment (Docker Compose, Kubernetes, and so on). We suggest you use the method most familiar to you. + +We recommend: + +* Using a single Minio endpoint with the Elastic Cloud Enterprise installation, to simplify repository management. +* Securing access to the Minio endpoint with TLS. + +:::{image} ../../../images/cloud-enterprise-ece-minio-large-arch.png +:alt: Architecture diagram +:name: img-ece-minio-large-arch +::: + + +## Create an offline installation [ece-minio-offline-installation] + +If you are installing MinIO offline, the process is very similar to the [offline installation of Elastic Cloud Enterprise](../../deploy/cloud-enterprise/air-gapped-install.md). There are two options: + +* Use a private Docker repository and [install the Minio images in the private repository](https://docs.docker.com/registry/deploying/). +* Download the Minio images from an internet-connected machine, then use docker save to bundle the images into tar files. Copy the TAR files to the target hosts and use `docker load` to install. + +Gather the following after your installation: + +* Minio AccessKey +* Minio SecretKey +* Endpoint URL + +::::{tip} +Minio might report various Endpoint URLs, be sure to choose the one that will be routable from your Elasticsearch Docker containers. +:::: + + + +## Create the S3 bucket [ece-minio-create-s3-bucket] + +How you create the AWS S3 bucket depends on what version of Elasticsearch you are using: + +* For version 7.x: + + 1. Using the Minio browser or an S3 client application, create an S3 bucket to store your snapshots. + 2. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md) and [add the S3 repository plugin](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-add-plugins.html) to your cluster. + +* For versions 8.0 and later, {{es}} has built-in support for AWS S3 repositories; no repository plugin is needed. Use the Minio browser or an S3 client application to create an S3 bucket to store your snapshots. + +::::{tip} +Don’t forget to make the bucket name DNS-friendly, for example no underscores or uppercase letters. For more details, read the [bucket restrictions](https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.md). +:::: + + + +## Elastic Cloud Enterprise configuration [ece-install-with-minio] + +You can configure existing deployments, or create new ones, with the following changes to use Minio storage. + + +### Add the repository to Elastic Cloud Enterprise [ece-add-repository] + +You must add the new repository to Elastic Cloud Enterprise before it can be used with your Elasticsearch clusters. + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. From the **Platform** menu, select **Repositories**. +3. Select **Add Repository**. +4. From the **Repository Type** drop-down list, select **Advanced**. +5. In the **Configuration** text area, provide the repository JSON. You must specify the bucket, access_key, secret_key, endpoint, and protocol. + + ```json + { + "type": "s3", + "settings": { + "bucket": "ece-backup", + "access_key": "", + "secret_key": "", + "endpoint": ":9000", + "path_style_access": "true", + "protocol": "http" + } + } + ``` + + :::{image} ../../../images/cloud-enterprise-ece-minio-repository.png + :alt: Create form + :name: img-ece-minio-repository + ::: + +6. Select **Save** to submit your configuration. + +The Minio repository is now available from the drop-down list of repositories when creating deployments. + +:::{image} ../../../images/cloud-enterprise-ece-minio-deployment.png +:alt: Create deployment +:name: img-ece-minio-deployment +::: + + +### Additional settings for 6.x clusters [ece-6.x-settings] + +For Elasticsearch versions 6.0 and later, after selecting the repository, you also need to set your **User Settings** YAML to specify the endpoint and protocol. For example: + +``` +s3.client.default.endpoint: ":9000" +s3.client.default.protocol: http +``` +Check the [Elasticsearch S3 plugin details](https://www.elastic.co/guide/en/elasticsearch/plugins/6.8/repository-s3-client.html) for more information. + + +## Upgrade from 5.x to 6.x Elasticsearch clusters [ece-upgrade-minio] + +The configuration options for the Elasticsearch S3 repository plugin have changed from 5.x to 6.x versions and you must copy the endpoint and protocol values from your repository configuration to your **User Settings** YAML before you upgrade. + + +## Verify snapshots [ece-minio-verify-snapshot] + +The cluster should make a snapshot when the repository is set up. You can check that by going to the **Elasticsearch** and then the **Snapshots** page. + +As an extra verification step, you can restore a cluster using the snapshots that have been taken. + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Get the plan from your test cluster. + + 1. From the **Deployments** page, select your deployment. + + Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters. + + 2. From your deployment menu, go to the **Edit** page then go to the bottom of the page and select **advanced Elasticsearch configuration**. + 3. Copy the JSON format under the **Deployment configuration** heading. + +3. Create a new Elasticsearch cluster as your target. +4. On the new cluster, open the advanced cluster configuration editor. In the transient section, add the `restore_snapshot` settings to the plan. + + ```json + ... + "transient": { + "restore_snapshot": { + "repository_name": "", + "snapshot_name": "latest_success" + } + } + ``` + +5. Select **Save** to restore from the snapshot. When the plan update is complete, you can check the restored indexes in your target cluster. + +More details are available to [work with snapshots](../snapshot-and-restore.md). + diff --git a/deploy-manage/tools/snapshot-and-restore/read-only-url-repository.md b/deploy-manage/tools/snapshot-and-restore/read-only-url-repository.md new file mode 100644 index 000000000..0d2c35e44 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/read-only-url-repository.md @@ -0,0 +1,64 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-read-only-repository.html +--- + +# Read-only URL repository [snapshots-read-only-repository] + +::::{note} +This repository type is only available if you run {{es}} on your own hardware. If you use {{ess}}, see [{{ess}} repository types](self-managed.md#ess-repo-types). +:::: + + +You can use a URL repository to give a cluster read-only access to a shared file system. Since URL repositories are always read-only, they’re a safer and more convenient alternative to registering a read-only shared filesystem repository. + +Use {{kib}} or the [create snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html) to register a URL repository. + +```console +PUT _snapshot/my_read_only_url_repository +{ + "type": "url", + "settings": { + "url": "file:/mount/backups/my_fs_backup_location" + } +} +``` + +## Repository settings [read-only-url-repository-settings] + +`chunk_size` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum size of files in snapshots. In snapshots, files larger than this are broken down into chunks of this size or smaller. Defaults to `null` (unlimited file size). + +`http_max_retries` +: (Optional, integer) Maximum number of retries for `http` and `https` URLs. Defaults to `5`. + +`http_socket_timeout` +: (Optional, [time value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units)) Maximum wait time for data transfers over a connection. Defaults to `50s`. + +`compress` +: (Optional, Boolean) If `true`, metadata files, such as index mappings and settings, are compressed in snapshots. Data files are not compressed. Defaults to `true`. + +`max_number_of_snapshots` +: (Optional, integer) Maximum number of snapshots the repository can contain. Defaults to `Integer.MAX_VALUE`, which is `2^31-1` or `2147483647`. + +`max_restore_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`max_snapshot_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot creation rate per node. Defaults to `40mb` per second. Note that if the [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services) are set, then it defaults to unlimited, and the rate is additionally throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`url` +: (Required, string) URL location of the root of the shared filesystem repository. The following protocols are supported: + +* `file` +* `ftp` +* `http` +* `https` +* `jar` + +URLs using the `http`, `https`, or `ftp` protocols must be explicitly allowed with the [`repositories.url.allowed_urls`](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-settings.html#repositories-url-allowed) cluster setting. This setting supports wildcards in the place of a host, path, query, or fragment in the URL. + +URLs using the `file` protocol must point to the location of a shared filesystem accessible to all master and data nodes in the cluster. This location must be registered in the `path.repo` setting. You don’t need to register URLs using the `ftp`, `http`, `https`, or `jar` protocols in the `path.repo` setting. + + + diff --git a/deploy-manage/tools/snapshot-and-restore/repository-isolation-on-aws-gcp.md b/deploy-manage/tools/snapshot-and-restore/repository-isolation-on-aws-gcp.md new file mode 100644 index 000000000..9d28773eb --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/repository-isolation-on-aws-gcp.md @@ -0,0 +1,36 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-snapshot-repository-aws-gcp-migration.html +--- + +# Repository isolation on AWS and GCP [ec-snapshot-repository-aws-gcp-migration] + +::::{note} +This configuration is automatic for all newly created deployments, but may be necessary for some existing deployments you have. If a deployment is not yet using an isolated snapshot repository, a notification will show up in the deployments menu under **Elasticsearch** > **Snapshots**. +:::: + + +Deployments of your organization in the same region currently may have access to each other’s snapshots via the Elastic provided `found-snapshots` repository. For improved security between deployments, each deployment should only have access to its own snapshots. + +If a deployment can still access the snapshots of other deployments, a notification will show up in the deployments menu under **Elasticsearch** > **Snapshots**. After applying the action, the notification will disappear. + + +## Removing a repository of another deployment [ec_removing_a_repository_of_another_deployment] + +The deployment may have access to other deployments if it has been restored from a snapshot. If this is the case, the access permissions will be listed under **Elasticsearch** > **Snapshots** under the title **Snapshot repositories of other deployments**. + +If you no longer need access to the snapshot of another deployment, you can remove the access. By doing this, you prevent accessing snapshots of other deployments from this deployment: + +1. From your deployment menu, go to **Elasticsearch** > **Snapshots**. +2. On the **Snapshots** page, **Snapshot repositories of other deployments** shows the old repository. +3. With **Remove Access**, the snapshot repository will be removed. + +::::{note} +If the repository is still in use (for example by mounted searchable snapshots), it can’t be removed. Please first remove any indices stored in this repository. +:::: + + +:::{image} ../../../images/cloud-ec-elasticsearch-snapshots-of-other-deployments-aws-gcp.png +:alt: View of the old snapshot repository in the Cloud UI +::: + diff --git a/deploy-manage/tools/snapshot-and-restore/repository-isolation-on-azure.md b/deploy-manage/tools/snapshot-and-restore/repository-isolation-on-azure.md new file mode 100644 index 000000000..e8046149c --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/repository-isolation-on-azure.md @@ -0,0 +1,43 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-snapshot-repository-azure-migration.html +--- + +# Repository isolation on Azure [ec-snapshot-repository-azure-migration] + +::::{note} +This configuration is automatic for all newly created deployments, but may have to be triggered manually on any existing Azure deployments you have. If a deployment can be moved to a dedicated repository, a notification will show up in the deployments menu under **Elasticsearch** > **Snapshots**. +:::: + + +Azure deployments of your organization in the same region currently may use the same Azure Blob storage container as shared repository to store their snapshots. To make sure that no other deployment can have access to this deployment’s snapshots, you can instead use a dedicated repository for this deployment. + +When enabling a dedicated repository for storing snapshots, a configuration change triggers for your deployment and: + +* Renames the existing `found-snapshots` repository to `\_clone_`. In this repository, all existing snapshots and searchable snapshots can still be accessed. +* Adds a new (empty) `found-snapshots` repository using a new container. +* Takes a full snapshot in this new `found-snapshots` repository. + + +## Restoring from a snapshot created before the migration [ec_restoring_from_a_snapshot_created_before_the_migration] + +The snapshots are still available and can be restored just like snapshots in `found-snapshots`. You can find more information in [Snapshot and restore](../snapshot-and-restore.md). + + +## Removing the old repository [ec_removing_the_old_repository] + +If you no longer need the old snapshots, you can remove the repository. By doing this, you also prevent accessing snapshots of other deployments from this deployment: + +1. From your deployment menu, go to **Elasticsearch** > **Snapshots**. +2. On the **Snapshots** page, **Snapshot repositories of other deployments** shows the old repository. +3. With **Remove Access**, the snapshot repository will be removed. + +::::{note} +If the repository is still in use (for example by mounted searchable snapshots), it can’t be removed. Please first remove any indices stored in this repository. +:::: + + +:::{image} ../../../images/cloud-ec-elasticsearch-snapshots-of-other-deployments.png +:alt: View of the old snapshot repository in the Cloud UI +::: + diff --git a/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md b/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md new file mode 100644 index 000000000..fe2ba8996 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md @@ -0,0 +1,35 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-restore-snapshot.html + - https://www.elastic.co/guide/en/cloud/current/ec-restore-across-clusters.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restore-across-clusters.html +--- + +# Restore a snapshot + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/343 + +% Scope notes: Merge the articles, highlight the differences for the deployment types. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/snapshots-restore-snapshot.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-restore-across-clusters.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-restore-across-clusters.md +% Notes: 3 children + +$$$delete-restore$$$ + +$$$rename-on-restore$$$ + +$$$restore-create-file-realm-user$$$ + +$$$restore-different-cluster$$$ + +$$$restore-entire-cluster$$$ + +$$$restore-index-data-stream$$$ + +$$$troubleshoot-restore$$$ \ No newline at end of file diff --git a/deploy-manage/tools/snapshot-and-restore/s3-repository.md b/deploy-manage/tools/snapshot-and-restore/s3-repository.md new file mode 100644 index 000000000..6a4fbccdc --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/s3-repository.md @@ -0,0 +1,408 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-s3.html +--- + +# S3 repository [repository-s3] + +You can use AWS S3 as a repository for [Snapshot/Restore](../snapshot-and-restore.md). + +**If you are looking for a hosted solution of Elasticsearch on AWS, please visit [https://www.elastic.co/cloud/.**](https://www.elastic.co/cloud/.**) + +See [this video](https://www.youtube.com/watch?v=ACqfyzWf-xs) for a walkthrough of connecting an AWS S3 repository. + +## Getting started [repository-s3-usage] + +To register an S3 repository, specify the type as `s3` when creating the repository. The repository defaults to using [ECS IAM Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.md) credentials for authentication. You can also use [Kubernetes service accounts](#iam-kubernetes-service-accounts) for authentication. + +The only mandatory setting is the bucket name: + +```console +PUT _snapshot/my_s3_repository +{ + "type": "s3", + "settings": { + "bucket": "my-bucket" + } +} +``` + + +## Client settings [repository-s3-client] + +The client that you use to connect to S3 has a number of settings available. The settings have the form `s3.client.CLIENT_NAME.SETTING_NAME`. By default, `s3` repositories use a client named `default`, but this can be modified using the [repository setting](#repository-s3-repository) `client`. For example, to use a client named `my-alternate-client`, register the repository as follows: + +```console +PUT _snapshot/my_s3_repository +{ + "type": "s3", + "settings": { + "bucket": "my-bucket", + "client": "my-alternate-client" + } +} +``` + +Most client settings can be added to the `elasticsearch.yml` configuration file with the exception of the secure settings, which you add to the {{es}} keystore. For more information about creating and updating the {{es}} keystore, see [Secure settings](../../security/secure-settings.md). + +For example, if you want to use specific credentials to access S3 then run the following commands to add these credentials to the keystore. + +```sh +bin/elasticsearch-keystore add s3.client.default.access_key +bin/elasticsearch-keystore add s3.client.default.secret_key +# a session token is optional so the following command may not be needed +bin/elasticsearch-keystore add s3.client.default.session_token +``` + +If you do not configure these settings then {{es}} will attempt to automatically obtain credentials from the environment in which it is running: + +* Nodes running on an instance in AWS EC2 will attempt to use the EC2 Instance Metadata Service (IMDS) to obtain instance role credentials. {{es}} supports both IMDS version 1 and IMDS version 2. +* Nodes running in a container in AWS ECS and AWS EKS will attempt to obtain container role credentials similarly. + +You can switch from using specific credentials back to the default of using the instance role or container role by removing these settings from the keystore as follows: + +```sh +bin/elasticsearch-keystore remove s3.client.default.access_key +bin/elasticsearch-keystore remove s3.client.default.secret_key +# a session token is optional so the following command may not be needed +bin/elasticsearch-keystore remove s3.client.default.session_token +``` + +Define the relevant secure settings in each node’s keystore before starting the node. The secure settings described here are all [reloadable](../../security/secure-settings.md#reloadable-secure-settings) so you may update the keystore contents on each node while the node is running and then call the [Nodes reload secure settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-reload-secure-settings.html) to apply the updated settings to the nodes in the cluster. After this API completes, {{es}} will use the updated setting values for all future snapshot operations, but ongoing operations may continue to use older setting values. + +The following list contains the available client settings. Those that must be stored in the keystore are marked as "secure" and are **reloadable**; the other settings belong in the `elasticsearch.yml` file. + +`access_key` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: An S3 access key. If set, the `secret_key` setting must also be specified. If unset, the client will use the instance or container role instead. + +`secret_key` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: An S3 secret key. If set, the `access_key` setting must also be specified. + +`session_token` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: An S3 session token. If set, the `access_key` and `secret_key` settings must also be specified. + +`endpoint` +: The S3 service endpoint to connect to. This defaults to `s3.amazonaws.com` but the [AWS documentation](https://docs.aws.amazon.com/general/latest/gr/rande.md#s3_region) lists alternative S3 endpoints. If you are using an [S3-compatible service](#repository-s3-compatible-services) then you should set this to the service’s endpoint. + +`protocol` +: The protocol to use to connect to S3. Valid values are either `http` or `https`. Defaults to `https`. When using HTTPS, this repository type validates the repository’s certificate chain using the JVM-wide truststore. Ensure that the root certificate authority is in this truststore using the JVM’s `keytool` tool. If you have a custom certificate authority for your S3 repository and you use the {{es}} [bundled JDK](../../deploy/self-managed/installing-elasticsearch.md#jvm-version), then you will need to reinstall your CA certificate every time you upgrade {{es}}. + +`proxy.host` +: The host name of a proxy to connect to S3 through. + +`proxy.port` +: The port of a proxy to connect to S3 through. + +`proxy.scheme` +: The scheme to use for the proxy connection to S3. Valid values are either `http` or `https`. Defaults to `http`. This setting allows to specify the protocol used for communication with the proxy server + +`proxy.username` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: The username to connect to the `proxy.host` with. + +`proxy.password` ({{ref}}/secure-settings.html[Secure], [reloadable](../../security/secure-settings.md#reloadable-secure-settings)) +: The password to connect to the `proxy.host` with. + +`read_timeout` +: ([time value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units)) The maximum time {{es}} will wait to receive the next byte of data over an established, open connection to the repository before it closes the connection. The default value is 50 seconds. + +`max_connections` +: The maximum number of concurrent connections to S3. The default value is `50`. + +`max_retries` +: The number of retries to use when an S3 request fails. The default value is `3`. + +`use_throttle_retries` +: Whether retries should be throttled (i.e. should back off). Must be `true` or `false`. Defaults to `true`. + +`path_style_access` +: Whether to force the use of the path style access pattern. If `true`, the path style access pattern will be used. If `false`, the access pattern will be automatically determined by the AWS Java SDK (See [AWS documentation](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3Builder.md#setPathStyleAccessEnabled-java.lang.Boolean-) for details). Defaults to `false`. + +::::{note} +:name: repository-s3-path-style-deprecation + +In versions `7.0`, `7.1`, `7.2` and `7.3` all bucket operations used the [now-deprecated](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/) path style access pattern. If your deployment requires the path style access pattern then you should set this setting to `true` when upgrading. +:::: + + +`disable_chunked_encoding` +: Whether chunked encoding should be disabled or not. If `false`, chunked encoding is enabled and will be used where appropriate. If `true`, chunked encoding is disabled and will not be used, which may mean that snapshot operations consume more resources and take longer to complete. It should only be set to `true` if you are using a storage service that does not support chunked encoding. See the [AWS Java SDK documentation](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3Builder.md#disableChunkedEncoding--) for details. Defaults to `false`. + +`region` +: Allows specifying the signing region to use. Specificing this setting manually should not be necessary for most use cases. Generally, the SDK will correctly guess the signing region to use. It should be considered an expert level setting to support S3-compatible APIs that require [v4 signatures](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.md) and use a region other than the default `us-east-1`. Defaults to empty string which means that the SDK will try to automatically determine the correct signing region. + +`signer_override` +: Allows specifying the name of the signature algorithm to use for signing requests by the S3 client. Specifying this setting should not be necessary for most use cases. It should be considered an expert level setting to support S3-compatible APIs that do not support the signing algorithm that the SDK automatically determines for them. See the [AWS Java SDK documentation](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/ClientConfiguration.md#setSignerOverride-java.lang.String-) for details. Defaults to empty string which means that no signing algorithm override will be used. + + +## Repository settings [repository-s3-repository] + +The `s3` repository type supports a number of settings to customize how data is stored in S3. These can be specified when creating the repository. For example: + +```console +PUT _snapshot/my_s3_repository +{ + "type": "s3", + "settings": { + "bucket": "my-bucket", + "another_setting": "setting-value" + } +} +``` + +The following settings are supported: + +`bucket` +: (Required) Name of the S3 bucket to use for snapshots. + + The bucket name must adhere to Amazon’s [S3 bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.md#bucketnamingrules). + + +`client` +: The name of the [S3 client](#repository-s3-client) to use to connect to S3. Defaults to `default`. + +`base_path` +: Specifies the path to the repository data within its bucket. Defaults to an empty string, meaning that the repository is at the root of the bucket. The value of this setting should not start or end with a `/`. + + ::::{note} + Don’t set `base_path` when configuring a snapshot repository for {{ECE}}. {{ECE}} automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket. + :::: + + +`chunk_size` +: ([byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) The maximum size of object that {{es}} will write to the repository when creating a snapshot. Files which are larger than `chunk_size` will be chunked into several smaller objects. {{es}} may also split a file across multiple objects to satisfy other constraints such as the `max_multipart_parts` limit. Defaults to `5TB` which is the [maximum size of an object in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.md). + +`compress` +: When set to `true` metadata files are stored in compressed format. This setting doesn’t affect index files that are already compressed by default. Defaults to `true`. + +`max_restore_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`max_snapshot_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot creation rate per node. Defaults to `40mb` per second. Note that if the [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services) are set, then it defaults to unlimited, and the rate is additionally throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`readonly` +: (Optional, Boolean) If `true`, the repository is read-only. The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + + Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the `readonly` parameter set to `true`. + + If `false`, the cluster can write to the repository and create snapshots in it. Defaults to `false`. + + ::::{important} + If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + + :::: + + +`server_side_encryption` +: When set to `true` files are encrypted on server side using AES256 algorithm. Defaults to `false`. + +`buffer_size` +: ([byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Minimum threshold below which the chunk is uploaded using a single request. Beyond this threshold, the S3 repository will use the [AWS Multipart Upload API](https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.md) to split the chunk into several parts, each of `buffer_size` length, and to upload each part in its own request. Note that setting a buffer size lower than `5mb` is not allowed since it will prevent the use of the Multipart API and may result in upload errors. It is also not possible to set a buffer size greater than `5gb` as it is the maximum upload size allowed by S3. Defaults to `100mb` or `5%` of JVM heap, whichever is smaller. + +`max_multipart_parts` +: (integer) The maximum number of parts that {{es}} will write during a multipart upload of a single object. Files which are larger than `buffer_size × max_multipart_parts` will be chunked into several smaller objects. {{es}} may also split a file across multiple objects to satisfy other constraints such as the `chunk_size` limit. Defaults to `10000` which is the [maximum number of parts in a multipart upload in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.md). + +`canned_acl` +: The S3 repository supports all [S3 canned ACLs](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.md#canned-acl) : `private`, `public-read`, `public-read-write`, `authenticated-read`, `log-delivery-write`, `bucket-owner-read`, `bucket-owner-full-control`. Defaults to `private`. You could specify a canned ACL using the `canned_acl` setting. When the S3 repository creates buckets and objects, it adds the canned ACL into the buckets and objects. + +`storage_class` +: Sets the S3 storage class for objects written to the repository. Values may be `standard`, `reduced_redundancy`, `standard_ia`, `onezone_ia` and `intelligent_tiering`. Defaults to `standard`. See [S3 storage classes](#repository-s3-storage-classes) for more information. + +`delete_objects_max_size` +: (integer) Sets the maxmimum batch size, betewen 1 and 1000, used for `DeleteObjects` requests. Defaults to 1000 which is the maximum number supported by the [AWS DeleteObjects API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.md). + +`max_multipart_upload_cleanup_size` +: (integer) Sets the maximum number of possibly-dangling multipart uploads to clean up in each batch of snapshot deletions. Defaults to `1000` which is the maximum number supported by the [AWS ListMultipartUploads API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.md). If set to `0`, {{es}} will not attempt to clean up dangling multipart uploads. + +`throttled_delete_retry.delay_increment` +: ([time value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units)) This value is used as the delay before the first retry and the amount the delay is incremented by on each subsequent retry. Default is 50ms, minimum is 0ms. + +`throttled_delete_retry.maximum_delay` +: ([time value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units)) This is the upper bound on how long the delays between retries will grow to. Default is 5s, minimum is 0ms. + +`throttled_delete_retry.maximum_number_of_retries` +: (integer) Sets the number times to retry a throttled snapshot deletion. Defaults to `10`, minimum value is `0` which will disable retries altogether. Note that if retries are enabled in the Azure client, each of these retries comprises that many client-level retries. + +`get_register_retry_delay` +: ([time value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units)) Sets the time to wait before trying again if an attempt to read a [linearizable register](#repository-s3-linearizable-registers) fails. Defaults to `5s`. + +::::{note} +The option of defining client settings in the repository settings as documented below is considered deprecated, and will be removed in a future version. +:::: + + +In addition to the above settings, you may also specify all non-secure client settings in the repository settings. In this case, the client settings found in the repository settings will be merged with those of the named client used by the repository. Conflicts between client and repository settings are resolved by the repository settings taking precedence over client settings. + +For example: + +```console +PUT _snapshot/my_s3_repository +{ + "type": "s3", + "settings": { + "client": "my-client", + "bucket": "my-bucket", + "endpoint": "my.s3.endpoint" + } +} +``` + +This sets up a repository that uses all client settings from the client `my_client_name` except for the `endpoint` that is overridden to `my.s3.endpoint` by the repository settings. ` + + +## S3 storage classes [repository-s3-storage-classes] + +Amazon S3 supports a variety of *storage classes*, each of which offers different operational characteristics. For instance, some classes cost less per byte stored per month, but cost more per request, and other classes may vary in terms of their availability guarantees. + +You may specify the storage class that {{es}} uses to store data objects with the `storage_class` repository setting. + +Changing the `storage_class` setting on an existing repository only affects the storage class for newly created objects, resulting in a mixed usage of storage classes. + +You may use an S3 Lifecycle Policy to adjust the storage class of existing objects in your repository, but you must not transition objects to an unsupported class such as the Glacier classes, and you must not expire objects. If you use a Glacier storage class, or another unsupported storage class, or object expiry, then you may permanently lose access to your repository contents. + +You may use the `intelligent_tiering` storage class to automatically manage the class of objects, but you must not enable the optional Archive Access or Deep Archive Access tiers. If you use these tiers then you may permanently lose access to your repository contents. + +For more information about S3 storage classes, see [AWS Storage Classes Guide](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.md). + + +## Recommended S3 permissions [repository-s3-permissions] + +In order to restrict the Elasticsearch snapshot process to the minimum required resources, we recommend using Amazon IAM in conjunction with pre-existing S3 buckets. Here is an example policy which will allow the snapshot access to an S3 bucket named "snaps.example.com". This may be configured through the AWS IAM console, by creating a Custom Policy, and using a Policy Document similar to this (changing snaps.example.com to your bucket name). + +```js +{ + "Statement": [ + { + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation", + "s3:ListBucketMultipartUploads", + "s3:ListBucketVersions" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::snaps.example.com" + ] + }, + { + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject", + "s3:AbortMultipartUpload", + "s3:ListMultipartUploadParts" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::snaps.example.com/*" + ] + } + ], + "Version": "2012-10-17" +} +``` + +You may further restrict the permissions by specifying a prefix within the bucket, in this example, named "foo". + +```js +{ + "Statement": [ + { + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation", + "s3:ListBucketMultipartUploads", + "s3:ListBucketVersions" + ], + "Condition": { + "StringLike": { + "s3:prefix": [ + "foo/*" + ] + } + }, + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::snaps.example.com" + ] + }, + { + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject", + "s3:AbortMultipartUpload", + "s3:ListMultipartUploadParts" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::snaps.example.com/foo/*" + ] + } + ], + "Version": "2012-10-17" +} +``` + +The bucket needs to exist to register a repository for snapshots. If you did not create the bucket then the repository registration will fail. + + +#### Using IAM roles for Kubernetes service accounts for authentication [iam-kubernetes-service-accounts] + +If you want to use [Kubernetes service accounts](https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/) for authentication, you need to add a symlink to the `$AWS_WEB_IDENTITY_TOKEN_FILE` environment variable (which should be automatically set by a Kubernetes pod) in the S3 repository config directory, so the repository can have the read access for the service account (a repository can’t read any files outside its config directory). For example: + +```bash +mkdir -p "${ES_PATH_CONF}/repository-s3" +ln -s $AWS_WEB_IDENTITY_TOKEN_FILE "${ES_PATH_CONF}/repository-s3/aws-web-identity-token-file" +``` + +::::{important} +The symlink must be created on all data and master eligible nodes and be readable by the `elasticsearch` user. By default, {{es}} runs as user `elasticsearch` using uid:gid `1000:0`. +:::: + + +If the symlink exists, it will be used by default by all S3 repositories that don’t have explicit `client` credentials. + + +## AWS VPC bandwidth settings [repository-s3-aws-vpc] + +AWS instances resolve S3 endpoints to a public IP. If the Elasticsearch instances reside in a private subnet in an AWS VPC then all traffic to S3 will go through the VPC’s NAT instance. If your VPC’s NAT instance is a smaller instance size (e.g. a t2.micro) or is handling a high volume of network traffic your bandwidth to S3 may be limited by that NAT instance’s networking bandwidth limitations. Instead we recommend creating a [VPC endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.md) that enables connecting to S3 in instances that reside in a private subnet in an AWS VPC. This will eliminate any limitations imposed by the network bandwidth of your VPC’s NAT instance. + +Instances residing in a public subnet in an AWS VPC will connect to S3 via the VPC’s internet gateway and not be bandwidth limited by the VPC’s NAT instance. + + +## S3-compatible services [repository-s3-compatible-services] + +There are a number of storage systems that provide an S3-compatible API, and the `s3` repository type allows you to use these systems in place of AWS S3. To do so, you should set the `s3.client.CLIENT_NAME.endpoint` setting to the system’s endpoint. This setting accepts IP addresses and hostnames and may include a port. For example, the endpoint may be `172.17.0.2` or `172.17.0.2:9000`. + +By default {{es}} communicates with your storage system using HTTPS, and validates the repository’s certificate chain using the JVM-wide truststore. Ensure that the JVM-wide truststore includes an entry for your repository. If you wish to use unsecured HTTP communication instead of HTTPS, set `s3.client.CLIENT_NAME.protocol` to `http`. + +[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite. + +There are many systems, including some from very well-known storage vendors, which claim to offer an S3-compatible API despite failing to emulate S3’s behaviour in full. If you are using such a system for your snapshots, consider using a [shared filesystem repository](shared-file-system-repository.md) based on a standardized protocol such as NFS to access your storage system instead. The `s3` repository type requires full compatibility with S3. In particular it must support the same set of API endpoints, with the same parameters, return the same errors in case of failures, and offer consistency and performance at least as good as S3 even when accessed concurrently by multiple nodes. You will need to work with the supplier of your storage system to address any incompatibilities you encounter. Please do not report {{es}} issues involving storage systems which claim to be S3-compatible unless you can demonstrate that the same issue exists when using a genuine AWS S3 repository. + +You can perform some basic checks of the suitability of your storage system using the [repository analysis API](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html). If this API does not complete successfully, or indicates poor performance, then your storage system is not fully compatible with AWS S3 and therefore unsuitable for use as a snapshot repository. However, these checks do not guarantee full compatibility. + +Most storage systems can be configured to log the details of their interaction with {{es}}. If you are investigating a suspected incompatibility with AWS S3, it is usually simplest to collect these logs and provide them to the supplier of your storage system for further analysis. If the incompatibility is not clear from the logs emitted by the storage system, configure {{es}} to log every request it makes to the S3 API by [setting the logging level](../../monitor/logging-configuration/elasticsearch-log4j-configuration-self-managed.md#configuring-logging-levels) of the `com.amazonaws.request` logger to `DEBUG`. + +To prevent leaking sensitive information such as credentials and keys in logs, {{es}} rejects configuring this logger at high verbosity unless [insecure network trace logging](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#http-rest-request-tracer) is enabled. To do so, you must explicitly enable it on each node by setting the system property `es.insecure_network_trace_enabled` to `true`. + +Once enabled, you can configure the `com.amazonaws.request` logger: + +```console +PUT /_cluster/settings +{ + "persistent": { + "logger.com.amazonaws.request": "DEBUG" + } +} +``` + +Collect the Elasticsearch logs covering the time period of the failed analysis from all nodes in your cluster and share them with the supplier of your storage system along with the analysis response so they can use them to determine the problem. See the [AWS Java SDK](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-../../monitor/logging-configuration/elasticsearch-log4j-configuration-self-managed.md) documentation for further information, including details about other loggers that can be used to obtain even more verbose logs. When you have finished collecting the logs needed by your supplier, set the logger settings back to `null` to return to the default logging configuration and disable insecure network trace logging again. See [Logger](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-logger) and [Cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) for more information. + + +## Linearizable register implementation [repository-s3-linearizable-registers] + +The linearizable register implementation for S3 repositories is based on the strongly consistent semantics of the multipart upload API. {{es}} first creates a multipart upload to indicate its intention to perform a linearizable register operation. {{es}} then lists and cancels all other multipart uploads for the same register. {{es}} then attempts to complete the upload. If the upload completes successfully then the compare-and-exchange operation was atomic. + + diff --git a/deploy-manage/tools/snapshot-and-restore/searchable-snapshots.md b/deploy-manage/tools/snapshot-and-restore/searchable-snapshots.md new file mode 100644 index 000000000..7e9aaff71 --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/searchable-snapshots.md @@ -0,0 +1,194 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html +--- + +# Searchable snapshots [searchable-snapshots] + +{{search-snaps-cap}} let you use [snapshots](../snapshot-and-restore.md) to search infrequently accessed and read-only data in a very cost-effective fashion. The [cold](../../../manage-data/lifecycle/data-tiers.md#cold-tier) and [frozen](../../../manage-data/lifecycle/data-tiers.md#frozen-tier) data tiers use {{search-snaps}} to reduce your storage and operating costs. + +{{search-snaps-cap}} eliminate the need for [replica shards](../../../deploy-manage/index.md) after rolling over from the hot tier, potentially halving the local storage needed to search your data. {{search-snaps-cap}} rely on the same snapshot mechanism you already use for backups and have minimal impact on your snapshot repository storage costs. + + +## Using {{search-snaps}} [using-searchable-snapshots] + +Searching a {{search-snap}} index is the same as searching any other index. + +By default, {{search-snap}} indices have no replicas. The underlying snapshot provides resilience and the query volume is expected to be low enough that a single shard copy will be sufficient. However, if you need to support a higher query volume, you can add replicas by adjusting the `index.number_of_replicas` index setting. + +If a node fails and {{search-snap}} shards need to be recovered elsewhere, there is a brief window of time while {{es}} allocates the shards to other nodes where the cluster health will not be `green`. Searches that hit these shards may fail or return partial results until the shards are reallocated to healthy nodes. + +You typically manage {{search-snaps}} through {{ilm-init}}. The [searchable snapshots](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-searchable-snapshot.html) action automatically converts a regular index into a {{search-snap}} index when it reaches the `cold` or `frozen` phase. You can also make indices in existing snapshots searchable by manually mounting them using the [mount snapshot](https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-mount-snapshot.html) API. + +To mount an index from a snapshot that contains multiple indices, we recommend creating a [clone](https://www.elastic.co/guide/en/elasticsearch/reference/current/clone-snapshot-api.html) of the snapshot that contains only the index you want to search, and mounting the clone. You should not delete a snapshot if it has any mounted indices, so creating a clone enables you to manage the lifecycle of the backup snapshot independently of any {{search-snaps}}. If you use {{ilm-init}} to manage your {{search-snaps}} then it will automatically look after cloning the snapshot as needed. + +You can control the allocation of the shards of {{search-snap}} indices using the same mechanisms as for regular indices. For example, you could use [Index-level shard allocation filtering](../../distributed-architecture/shard-allocation-relocation-recovery/index-level-shard-allocation.md) to restrict {{search-snap}} shards to a subset of your nodes. + +The speed of recovery of a {{search-snap}} index is limited by the repository setting `max_restore_bytes_per_sec` and the node setting `indices.recovery.max_bytes_per_sec` just like a normal restore operation. By default `max_restore_bytes_per_sec` is unlimited, but the default for `indices.recovery.max_bytes_per_sec` depends on the configuration of the node. See [Recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings). + +We recommend that you [force-merge](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html) indices to a single segment per shard before taking a snapshot that will be mounted as a {{search-snap}} index. Each read from a snapshot repository takes time and costs money, and the fewer segments there are the fewer reads are needed to restore the snapshot or to respond to a search. + +::::{tip} +{{search-snaps-cap}} are ideal for managing a large archive of historical data. Historical information is typically searched less frequently than recent data and therefore may not need replicas for their performance benefits. + +For more complex or time-consuming searches, you can use [Async search](https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html) with {{search-snaps}}. + +:::: + + +$$$searchable-snapshots-repository-types$$$ +Use any of the following repository types with searchable snapshots: + +* [AWS S3](s3-repository.md) +* [Google Cloud Storage](google-cloud-storage-repository.md) +* [Azure Blob Storage](azure-repository.md) +* [Hadoop Distributed File Store (HDFS)](https://www.elastic.co/guide/en/elasticsearch/plugins/current/repository-hdfs.html) +* [Shared filesystems](shared-file-system-repository.md) such as NFS +* [Read-only HTTP and HTTPS repositories](read-only-url-repository.md) + +You can also use alternative implementations of these repository types, for instance [MinIO](s3-repository.md#repository-s3-client), as long as they are fully compatible. Use the [Repository analysis](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html) API to analyze your repository’s suitability for use with searchable snapshots. + + +## How {{search-snaps}} work [how-searchable-snapshots-work] + +When an index is mounted from a snapshot, {{es}} allocates its shards to data nodes within the cluster. The data nodes then automatically retrieve the relevant shard data from the repository onto local storage, based on the [mount options](#searchable-snapshot-mount-storage-options) specified. If possible, searches use data from local storage. If the data is not available locally, {{es}} downloads the data that it needs from the snapshot repository. + +If a node holding one of these shards fails, {{es}} automatically allocates the affected shards on another node, and that node restores the relevant shard data from the repository. No replicas are needed, and no complicated monitoring or orchestration is necessary to restore lost shards. Although searchable snapshot indices have no replicas by default, you may add replicas to these indices by adjusting `index.number_of_replicas`. Replicas of {{search-snap}} shards are recovered by copying data from the snapshot repository, just like primaries of {{search-snap}} shards. In contrast, replicas of regular indices are restored by copying data from the primary. + + +### Mount options [searchable-snapshot-mount-storage-options] + +To search a snapshot, you must first mount it locally as an index. Usually {{ilm-init}} will do this automatically, but you can also call the [mount snapshot](https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-mount-snapshot.html) API yourself. There are two options for mounting an index from a snapshot, each with different performance characteristics and local storage footprints: + +$$$fully-mounted$$$ + +Fully mounted index +: Fully caches the snapshotted index’s shards in the {{es}} cluster. {{ilm-init}} uses this option in the `hot` and `cold` phases. + + Search performance for a fully mounted index is normally comparable to a regular index, since there is minimal need to access the snapshot repository. While recovery is ongoing, search performance may be slower than with a regular index because a search may need some data that has not yet been retrieved into the local cache. If that happens, {{es}} will eagerly retrieve the data needed to complete the search in parallel with the ongoing recovery. On-disk data is preserved across restarts, such that the node does not need to re-download data that is already stored on the node after a restart. + + Indices managed by {{ilm-init}} are prefixed with `restored-` when fully mounted. + + +$$$partially-mounted$$$ + +Partially mounted index +: Uses a local cache containing only recently searched parts of the snapshotted index’s data. This cache has a fixed size and is shared across shards of partially mounted indices allocated on the same data node. {{ilm-init}} uses this option in the `frozen` phase. + + If a search requires data that is not in the cache, {{es}} fetches the missing data from the snapshot repository. Searches that require these fetches are slower, but the fetched data is stored in the cache so that similar searches can be served more quickly in future. {{es}} will evict infrequently used data from the cache to free up space. The cache is cleared when a node is restarted. + + Although slower than a fully mounted index or a regular index, a partially mounted index still returns search results quickly, even for large data sets, because the layout of data in the repository is heavily optimized for search. Many searches will need to retrieve only a small subset of the total shard data before returning results. + + Indices managed by {{ilm-init}} are prefixed with `partial-` when partially mounted. + + +To partially mount an index, you must have one or more nodes with a shared cache available. By default, dedicated frozen data tier nodes (nodes with the `data_frozen` role and no other data roles) have a shared cache configured using the greater of 90% of total disk space and total disk space subtracted a headroom of 100GB. + +Using a dedicated frozen tier is highly recommended for production use. If you do not have a dedicated frozen tier, you must configure the `xpack.searchable.snapshot.shared_cache.size` setting to reserve space for the cache on one or more nodes. Partially mounted indices are only allocated to nodes that have a shared cache. + +::::{admonition} Manual snapshot mounting +:class: warning + +:name: manually-mounting-snapshots + +Manually mounting snapshots captured by an Index Lifecycle Management ({{ilm-init}}) policy can interfere with {{ilm-init}}'s automatic management. This may lead to issues such as data loss or complications with snapshot handling. + +For optimal results, allow {{ilm-init}} to manage snapshots automatically. + +[Learn more about {{ilm-init}} snapshot management](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-searchable-snapshot.html). + +:::: + + +$$$searchable-snapshots-shared-cache$$$ + +`xpack.searchable.snapshot.shared_cache.size` +: ([Static](../../deploy/self-managed/configure-elasticsearch.md#static-cluster-setting)) Disk space reserved for the shared cache of partially mounted indices. Accepts a percentage of total disk space or an absolute [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units). Defaults to `90%` of total disk space for dedicated frozen data tier nodes. Otherwise defaults to `0b`. + +`xpack.searchable.snapshot.shared_cache.size.max_headroom` +: ([Static](../../deploy/self-managed/configure-elasticsearch.md#static-cluster-setting), [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) For dedicated frozen tier nodes, the max headroom to maintain. If `xpack.searchable.snapshot.shared_cache.size` is not explicitly set, this setting defaults to `100GB`. Otherwise it defaults to `-1` (not set). You can only configure this setting if `xpack.searchable.snapshot.shared_cache.size` is set as a percentage. + +To illustrate how these settings work in concert let us look at two examples when using the default values of the settings on a dedicated frozen node: + +* A 4000 GB disk will result in a shared cache sized at 3900 GB. 90% of 4000 GB is 3600 GB, leaving 400 GB headroom. The default `max_headroom` of 100 GB takes effect, and the result is therefore 3900 GB. +* A 400 GB disk will result in a shared cache sized at 360 GB. + +You can configure the settings in `elasticsearch.yml`: + +```yaml +xpack.searchable.snapshot.shared_cache.size: 4TB +``` + +::::{important} +You can only configure these settings on nodes with the [`data_frozen`](../../distributed-architecture/clusters-nodes-shards/node-roles.md#data-frozen-node) role. Additionally, nodes with a shared cache can only have a single [data path](../../deploy/self-managed/configure-elasticsearch.md#path-settings). +:::: + + +{{es}} also uses a dedicated system index named `.snapshot-blob-cache` to speed up the recoveries of {{search-snap}} shards. This index is used as an additional caching layer on top of the partially or fully mounted data and contains the minimal required data to start the {{search-snap}} shards. {{es}} automatically deletes the documents that are no longer used in this index. This periodic clean up can be tuned using the following settings: + +`searchable_snapshots.blob_cache.periodic_cleanup.interval` +: ([Dynamic](../../deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The interval at which the periodic cleanup of the `.snapshot-blob-cache` index is scheduled. Defaults to every hour (`1h`). + +`searchable_snapshots.blob_cache.periodic_cleanup.retention_period` +: ([Dynamic](../../deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The retention period to keep obsolete documents in the `.snapshot-blob-cache` index. Defaults to every hour (`1h`). + +`searchable_snapshots.blob_cache.periodic_cleanup.batch_size` +: ([Dynamic](../../deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The number of documents that are searched for and bulk-deleted at once during the periodic cleanup of the `.snapshot-blob-cache` index. Defaults to `100`. + +`searchable_snapshots.blob_cache.periodic_cleanup.pit_keep_alive` +: ([Dynamic](../../deploy/self-managed/configure-elasticsearch.md#dynamic-cluster-setting)) The value used for the [point-in-time keep alive](https://www.elastic.co/guide/en/elasticsearch/reference/current/point-in-time-api.html#point-in-time-keep-alive) requests executed during the periodic cleanup of the `.snapshot-blob-cache` index. Defaults to `10m`. + + +## Reduce costs with {{search-snaps}} [searchable-snapshots-costs] + +In most cases, {{search-snaps}} reduce the costs of running a cluster by removing the need for replica shards and for shard data to be copied between nodes. However, if it’s particularly expensive to retrieve data from a snapshot repository in your environment, {{search-snaps}} may be more costly than regular indices. Ensure that the cost structure of your operating environment is compatible with {{search-snaps}} before using them. + + +### Replica costs [searchable-snapshots-costs-replicas] + +For resiliency, a regular index requires multiple redundant copies of each shard across multiple nodes. If a node fails, {{es}} uses the redundancy to rebuild any lost shard copies. A {{search-snap}} index doesn’t require replicas. If a node containing a {{search-snap}} index fails, {{es}} can rebuild the lost shard cache from the snapshot repository. + +Without replicas, rarely-accessed {{search-snap}} indices require far fewer resources. A cold data tier that contains replica-free fully-mounted {{search-snap}} indices requires half the nodes and disk space of a tier containing the same data in regular indices. The frozen tier, which contains only partially-mounted {{search-snap}} indices, requires even fewer resources. + + +### Data transfer costs [snapshot-retrieval-costs] + +When a shard of a regular index is moved between nodes, its contents are copied from another node in your cluster. In many environments, the costs of moving data between nodes are significant, especially if running in a Cloud environment with nodes in different zones. In contrast, when mounting a {{search-snap}} index or moving one of its shards, the data is always copied from the snapshot repository. This is typically much cheaper. + +::::{warning} +Most cloud providers charge significant fees for data transferred between regions and for data transferred out of their platforms. You should only mount snapshots into a cluster that is in the same region as the snapshot repository. If you wish to search data across multiple regions, configure multiple clusters and use [{{ccs}}](../../../solutions/search/cross-cluster-search.md) or [{{ccr}}](../cross-cluster-replication.md) instead of {{search-snaps}}. +:::: + + +It’s worth noting that if a searchable snapshot index has no replicas, then when the node hosting it is shut down, allocation will immediately try to relocate the index to a new node in order to maximize availability. For fully mounted indices this will result in the new node downloading the entire index snapshot from the cloud repository. Under a rolling cluster restart, this may happen multiple times for each searchable snapshot index. Temporarily disabling allocation during planned node restart will prevent this, as described in the [cluster restart procedure](../../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling). + + +## Back up and restore {{search-snaps}} [back-up-restore-searchable-snapshots] + +You can use [regular snapshots](create-snapshots.md) to back up a cluster containing {{search-snap}} indices. When you restore a snapshot containing {{search-snap}} indices, these indices are restored as {{search-snap}} indices again. + +Before you restore a snapshot containing a {{search-snap}} index, you must first [register the repository](self-managed.md) containing the original index snapshot. When restored, the {{search-snap}} index mounts the original index snapshot from its original repository. If wanted, you can use separate repositories for regular snapshots and {{search-snaps}}. + +A snapshot of a {{search-snap}} index contains only a small amount of metadata which identifies its original index snapshot. It does not contain any data from the original index. The restore of a backup will fail to restore any {{search-snap}} indices whose original index snapshot is unavailable. + +Because {{search-snap}} indices are not regular indices, it is not possible to use a [source-only repository](source-only-repository.md) to take snapshots of {{search-snap}} indices. + +::::{admonition} Reliability of {search-snaps} +:class: warning + +:name: searchable-snapshots-reliability + +The sole copy of the data in a {{search-snap}} index is the underlying snapshot, stored in the repository. If you remove this snapshot, the data will be permanently lost. Although {{es}} may have cached some of the data onto local storage for faster searches, this cached data is incomplete and cannot be used for recovery if you remove the underlying snapshot. For example: + +* You must not unregister a repository while any of the {{search-snaps}} it contains are mounted in {{es}}. +* You must not delete a snapshot if any of its indices are mounted as {{search-snap}} indices. The snapshot contains the sole full copy of your data. If you delete it then the data cannot be recovered from elsewhere. +* If you mount indices from snapshots held in a repository to which a different cluster has write access then you must make sure that the other cluster does not delete these snapshots. The snapshot contains the sole full copy of your data. If you delete it then the data cannot be recovered from elsewhere. +* The data in a searchable snapshot index are cached in local storage, so if you delete the underlying searchable snapshot {{es}} will continue to operate normally until the first cache miss. This may be much later, for instance when a shard relocates to a different node, or when the node holding the shard restarts. +* If the repository fails or corrupts the contents of the snapshot and you cannot restore it to its previous healthy state then the data is permanently lost. + + The blob storage offered by all major public cloud providers typically offers very good protection against failure or corruption. If you manage your own repository storage then you are responsible for its reliability. + + +:::: + + diff --git a/deploy-manage/tools/snapshot-and-restore/self-managed.md b/deploy-manage/tools/snapshot-and-restore/self-managed.md new file mode 100644 index 000000000..9643395ae --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/self-managed.md @@ -0,0 +1,175 @@ +--- +navigation_title: "Register a repository" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html +--- + + + +# Self-managed [snapshots-register-repository] + + +This guide shows you how to register a snapshot repository. A snapshot repository is an off-cluster storage location for your snapshots. You must register a repository before you can take or restore snapshots. + +In this guide, you’ll learn how to: + +* Register a snapshot repository +* Verify that a repository is functional +* Clean up a repository to remove unneeded files + + +## Prerequisites [snapshot-repo-prereqs] + +* To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions: + + * [Cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + * [Index privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index + +* To register a snapshot repository, the cluster’s global metadata must be writeable. Ensure there aren’t any [cluster blocks](https://www.elastic.co/guide/en/elasticsearch/reference/current/misc-cluster-settings.html#cluster-read-only) that prevent write access. + + +## Considerations [snapshot-repo-considerations] + +When registering a snapshot repository, keep the following in mind: + +* Each snapshot repository is separate and independent. {{es}} doesn’t share data between repositories. +* + + Clusters should only register a particular snapshot repository bucket once. If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. On other clusters, register the repository as read-only. + + This prevents multiple clusters from writing to the repository at the same time and corrupting the repository’s contents. It also prevents {{es}} from caching the repository’s contents, which means that changes made by other clusters will become visible straight away. + +* When upgrading {{es}} to a newer version you can continue to use the same repository you were using before the upgrade. If the repository is accessed by multiple clusters, they should all have the same version. Once a repository has been modified by a particular version of {{es}}, it may not work correctly when accessed by older versions. However, you will be able to recover from a failed upgrade by restoring a snapshot taken before the upgrade into a cluster running the pre-upgrade version, even if you have taken more snapshots during or after the upgrade. + + +## Manage snapshot repositories [manage-snapshot-repos] + +You can register and manage snapshot repositories in two ways: + +* {{kib}}'s **Snapshot and Restore** feature +* {{es}}'s [snapshot repository management APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore-apis.html#snapshot-restore-repo-apis) + +To manage repositories in {{kib}}, go to the main menu and click **Stack Management** > **Snapshot and Restore*** > ***Repositories**. To register a snapshot repository, click **Register repository**. + +You can also register a repository using the [Create snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html). + + +## Snapshot repository types [snapshot-repo-types] + +Supported snapshot repository types vary based on your deployment type: + +* [{{ess}} repository types](#ess-repo-types) +* [Self-managed repository types](#self-managed-repo-types) + + +### {{ess}} repository types [ess-repo-types] + +[{{ess}} deployments](https://cloud.elastic.co/registration?page=docs&placement=docs-body) automatically register the [`found-snapshots`](../snapshot-and-restore.md) repository. {{ess}} uses this repository and the `cloud-snapshot-policy` to take periodic snapshots of your cluster. You can also use the `found-snapshots` repository for your own [{{slm-init}} policies](create-snapshots.md#automate-snapshots-slm) or to store searchable snapshots. + +The `found-snapshots` repository is specific to each deployment. However, you can restore snapshots from another deployment’s `found-snapshots` repository if the deployments are under the same account and in the same region. See the Cloud [Snapshot and restore](../snapshot-and-restore.md) documentation to learn more. + +{{ess}} deployments also support the following repository types: + +* [Azure](ec-azure-snapshotting.md) +* [Google Cloud Storage](ec-gcs-snapshotting.md) +* [AWS S3](ec-aws-custom-repository.md) +* [Source-only](source-only-repository.md) + + +### Self-managed repository types [self-managed-repo-types] + +If you manage your own {{es}} cluster, you can use the following built-in snapshot repository types: + +* [Azure](azure-repository.md) +* [Google Cloud Storage](google-cloud-storage-repository.md) +* [AWS S3](s3-repository.md) +* [Shared file system](shared-file-system-repository.md) +* [Read-only URL](read-only-url-repository.md) +* [Source-only](source-only-repository.md) + +$$$snapshots-repository-plugins$$$ +Other repository types are available through official plugins: + +* [Hadoop Distributed File System (HDFS)](https://www.elastic.co/guide/en/elasticsearch/plugins/current/repository-hdfs.html) + +You can also use alternative storage implementations with these repository types, as long as the alternative implementation is fully compatible. For instance, [MinIO](https://minio.io) provides an alternative implementation of the AWS S3 API and you can use MinIO with the [`s3` repository type](s3-repository.md). + +Note that some storage systems claim to be compatible with these repository types without emulating their behaviour in full. {{es}} requires full compatibility. In particular the alternative implementation must support the same set of API endpoints, return the same errors in case of failures, and offer equivalent consistency guarantees and performance even when accessed concurrently by multiple nodes. Incompatible error codes, consistency or performance may be particularly hard to track down since errors, consistency failures, and performance issues are usually rare and hard to reproduce. + +You can perform some basic checks of the suitability of your storage system using the [Repository analysis](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html) API. If this API does not complete successfully, or indicates poor performance, then your storage system is not fully compatible and is therefore unsuitable for use as a snapshot repository. You will need to work with the supplier of your storage system to address any incompatibilities you encounter. + + +## Verify a repository [snapshots-repository-verification] + +When you register a snapshot repository, {{es}} automatically verifies that the repository is available and functional on all master and data nodes. + +To disable this verification, set the [create snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html)'s `verify` query parameter to `false`. You can’t disable repository verification in {{kib}}. + +```console +PUT _snapshot/my_unverified_backup?verify=false +{ + "type": "fs", + "settings": { + "location": "my_unverified_backup_location" + } +} +``` + +If wanted, you can manually run the repository verification check. To verify a repository in {{kib}}, go to the **Repositories** list page and click the name of a repository. Then click **Verify repository**. You can also use the [verify snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/verify-snapshot-repo-api.html). + +```console +POST _snapshot/my_unverified_backup/_verify +``` + +If successful, the request returns a list of nodes used to verify the repository. If verification fails, the request returns an error. + +You can test a repository more thoroughly using the [repository analysis API](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html). + + +## Clean up a repository [snapshots-repository-cleanup] + +Repositories can over time accumulate data that is not referenced by any existing snapshot. This is a result of the data safety guarantees the snapshot functionality provides in failure scenarios during snapshot creation and the decentralized nature of the snapshot creation process. This unreferenced data does in no way negatively impact the performance or safety of a snapshot repository but leads to higher than necessary storage use. To remove this unreferenced data, you can run a cleanup operation on the repository. This will trigger a complete accounting of the repository’s contents and delete any unreferenced data. + +To run the repository cleanup operation in {{kib}}, go to the **Repositories** list page and click the name of a repository. Then click **Clean up repository**. + +You can also use the [clean up snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/clean-up-snapshot-repo-api.html). + +```console +POST _snapshot/my_repository/_cleanup +``` + +The API returns: + +```console-result +{ + "results": { + "deleted_bytes": 20, + "deleted_blobs": 5 + } +} +``` + +Depending on the concrete repository implementation the numbers shown for bytes free as well as the number of blobs removed will either be an approximation or an exact result. Any non-zero value for the number of blobs removed implies that unreferenced blobs were found and subsequently cleaned up. + +Please note that most of the cleanup operations executed by this endpoint are automatically executed when deleting any snapshot from a repository. If you regularly delete snapshots, you will in most cases not get any or only minor space savings from using this functionality and should lower your frequency of invoking it accordingly. + + +## Back up a repository [snapshots-repository-backup] + +You may wish to make an independent backup of your repository, for instance so that you have an archive copy of its contents that you can use to recreate the repository in its current state at a later date. + +You must ensure that {{es}} does not write to the repository while you are taking the backup of its contents. If {{es}} writes any data to the repository during the backup then the contents of the backup may not be consistent and it may not be possible to recover any data from it in future. Prevent writes to the repository by unregistering the repository from the cluster which has write access to it. + +Alternatively, if your repository supports it, you may take an atomic snapshot of the underlying filesystem and then take a backup of this filesystem snapshot. It is very important that the filesystem snapshot is taken atomically. + +::::{warning} +Do not rely on repository backups that were taken by methods other than the one described in this section. If you use another method to make a copy of your repository contents then the resulting copy may capture an inconsistent view of your data. Restoring a repository from such a copy may fail, reporting errors, or may succeed having silently lost some of your data. +:::: + + +::::{warning} +Do not use filesystem snapshots of individual nodes as a backup mechanism. You must use the {{es}} snapshot and restore feature to copy the cluster contents to a separate repository. Then, if desired, you can take a filesystem snapshot of this repository. +:::: + + +When restoring a repository from a backup, you must not register the repository with {{es}} until the repository contents are fully restored. If you alter the contents of a repository while it is registered with {{es}} then the repository may become unreadable or may silently lose some of its contents. After restoring a repository from a backup, use the [Verify repository integrity](https://www.elastic.co/guide/en/elasticsearch/reference/current/verify-repo-integrity-api.html) API to verify its integrity before you start to use the repository. diff --git a/deploy-manage/tools/snapshot-and-restore/shared-file-system-repository.md b/deploy-manage/tools/snapshot-and-restore/shared-file-system-repository.md new file mode 100644 index 000000000..f3bb084eb --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/shared-file-system-repository.md @@ -0,0 +1,192 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-filesystem-repository.html +--- + +# Shared file system repository [snapshots-filesystem-repository] + +::::{note} +This repository type is only available if you run {{es}} on your own hardware. If you use {{ess}}, see [{{ess}} repository types](self-managed.md#ess-repo-types). +:::: + + +Use a shared file system repository to store snapshots on a shared file system. + +To register a shared file system repository, first mount the file system to the same location on all master and data nodes. Then add the file system’s path or parent directory to the `path.repo` setting in `elasticsearch.yml` for each master and data node. For running clusters, this requires a [rolling restart](../../maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) of each node. + +Supported `path.repo` values vary by platform: + +:::::::{tab-set} + +::::::{tab-item} Unix-like systems +Linux and macOS installations support Unix-style paths: + +```yaml +path: + repo: + - /mount/backups + - /mount/long_term_backups +``` + +After restarting each node, use {{kib}} or the [create snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html) to register the repository. When registering the repository, specify the file system’s path: + +```console +PUT _snapshot/my_fs_backup +{ + "type": "fs", + "settings": { + "location": "/mount/backups/my_fs_backup_location" + } +} +``` + +If you specify a relative path, {{es}} resolves the path using the first value in the `path.repo` setting. + +```console +PUT _snapshot/my_fs_backup +{ + "type": "fs", + "settings": { + "location": "my_fs_backup_location" <1> + } +} +``` + +1. The first value in the `path.repo` setting is `/mount/backups`. This relative path, `my_fs_backup_location`, resolves to `/mount/backups/my_fs_backup_location`. + + +Clusters should only register a particular snapshot repository bucket once. If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. On other clusters, register the repository as read-only. + +This prevents multiple clusters from writing to the repository at the same time and corrupting the repository’s contents. It also prevents {{es}} from caching the repository’s contents, which means that changes made by other clusters will become visible straight away. + +To register a file system repository as read-only using the create snapshot repository API, set the `readonly` parameter to true. Alternatively, you can register a [URL repository](read-only-url-repository.md) for the file system. + +```console +PUT _snapshot/my_fs_backup +{ + "type": "fs", + "settings": { + "location": "my_fs_backup_location", + "readonly": true + } +} +``` +:::::: + +::::::{tab-item} Windows +Windows installations support both DOS and Microsoft UNC paths. Escape any backslashes in the paths. For UNC paths, provide the server and share name as a prefix. + +```yaml +path: + repo: + - "E:\\Mount\\Backups" <1> + - "\\\\MY_SERVER\\Mount\\Long_term_backups" <2> +``` + +1. DOS path +2. UNC path + + +After restarting each node, use {{kib}} or the [create snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html) to register the repository. When registering the repository, specify the file system’s path: + +```console +PUT _snapshot/my_fs_backup +{ + "type": "fs", + "settings": { + "location": "E:\\Mount\\Backups\\My_fs_backup_location" + } +} +``` + +If you specify a relative path, {{es}} resolves the path using the first value in the `path.repo` setting. + +```console +PUT _snapshot/my_fs_backup +{ + "type": "fs", + "settings": { + "location": "My_fs_backup_location" <1> + } +} +``` + +1. The first value in the `path.repo` setting is `E:\Mount\Backups`. This relative path, `My_fs_backup_location`, resolves to `E:\Mount\Backups\My_fs_backup_location`. + + +Clusters should only register a particular snapshot repository bucket once. If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. On other clusters, register the repository as read-only. + +This prevents multiple clusters from writing to the repository at the same time and corrupting the repository’s contents. It also prevents {{es}} from caching the repository’s contents, which means that changes made by other clusters will become visible straight away. + +To register a file system repository as read-only using the create snapshot repository API, set the `readonly` parameter to true. Alternatively, you can register a [URL repository](read-only-url-repository.md) for the file system. + +```console +PUT _snapshot/my_fs_backup +{ + "type": "fs", + "settings": { + "location": "my_fs_backup_location", + "readonly": true + } +} +``` +:::::: + +::::::: +## Repository settings [filesystem-repository-settings] + +`chunk_size` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum size of files in snapshots. In snapshots, files larger than this are broken down into chunks of this size or smaller. Defaults to `null` (unlimited file size). + +`compress` +: (Optional, Boolean) If `true`, metadata files, such as index mappings and settings, are compressed in snapshots. Data files are not compressed. Defaults to `true`. + +`location` +: (Required, string) Location of the shared filesystem used to store and retrieve snapshots. This location must be registered in the `path.repo` setting on all master and data nodes in the cluster. Unlike `path.repo`, this setting supports only a single file path. + +`max_number_of_snapshots` +: (Optional, integer) Maximum number of snapshots the repository can contain. Defaults to `Integer.MAX_VALUE`, which is `2^31-1` or `2147483647`. + +`max_restore_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`max_snapshot_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot creation rate per node. Defaults to `40mb` per second. Note that if the [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services) are set, then it defaults to unlimited, and the rate is additionally throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`readonly` +: (Optional, Boolean) If `true`, the repository is read-only. The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + + Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the `readonly` parameter set to `true`. + + If `false`, the cluster can write to the repository and create snapshots in it. Defaults to `false`. + + ::::{important} + If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + + :::: + + + +## Troubleshooting a shared file system repository [_troubleshooting_a_shared_file_system_repository] + +{{es}} interacts with a shared file system repository using the file system abstraction in your operating system. This means that every {{es}} node must be able to perform operations within the repository path such as creating, opening, and renaming files, and creating and listing directories, and operations performed by one node must be visible to other nodes as soon as they complete. + +Check for common misconfigurations using the [Verify snapshot repository](https://www.elastic.co/guide/en/elasticsearch/reference/current/verify-snapshot-repo-api.html) API and the [Repository analysis](https://www.elastic.co/guide/en/elasticsearch/reference/current/repo-analysis-api.html) API. When the repository is properly configured, these APIs will complete successfully. If the verify repository or repository analysis APIs report a problem then you will be able to reproduce this problem outside {{es}} by performing similar operations on the file system directly. + +If the verify repository or repository analysis APIs fail with an error indicating insufficient permissions then adjust the configuration of the repository within your operating system to give {{es}} an appropriate level of access. To reproduce such problems directly, perform the same operations as {{es}} in the same security context as the one in which {{es}} is running. For example, on Linux, use a command such as `su` to switch to the user as which {{es}} runs. + +If the verify repository or repository analysis APIs fail with an error indicating that operations on one node are not immediately visible on another node then adjust the configuration of the repository within your operating system to address this problem. If your repository cannot be configured with strong enough visibility guarantees then it is not suitable for use as an {{es}} snapshot repository. + +The verify repository and repository analysis APIs will also fail if the operating system returns any other kind of I/O error when accessing the repository. If this happens, address the cause of the I/O error reported by the operating system. + +::::{tip} +Many NFS implementations match accounts across nodes using their *numeric* user IDs (UIDs) and group IDs (GIDs) rather than their names. It is possible for {{es}} to run under an account with the same name (often `elasticsearch`) on each node, but for these accounts to have different numeric user or group IDs. If your shared file system uses NFS then ensure that every node is running with the same numeric UID and GID, or else update your NFS configuration to account for the variance in numeric IDs across nodes. +:::: + + + +## Linearizable register implementation [repository-fs-linearizable-registers] + +The linearizable register implementation for shared filesystem repositories is based around file locking. To perform a compare-and-exchange operation on a register, {{es}} first locks he underlying file and then writes the updated contents under the same lock. This ensures that the file has not changed in the meantime. + + diff --git a/deploy-manage/tools/snapshot-and-restore/source-only-repository.md b/deploy-manage/tools/snapshot-and-restore/source-only-repository.md new file mode 100644 index 000000000..210a1b69d --- /dev/null +++ b/deploy-manage/tools/snapshot-and-restore/source-only-repository.md @@ -0,0 +1,74 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-source-only-repository.html +--- + +# Source-only repository [snapshots-source-only-repository] + +You can use a source-only repository to take minimal, source-only snapshots that use up to 50% less disk space than regular snapshots. + +Unlike other repository types, a source-only repository doesn’t directly store snapshots. It delegates storage to another registered snapshot repository. + +When you take a snapshot using a source-only repository, {{es}} creates a source-only snapshot in the delegated storage repository. This snapshot only contains stored fields and metadata. It doesn’t include index or doc values structures and isn’t immediately searchable when restored. To search the restored data, you first have to [reindex](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) it into a new data stream or index. + +::::{important} +Source-only snapshots are only supported if the `_source` field is enabled and no source-filtering is applied. As a result, indices adopting synthetic source cannot be restored. When you restore a source-only snapshot: + +* The restored index is read-only and can only serve `match_all` search or scroll requests to enable reindexing. +* Queries other than `match_all` and `_get` requests are not supported. +* The mapping of the restored index is empty, but the original mapping is available from the types top level `meta` element. +* Information such as document count, deleted document count and store size are not available for such indices since these indices do not contain the relevant data structures to retrieve this information from. Therefore, this information is not shown for such indices in APIs such as the [cat indices API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-indices.html). + +:::: + + +Before registering a source-only repository, use {{kib}} or the [create snapshot repository API](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html) to register a snapshot repository of another type to use for storage. Then register the source-only repository and specify the delegated storage repository in the request. + +```console +PUT _snapshot/my_src_only_repository +{ + "type": "source", + "settings": { + "delegate_type": "fs", + "location": "my_backup_repository" + } +} +``` + +## Repository settings [source-only-repository-settings] + +`chunk_size` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum size of files in snapshots. In snapshots, files larger than this are broken down into chunks of this size or smaller. Defaults to `null` (unlimited file size). + +`compress` +: (Optional, Boolean) If `true`, metadata files, such as index mappings and settings, are compressed in snapshots. Data files are not compressed. Defaults to `true`. + +`delegate_type` +: (Optional, string) Delegated repository type. For valid values, see the [`type` parameter](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-snapshot-repo-api.html#put-snapshot-repo-api-request-type). + + `source` repositories can use `settings` properties for its delegated repository type. See [Source-only repository](). + + +`max_number_of_snapshots` +: (Optional, integer) Maximum number of snapshots the repository can contain. Defaults to `Integer.MAX_VALUE`, which is `2^31-1` or `2147483647`. + +`max_restore_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`max_snapshot_bytes_per_sec` +: (Optional, [byte value](https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units)) Maximum snapshot creation rate per node. Defaults to `40mb` per second. Note that if the [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services) are set, then it defaults to unlimited, and the rate is additionally throttled through [recovery settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html). + +`readonly` +: (Optional, Boolean) If `true`, the repository is read-only. The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + + Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the `readonly` parameter set to `true`. + + If `false`, the cluster can write to the repository and create snapshots in it. Defaults to `false`. + + ::::{important} + If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + + :::: + + + diff --git a/deploy-manage/uninstall.md b/deploy-manage/uninstall.md new file mode 100644 index 000000000..df04a3d75 --- /dev/null +++ b/deploy-manage/uninstall.md @@ -0,0 +1,5 @@ +# Uninstall + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/362 \ No newline at end of file diff --git a/deploy-manage/uninstall/delete-a-cloud-deployment.md b/deploy-manage/uninstall/delete-a-cloud-deployment.md new file mode 100644 index 000000000..bb8df7b53 --- /dev/null +++ b/deploy-manage/uninstall/delete-a-cloud-deployment.md @@ -0,0 +1,21 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-delete-deployment.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-delete-deployment.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-terminate-deployment.html + - https://www.elastic.co/guide/en/cloud/current/ec-delete-deployment.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restore-deployment.html +--- + +# Delete a cloud deployment + +% What needs to be done: Refine + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-delete-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-delete-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-terminate-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-delete-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-restore-deployment.md +% Notes: if you need to restore a deleted deployment ... \ No newline at end of file diff --git a/deploy-manage/uninstall/uninstall-a-self-managed-cluster.md b/deploy-manage/uninstall/uninstall-a-self-managed-cluster.md new file mode 100644 index 000000000..67922a5f0 --- /dev/null +++ b/deploy-manage/uninstall/uninstall-a-self-managed-cluster.md @@ -0,0 +1,5 @@ +# Uninstall a self-managed cluster + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/362 \ No newline at end of file diff --git a/deploy-manage/uninstall/uninstall-elastic-cloud-enterprise.md b/deploy-manage/uninstall/uninstall-elastic-cloud-enterprise.md new file mode 100644 index 000000000..de2bea13d --- /dev/null +++ b/deploy-manage/uninstall/uninstall-elastic-cloud-enterprise.md @@ -0,0 +1,41 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-uninstall.html +--- + +# Uninstall Elastic Cloud Enterprise [ece-uninstall] + +You might need to remove Elastic Cloud Enterprise for one of the following reasons: + +* If the installation process does not complete successfully and you cannot troubleshoot the issue. +* If you are de-provisioning a host and want to remove the installed Elastic Cloud Enterprise software. + +You remove Elastic Cloud Enterprise by removing all containers on the host: + +* If using Docker + +::::{admonition} +```sh +docker rm -f frc-runners-runner frc-allocators-allocator $(docker ps -a -q); sudo rm -rf /mnt/data/elastic/ && docker ps -a +``` + +:::: + + +* If using Podman + +::::{admonition} +```sh +sudo podman rm -f frc-runners-runner frc-allocators-allocator $(sudo podman ps -a -q); sudo rm -rf /mnt/data/elastic && sudo podman ps -a +``` + +:::: + + +If you plan to reinstall Elastic Cloud Enterprise on the host, make sure you [delete the host](../maintenance/ece/delete-ece-hosts.md) from the Cloud UI first. Reinstallation can fail if the host is still associated with your old Elastic Cloud Enterprise installation. + +::::{warning} +During installation, the system generates secrets that are placed into the `/mnt/data/elastic/bootstrap-state/bootstrap-secrets.json` secrets file, unless you passed in a different path with the --host-storage-path parameter. Keep the information in the `bootstrap-secrets.json` file secure by removing it from its default location and placing it into a secure storage location. +:::: + + diff --git a/deploy-manage/uninstall/uninstall-elastic-cloud-on-kubernetes.md b/deploy-manage/uninstall/uninstall-elastic-cloud-on-kubernetes.md new file mode 100644 index 000000000..621a32266 --- /dev/null +++ b/deploy-manage/uninstall/uninstall-elastic-cloud-on-kubernetes.md @@ -0,0 +1,26 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-uninstalling-eck.html +--- + +# Uninstall Elastic Cloud on Kubernetes [k8s-uninstalling-eck] + +To uninstall the operator: + +1. Remove all Elastic resources in all namespaces: + + ```shell + kubectl get namespaces --no-headers -o custom-columns=:metadata.name \ + | xargs -n1 kubectl delete elastic --all -n + ``` + + This deletes all underlying Elastic Stack resources, including their Pods, Secrets, Services, and so on. + +2. Uninstall the operator: + + ```shell + kubectl delete -f https://download.elastic.co/downloads/eck/2.16.1/operator.yaml + kubectl delete -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml + ``` + + diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md new file mode 100644 index 000000000..9da1ca6e8 --- /dev/null +++ b/deploy-manage/upgrade.md @@ -0,0 +1,7 @@ +# Upgrade + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/355 + +% Scope notes: Can have version-specific child pages Connection between upgrading your orchestrator and your cluster \ No newline at end of file diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md new file mode 100644 index 000000000..3c3ea7314 --- /dev/null +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -0,0 +1,60 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/upgrade.html + - https://www.elastic.co/guide/en/kibana/current/upgrade-migrations-rolling-back.html + - https://www.elastic.co/guide/en/elastic-stack/current/upgrading-elastic-stack.html + - https://www.elastic.co/guide/en/elastic-stack/current/upgrading-elasticsearch.html + - https://www.elastic.co/guide/en/elastic-stack/current/upgrading-kibana.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-upgrade-deployment.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-upgrade-deployment.html + - https://www.elastic.co/guide/en/cloud/current/ec-upgrade-deployment.html + - https://www.elastic.co/guide/en/elastic-stack/current/upgrade-elastic-stack-for-elastic-cloud.html + - https://www.elastic.co/guide/en/elastic-stack/current/upgrading-elastic-stack-on-prem.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-upgrading-stack.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-orchestration.html +--- + +# Upgrade your deployment or cluster + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/270 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/upgrade.md +% - [ ] ./raw-migrated-files/kibana/kibana/upgrade-migrations-rolling-back.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/upgrading-elastic-stack.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/upgrading-elasticsearch.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/upgrading-kibana.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-upgrade-deployment.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-upgrade-deployment.md +% Notes: redirect only +% - [ ] ./raw-migrated-files/cloud/cloud/ec-upgrade-deployment.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/upgrade-elastic-stack-for-elastic-cloud.md +% - [ ] ./raw-migrated-files/stack-docs/elastic-stack/upgrading-elastic-stack-on-prem.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-upgrading-stack.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-orchestration.md +% Notes: upgrade explanations + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$preventing-migration-failures$$$ + +$$$prepare-to-upgrade$$$ + +$$$k8s-nodesets$$$ + +$$$k8s-orchestration-limitations$$$ + +$$$k8s-statefulsets$$$ + +$$$k8s-upgrade-patterns$$$ + +$$$k8s-upgrading$$$ + +$$$prepare-to-upgrade-8x$$$ + +$$$rolling-upgrades$$$ + +$$$upgrading-reindex$$$ \ No newline at end of file diff --git a/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md b/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md new file mode 100644 index 000000000..0be64f173 --- /dev/null +++ b/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md @@ -0,0 +1,60 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/archived-settings.html +--- + +# Archived settings [archived-settings] + +If you upgrade a cluster with a deprecated persistent cluster setting to a version that no longer supports the setting, {{es}} automatically archives that setting. Similarly, if you upgrade a cluster that contains an index with an unsupported index setting, {{es}} archives the index setting. + +We recommend you remove any archived settings after upgrading. Archived settings are considered invalid and can interfere with your ability to configure other settings. + +Archived settings start with the `archived.` prefix. + + +## Archived cluster settings [archived-cluster-settings] + +Use the following [cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) request to check for archived cluster settings. If the request returns an empty object (`{ }`), there are no archived cluster settings. + +```console +GET _cluster/settings?flat_settings=true&filter_path=persistent.archived* +``` + +To remove any archived cluster settings, use the following [cluster update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html) request. + +```console +PUT _cluster/settings +{ + "persistent": { + "archived.*": null + } +} +``` + +{{es}} doesn’t archive transient cluster settings or settings in `elasticsearch.yml`. If a node includes an unsupported setting in `elasticsearch.yml`, it will return an error at startup. + + +## Archived index settings [archived-index-settings] + +::::{important} +Before you upgrade, remove any unsupported index settings from index and component templates. {{es}} doesn’t archive unsupported index settings in templates during an upgrade. Attempts to use a template that contains an unsupported index setting will fail and return an error. This includes automated operations, such the {{ilm-init}} rollover action. +:::: + + +Archived index settings don’t affect an index’s configuration or most index operations, such as indexing or search. However, you’ll need to remove them before you can configure other settings for the index, such as `index.hidden`. + +Use the following [get index settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-get-settings.html) request to get a list indices with archived settings. If the request returns an empty object (`{ }`), there are no archived index settings. + +```console +GET */_settings?flat_settings=true&filter_path=**.settings.archived* +``` + +To remove any archived index settings, use the following [indices update settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-update-settings.html) request. + +```console +PUT /my-index/_settings +{ + "archived.*": null +} +``` + diff --git a/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md b/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md new file mode 100644 index 000000000..979de4148 --- /dev/null +++ b/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md @@ -0,0 +1,52 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/archive-indices.html +--- + +# Reading indices from older Elasticsearch versions [archive-indices] + +{{es}} has full query and write support for indices created in the previous major version. If you have indices created in {{es}} versions 5 or 6, you can now use the archive functionality to import them into newer {{es}} versions as well. + +The archive functionality provides slower read-only access to older {{es}} data, for compliance or regulatory reasons, the occasional lookback or investigation, or to rehydrate parts of it. Access to the data is expected to be infrequent, and can therefore happen with limited performance and query capabilities. + +For this, {{es}} has the ability to access older snapshot repositories (going back to version 5). The legacy indices in the [snapshot repository](../../tools/snapshot-and-restore.md) can either be [restored](https://www.elastic.co/guide/en/elasticsearch/reference/current/restore-snapshot-api.html), or can be directly accessed via [searchable snapshots](../../tools/snapshot-and-restore/searchable-snapshots.md) so that the archived data won’t even need to fully reside on local disks for access. + + +## Supported field types [archive-indices-supported-field-types] + +Old mappings are imported as much "as-is" as possible into {{es}} 8, but only provide regular query capabilities on a select subset of fields: + +* [Numeric types](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html) +* [`boolean` type](https://www.elastic.co/guide/en/elasticsearch/reference/current/boolean.html) +* [`ip` type](https://www.elastic.co/guide/en/elasticsearch/reference/current/ip.html) +* [`geo_point` type](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-point.html) +* [`date` types](https://www.elastic.co/guide/en/elasticsearch/reference/current/date.html): the date `format` setting on date fields is supported as long as it behaves similarly across these versions. In case it is not, for example [when using custom date formats](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/migrate-to-java-time.html), this field can be updated on legacy indices so that it can be changed by a user if need be. +* [`keyword` type](https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html#keyword-field-type): the `normalizer` setting on keyword fields is supported as long as it behaves similarly across these versions. In case it is not, this field can be updated on legacy indices if need be. +* [`text` type](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html#text-field-type): scoring capabilities are limited, and all queries return constant scores that are equal to 1.0. The `analyzer` settings on text fields are supported as long as they behave similarly across these versions. In case they do not, they can be updated on legacy indices if need be. +* [Multi-fields](https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-fields.html) +* [Field aliases](https://www.elastic.co/guide/en/elasticsearch/reference/current/field-alias.html) +* [`object`](https://www.elastic.co/guide/en/elasticsearch/reference/current/object.html) fields +* some basic metadata fields, e.g. `_type` for querying {{es}} 5 indices +* [runtime fields](../../../manage-data/data-store/mapping/map-runtime-field.md) +* [`_source` field](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html) + +{{es}} 5 indices with mappings that have [multiple mapping types](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/removal-of-types.html) are collapsed together on a best-effort basis before they are imported. + +In case the auto-import of mappings does not work, or the new {{es}} version can’t make sense of the mapping, it falls back to importing the index without the mapping, but stores the original mapping in the [_meta](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-meta-field.html) section of the imported index. The legacy mapping can then be introspected using the [GET mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-get-mapping.html) API and an updated mapping can be manually put in place using the [update mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html) API, copying and adapting relevant sections of the legacy mapping to work with the current {{es}} version. While auto-import is expected to work in most cases, failures of doing so should be [raised](https://github.com/elastic/elasticsearch/issues/new/choose) with the Elastic team for future improvements. + + +## Supported APIs [_supported_apis] + +Archive indices are read-only, and provide data access via the [search](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) and [field capabilities](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-field-caps.html) APIs. They do not support the [Get API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html) nor any write APIs. + +Archive indices allow running queries as well as aggregations in so far as they are [supported by the given field type](#archive-indices-supported-field-types). + +Due to `_source` access the data can also be [reindexed](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) to a new index that has full compatibility with the current {{es}} version. + + +## How to upgrade older {{es}} 5 or 6 clusters? [_how_to_upgrade_older_es_5_or_6_clusters] + +Take a snapshot of the indices in the old cluster, delete indices that are not directly supported by ES 8 (i.e. indices older than 7.0), upgrade the cluster without the old indices, and then [restore](https://www.elastic.co/guide/en/elasticsearch/reference/current/restore-snapshot-api.html) the legacy indices from the snapshot or [mount](https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots-api-mount-snapshot.html) them via searchable snapshots. + +In the future, we plan on streamlining the upgrade process going forward, making it easier to take legacy indices along when going to future major {{es}} versions. + diff --git a/deploy-manage/upgrade/internal-upgrade-processes.md b/deploy-manage/upgrade/internal-upgrade-processes.md new file mode 100644 index 000000000..fabe5e160 --- /dev/null +++ b/deploy-manage/upgrade/internal-upgrade-processes.md @@ -0,0 +1,3 @@ +# Internal upgrade processes + +% What needs to be done: Write from scratch \ No newline at end of file diff --git a/deploy-manage/upgrade/internal-upgrade-processes/saved-object-migrations.md b/deploy-manage/upgrade/internal-upgrade-processes/saved-object-migrations.md new file mode 100644 index 000000000..731d25329 --- /dev/null +++ b/deploy-manage/upgrade/internal-upgrade-processes/saved-object-migrations.md @@ -0,0 +1,52 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/saved-object-migrations.html +--- + +# Saved object migrations [saved-object-migrations] + +Each time you upgrade {{kib}}, an upgrade migration is performed to ensure that all [saved objects](../../../explore-analyze/find-and-organize/saved-objects.md) are compatible with the new version. + +::::{note} +{{kib}} includes an [**Upgrade Assistant**](../prepare-to-upgrade/upgrade-assistant.md) to help you prepare for an upgrade. To access the assistant, go to **Stack Management > Upgrade Assistant**. +:::: + + +::::{warning} +{{kib}} 7.12.0 and later uses a new migration process and index naming scheme. Before you upgrade, read the documentation for your version of {{kib}}. +:::: + + +::::{warning} +The `kibana.index` and `xpack.tasks.index` configuration settings are obsolete and no longer taken into account in 8.x. If you are using custom index names, please perform the necessary adaptations before attempting to upgrade to 8.x. +:::: + + + +## How saved objects migrations work [upgrade-migrations-process] + +When you start a new {{kib}} installation, an upgrade migration is performed before starting plugins or serving HTTP traffic. Before you upgrade, shut down old nodes to prevent losing acknowledged writes. To reduce the likelihood of old nodes losing acknowledged writes, {{kib}} 7.12.0 and later adds a write block to the outdated index. + +Saved objects are stored in multiple indices. Whilst all of them start with the `.kibana*` prefix, other `.kibana*` indices exist, which are not used to store saved objects. The following tables lists the saved objects indices used by each {{kib}} version. + +| Upgrading from version | Index | Aliases | +| --- | --- | --- | +| 6.5.0 through 7.3.x | `.kibana_N` | `.kibana` | +| 7.4.0 through 7.11.x | `.kibana_N`
`.kibana_task_manager_N` | `.kibana`
`.kibana_task_manager` | +| 7.11.x through 8.7.x | `.kibana_{{kibana_version}}_001`
`.kibana_task_manager_{{kibana_version}}_001` | `.kibana`, `.kibana_{{kibana_version}}`
`.kibana_task_manager`, `.kibana_task_manager_{{kibana_version}}` | +| 8.8.0+ | `.kibana_{{kibana_version}}_001`
`.kibana_alerting_cases_{{kibana_version}}_001``.kibana_analytics_{{kibana_version}}_001``.kibana_ingest_{{kibana_version}}_001``.kibana_task_manager_{{kibana_version}}_001``.kibana_security_solution_{{kibana_version}}_001` | `.kibana`, `.kibana_{{kibana_version}}`
`.kibana_alerting_cases`, `.kibana_alerting_cases_{{kibana_version}}``.kibana_analytics`, `.kibana_analytics_{{kibana_version}}``.kibana_ingest`, `.kibana_ingest_{{kibana_version}}``.kibana_task_manager`, `.kibana_task_manager_{{kibana_version}}``.kibana_security_solution`, `.kibana_security_solution_{{kibana_version}}` | + +Starting on 7.11.0, each of the saved objects indices has a couple of aliases, e.g. the `.kibana_8.8.0_001` index has a *default* alias `.kibana` and a *version* alias `.kibana_8.8.0`. The *default* aliases (e.g. `.kibana` and `.kibana_task_manager`) always point to the most up-to-date saved object indices. Then, *version* aliases are aligned with the deployed {{kib}} version. + +Starting on 8.6.0, index names aren’t necessarily aligned with the deployed {{kib}} version. When updates on a certain index are compatible, {{kib}} will keep the existing index instead of creating a new one. This allows for a more efficient upgrade process. The following example illustrates a completely valid state for a 8.8.0 deployment: + +* `.kibana_8.8.0_001` index, with `.kibana` and `.kibana_8.8.0` aliases. +* `.kibana_task_manager_8.7.0_001` index, with `.kibana_task_manager` and `.kibana_task_manager_8.8.0` aliases. + +Starting on 8.8.0, {{kib}} splits the main saved object index into multiple ones, as depicted on the table above. When upgrading from a previous version, the {{kib}} migration process will reindex some saved objects from the `.kibana` index into the new indices, depending on their types. Note that the `.kibana` index still exists, and it continues to store multiple saved object types. + + +## Old {{kib}} indices [upgrade-migrations-old-indices] + +As a deployment is gradually upgraded, multiple {{kib}} indices are created in {{es}}: (`.kibana_1`, `.kibana_2`, `.kibana_7.12.0_001`, `.kibana_7.13.0_001`, `.kibana_8.0.0_001` etc). {{kib}} only uses those indices that the *default* and *version* aliases point to. The other, older {{kib}} saved object indices can be safely deleted, but are left around as a matter of historical record, and to facilitate rolling {{kib}} back to a previous version. + diff --git a/deploy-manage/upgrade/orchestrator.md b/deploy-manage/upgrade/orchestrator.md new file mode 100644 index 000000000..e3658756f --- /dev/null +++ b/deploy-manage/upgrade/orchestrator.md @@ -0,0 +1,5 @@ +# Upgrade your orchestrator + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/355 \ No newline at end of file diff --git a/deploy-manage/upgrade/orchestrator/upgrade-cloud-enterprise.md b/deploy-manage/upgrade/orchestrator/upgrade-cloud-enterprise.md new file mode 100644 index 000000000..34181933b --- /dev/null +++ b/deploy-manage/upgrade/orchestrator/upgrade-cloud-enterprise.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-upgrade.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece_re_running_the_ece_upgrade.html +--- + +# Upgrade Elastic Cloud Enterprise + +% What needs to be done: Refine + +% GitHub issue: ? + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-upgrade.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece_re_running_the_ece_upgrade.md \ No newline at end of file diff --git a/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md b/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md new file mode 100644 index 000000000..71b91a0e0 --- /dev/null +++ b/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md @@ -0,0 +1,131 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-upgrading-eck.html +--- + +# Upgrade Elastic Cloud on Kubernetes [k8s-upgrading-eck] + +This page provides instructions on how to upgrade the ECK operator. + +For upgrades of Elastic Stack applications like Elasticsearch or Kibana, check [Upgrade the Elastic Stack version](../deployment-or-cluster.md). + + +## Before you upgrade to ECK 2.16.1 [k8s-ga-upgrade] + +The upgrade process results in an update to all the existing managed resources. This potentially triggers a rolling restart of all Elasticsearch and Kibana pods. This [list](#k8s-beta-to-ga-rolling-restart) details the affected target versions that will cause a rolling restart. If you have a large Elasticsearch cluster or multiple Elastic Stack deployments, the rolling restart could cause a performance degradation. When you plan to upgrade ECK for production workloads, take into consideration the time required to upgrade the ECK operator plus the time required to roll all managed workloads and Elasticsearch clusters. Check for more information on how to [control the rolling restarts during the upgrade](#k8s-beta-to-ga-rolling-restart). + +Before upgrading, refer to the [release notes](https://www.elastic.co/guide/en/cloud-on-k8s/current/release-notes-2.16.1.html) to make sure that the release does not contain any breaking changes that could affect you. The [release highlights document](https://www.elastic.co/guide/en/cloud-on-k8s/current/release-highlights-2.16.1.html) provides more details and possible workarounds for any breaking changes or known issues in each release. + +Note that the release notes and highlights only list the changes since the last release. If during the upgrade you skip any intermediate versions and go for example from 1.0.0 directly to 2.16.1, review the release notes and highlights of each of the skipped releases to understand all the breaking changes you might encounter during and after the upgrade. + +::::{warning} +When upgrading always ensure that the version of the CRDs installed in the cluster matches the version of the operator. If you are using Helm, the CRDs are upgraded automatically as part of the Helm chart. If you are using the YAML manifests, you must upgrade the CRDs manually. Running differing versions of the CRDs and the operator is not a supported configuration and can lead to unexpected behavior. +:::: + + + +## Upgrade instructions [k8s-upgrade-instructions] + + +### Upgrading from ECK 1.6 or earlier [k8s_upgrading_from_eck_1_6_or_earlier] + +Release 1.7.0 moved the [CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) (CRD) used by ECK to the v1 version. If you upgrade from a previous version of ECK, the new version of the CRDs replaces the existing CRDs. If you cannot remove the current ECK installation because you have production workloads that must not be deleted, the following approach is recommended. + +```shell +kubectl replace -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml +``` + +::::{note} +If you skipped a release in which new CRDs where introduced, you will get an error message similar to `Error from server (NotFound): error when replacing "config/crds.yaml": customresourcedefinitions.apiextensions.k8s.io ... not found`. To add the missing CRDs run + +```shell +kubectl create -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml +``` + +:::: + + +Then upgrade the remaining objects with the operator manifest: + +```shell +kubectl apply -f https://download.elastic.co/downloads/eck/2.16.1/operator.yaml +``` + +```shell +helm upgrade elastic-operator elastic/eck-operator-crds -n elastic-system --force +``` + +Then upgrade the main chart as usual: + +```shell +helm upgrade elastic-operator elastic/eck-operator -n elastic-system +``` + +If you are using ECK through an OLM-managed distribution channel like [operatorhub.io](https://operatorhub.io) or the OpenShift OperatorHub then the CRD version upgrade will be handled by OLM for you and you do not need to take special action. + + +### Upgrading from ECK 1.9 or earlier [k8s_upgrading_from_eck_1_9_or_earlier] + +Operator Lifecycle Manager (OLM) and OpenShift OperatorHub users that run with automatic upgrades enabled, are advised to set the `set-default-security-context` [operator flag](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-operator-config.html) explicitly before upgrading to ECK 2.0 or later. If not set, ECK can fail to [auto-detect](https://github.com/elastic/cloud-on-k8s/issues/5061) the correct security context configuration and Elasticsearch Pods may not be allowed to run. + + +### Upgrading from ECK 2.0 or later [k8s_upgrading_from_eck_2_0_or_later] + +There are no special instructions to follow if you upgrade from any 2.x version to 2.16.1. Use the upgrade method applicable to your installation method of choice. + +```shell +kubectl apply -f https://download.elastic.co/downloads/eck/2.16.1/crds.yaml +kubectl apply -f https://download.elastic.co/downloads/eck/2.16.1/operator.yaml +``` + +```shell +helm upgrade elastic-operator elastic/eck-operator -n elastic-system +``` + +This will update the ECK installation to the latest binary and update the CRDs and other ECK resources in the cluster. + + +## Control rolling restarts during the upgrade [k8s-beta-to-ga-rolling-restart] + +Upgrading the operator results in a one-time update to existing managed resources in the cluster. This potentially triggers a rolling restart of pods by Kubernetes to apply those changes. The following list contains the ECK operator versions that would cause a rolling restart after they have been installed. + +``` +1.6, 1.9, 2.0, 2.1, 2.2, 2.4, 2.5, 2.6, 2.7, 2.8, 2.14 +``` +::::{note} +Stepping over one of these versions, for example, upgrading ECK from 2.6 to 2.9, still triggers a rolling restart. +:::: + + +If you have a very large Elasticsearch cluster or multiple Elastic Stack deployments, this rolling restart might be disruptive or inconvenient. To have more control over when the pods belonging to a particular deployment should be restarted, you can [add an annotation](../../../troubleshoot/deployments/cloud-on-k8s/troubleshooting-methods.md#k8s-exclude-resource) to the corresponding resources to temporarily exclude them from being managed by the operator. When the time is convenient, you can remove the annotation and let the rolling restart go through. + +::::{warning} +Once a resource is excluded from being managed by ECK, you will not be able to add/remove nodes, upgrade Stack version, or perform other [orchestration tasks](../../deploy/cloud-on-k8s/configure-deployments.md) by updating the resource manifest. You must remember to remove the exclusion to ensure that your Elastic Stack deployment is continually monitored and managed by the operator. +:::: + + +```shell +ANNOTATION='eck.k8s.elastic.co/managed=false' + +# Exclude a single Elasticsearch resource named "quickstart" +kubectl annotate --overwrite elasticsearch quickstart $ANNOTATION + +# Exclude all resources in the current namespace +kubectl annotate --overwrite elastic --all $ANNOTATION + +# Exclude all resources in all of the namespaces: +for NS in $(kubectl get ns -o=custom-columns='NAME:.metadata.name' --no-headers); do kubectl annotate --overwrite elastic --all $ANNOTATION -n $NS; done +``` + +Once the operator has been upgraded and you are ready to let the resource become managed again (triggering a rolling restart of pods in the process), remove the annotation. + +```shell +RM_ANNOTATION='eck.k8s.elastic.co/managed-' + +# Resume management of a single Elasticsearch cluster named "quickstart" +kubectl annotate elasticsearch quickstart $RM_ANNOTATION +``` + +::::{note} +The ECK source repository contains a [shell script](https://github.com/elastic/cloud-on-k8s/tree/2.16/hack/annotator) to assist with mass addition/deletion of annotations. +:::: diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md new file mode 100644 index 000000000..0ea12c3f8 --- /dev/null +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -0,0 +1,5 @@ +# Prepare to upgrade + +% What needs to be done: Write from scratch + +% Scope notes: Prerequisites and requirements \ No newline at end of file diff --git a/deploy-manage/upgrade/prepare-to-upgrade/index-compatibility.md b/deploy-manage/upgrade/prepare-to-upgrade/index-compatibility.md new file mode 100644 index 000000000..7d8de2c69 --- /dev/null +++ b/deploy-manage/upgrade/prepare-to-upgrade/index-compatibility.md @@ -0,0 +1,39 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html +--- + +# Index compatibility [setup-upgrade] + +::::{important} +:name: upgrade-pre-release + +This documentation is for {{es}} 9.0.0-beta1, which is not yet released. You can upgrade from a previously released version to a pre-release build, if following a supported upgrade path. Upgrading from a pre-release build to any other build is not supported, and can result in errors or silent data loss. If you run a pre-release build for testing, discard the contents of the cluster before upgrading to another build of {{es}}. +:::: + + +{{es}} clusters can usually be upgraded one node at a time so upgrading does not interrupt service. For upgrade instructions, refer to [Upgrading to Elastic 9.0.0-beta1](../deployment-or-cluster.md). + +::::{admonition} Upgrade from 7.x +:class: important + +To upgrade to 9.0.0-beta1 from 7.16 or an earlier version, **you must first upgrade to 8.17**, even if you opt to do a full-cluster restart instead of a rolling upgrade. This enables you to use the **Upgrade Assistant** to identify and resolve issues, reindex indices created before 7.0, and then perform a rolling upgrade. You must resolve all critical issues before proceeding with the upgrade. For instructions, refer to [Prepare to upgrade from 7.x](../deployment-or-cluster.md#prepare-to-upgrade). +:::: + + + +## Index compatibility [upgrade-index-compatibility] + +{{es}} has full query and write support for indices created in the previous major version. If you have indices created in 6.x or earlier, you might use the [archive functionality](../deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to import them into newer {{es}} versions, or you must reindex or delete them before upgrading to 9.0.0-beta1. {{es}} nodes will fail to start if incompatible indices are present. Snapshots of 6.x or earlier indices can only restored using the [archive functionality](../deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to a 8.x cluster even if they were created by a 7.x cluster. The **Upgrade Assistant** in 8.17 identifies any indices that need to be reindexed or removed. + + +## REST API compatibility [upgrade-rest-api-compatibility] + +[REST API compatibility](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-api-compatibility.html) is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. + + +## FIPS Compliance and Java 17 [upgrade-fips-java17] + +{{es}} 8.0+ requires Java 17 or later. {{es}} 8.13+ has been tested with [Bouncy Castle](https://www.bouncycastle.org/java.md)'s Java 17 [certified](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4616) FIPS implementation and is the recommended Java security provider when running {{es}} in FIPS 140-2 mode. Note - {{es}} does not ship with a FIPS certified security provider and requires explicit installation and configuration. + +Alternatively, consider using {{ess}} in the [FedRAMP-certified GovCloud region](https://www.elastic.co/industries/public-sector/fedramp). diff --git a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md new file mode 100644 index 000000000..b7fc01ac5 --- /dev/null +++ b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md @@ -0,0 +1,32 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/upgrade-assistant.html +--- + +# Upgrade Assistant [upgrade-assistant] + +The Upgrade Assistant helps you prepare for your upgrade to the next version of the {{stack}}. To access the assistant, go to **{{stack-manage-app}} > Upgrade Assistant**. + +The assistant identifies deprecated settings in your configuration and guides you through the process of resolving issues if any deprecated features are enabled. + + +## Required permissions [_required_permissions_11] + +The `manage` cluster privilege is required to access the **Upgrade assistant**. Additional privileges may be needed to perform certain actions. + + +## Feature set [_feature_set] + +Some features of the Upgrade assistant are only needed when upgrading to a new major version. The feature set enabled by default are those for the very next version from the one Kibana currently runs on. + + +## Deprecations [_deprecations] + +The Upgrade assistant pulls information about deprecations from the following sources: + +* Elasticsearch Deprecation Info API +* Elasticsearch deprecation logs +* Kibana deprecations API + +For more information about Upgrade Assistant APIs, refer to [Upgrade Assistant APIs](https://www.elastic.co/guide/en/kibana/current/upgrade-assistant-api.html). + diff --git a/deploy-manage/users-roles.md b/deploy-manage/users-roles.md new file mode 100644 index 000000000..6e47818a6 --- /dev/null +++ b/deploy-manage/users-roles.md @@ -0,0 +1,20 @@ +--- +navigation_title: "Access" +mapped_pages: + - https://www.elastic.co/guide/en/serverless/current/project-settings-access.html +--- + + + +# Manage users and roles [project-settings-access] + + +Go to **Project settings**, then ** Management** to manage your indices, data views, saved objects, settings, and more. You can also open Management by using the [global search field](../explore-analyze/overview/kibana-quickstart.md#_finding_your_apps_and_objects). + +Access to individual features is governed by Elastic user roles. Consult your administrator if you do not have the appropriate access. To learn more about roles, refer to [Assign user roles and privileges](users-roles/cloud-organization/manage-users.md#general-assign-user-roles). + +| Feature | Description | Available in | +| --- | --- | --- | +| [Organization members](api-keys/serverless-project-api-keys.md) | Invite and manage your team’s access to your organization. | [![Elasticsearch](../images/serverless-es-badge.svg "")](../solutions/search.md)[![Observability](../images/serverless-obs-badge.svg "")](../solutions/observability.md)[![Security](../images/serverless-sec-badge.svg "")](../solutions/security/elastic-security-serverless.md) | +| [Project API keys](api-keys/serverless-project-api-keys.md) | Create and manage keys that can interact with your project’s data. | [![Elasticsearch](../images/serverless-es-badge.svg "")](../solutions/search.md)[![Observability](../images/serverless-obs-badge.svg "")](../solutions/observability.md)[![Security](../images/serverless-sec-badge.svg "")](../solutions/security/elastic-security-serverless.md) | +| [Custom roles](users-roles/cloud-organization/user-roles.md) | Create and manage custom roles for your users. | [![Elasticsearch](../images/serverless-es-badge.svg "")](../solutions/search.md)[![Security](../images/serverless-sec-badge.svg "")](../solutions/security/elastic-security-serverless.md) | diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator.md new file mode 100644 index 000000000..4488b5e2a --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator.md @@ -0,0 +1,5 @@ +# Elastic Cloud Enterprise orchestrator users + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 \ No newline at end of file diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/active-directory.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/active-directory.md new file mode 100644 index 000000000..d688c3c2e --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/active-directory.md @@ -0,0 +1,126 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-create-ad-profiles.html +--- + +# Active Directory [ece-create-ad-profiles] + +If you use an Active Directory (AD) server to authenticate users, you can specify the servers, parameters, and the search modes that Elastic Cloud Enterprise uses to locate user credentials. There are several sections to the profile: + +* Specify the [general AD settings](#ece-ad-general-settings). +* Optional: Prepare the [trusted CA certificates](#ece-prepare-ad-certificates). +* Supply the [bind credentials](#ece-supply-ad-bind-credentials). +* Select the [search mode and group search](#ece-ad-search-mode) settings. +* Create [role mappings](#ece-ad-role-mapping), either to all users that match the profile or assign roles to specific groups. +* Add any [custom configuration](#ece-ad-custom-configuration) advanced settings to the YAML file. + +$$$ece-ad-general-settings$$$Begin the provider profile by adding the general settings: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Users** and then **Authentication providers**. +3. From the **Add provider** drop-down menu, select **Active Directory**. +4. Provide a unique profile name. This name becomes the realm ID, with any spaces replaced by hyphens. + + The name can be changed, but the realm ID cannot. The realm ID becomes part of the [certificate bundle](ldap.md#ece-prepare-ldap-certificates). + +5. Add one or more LDAP URLs pointing to Active Directory domain controller servers. You can use LDAP or LDAPS, but you can’t use a mix of types. + + Example: `ldaps://ad.domain.com:636` + +6. Choose how you want your load balancing to work: + + Failover + : The LDAP URLs are used in the order they were entered. The first server that we can connect to gets used for all subsequent connections. If the connection to that server fails, the next available will be used for all subsequent connections. + + DNS failover + : The request is sent to a DNS hostname and the associated server IP addresses are searched in the order they are listed by the DNS Server. Each request starts at the beginning of the retrieved IP address list, regardless of previous failures. + + Round robin + : Connections continuously iterate through the list of provided URLs until a connection can be made. + + DNS round robin + : The request is sent to a DNS hostname that is configured to with multiple IP addresses, rotating through until a connection is made. + +7. Provide the top-level domain name. + + +## Prepare certificates [ece-prepare-ad-certificates] + +Though optional, you can add one or more certificate authorities (CAs) to validate the server certificate that the Domain Controller uses for SSL/TLS. Connecting through SSL/TLS ensures that the identity of the AD server is authenticated before Elastic Cloud Enterprise transmits the user credentials and that the contents of the connection are encrypted. + +1. Provide the URL to the ZIP file that contains a keystore with the CA certificate(s). + + The bundle should be a ZIP file containing a single `keystore.ks` file in the directory `/active_directory/:id/truststore`, where `:id` is the value of the **Realm ID** field created in the [General settings](#ece-ad-general-settings). The keystore file can either be a JKS or a PKCS#12 keystore, but the name of the file should be `keystore.ks`. + + ::::{important} + Don’t use the same URL to serve a new version of the ZIP file as otherwise the new version may not be picked up. + :::: + +2. Select a keystore type. +3. If the keystore is password protected, add the password to decrypt the keystore. + + +## Supply the bind credentials [ece-supply-ad-bind-credentials] + +You can either select **Bind anonymously** for user searches or you must specify the distinguished name (DN) of the user to bind and the bind password. When **Bind anonymously** is selected, all requests to Active Directory will be performed with the credentials of the authenticating user. In the case that `Bind DN` and `Bind Password` are provided, requests are performed on behalf of this bind user. This can be useful in cases where the regular users can’t access all of the necessary items within Active Directory. + + +## Configure the user search settings [ece-ad-search-mode] + +You can configure how Elastic Cloud Enterprise will search for users in the Active Directory + +To configure the user search: + +1. Provide the **Base DN** as the base context where users are located in the Active Directory. +2. Set the **Search scope**: + + Sub-tree + : Searches all entries at all levels *under* the base DN, including the base DN itself. + + One level + : Searches for objects one level under the `Base DN` but not the `Base DN` or entries in lower levels. + + Base + : Searches only the entry defined as `Base DN`. + +3. Optional: Specify an additional LDAP filter, used to lookup a user given a username. The default filter looks up user objects in Active Directory where the username entered by the user matches `sAMAccountName` or `userPrincipalName` attributes. + + +## Configure the group search settings [ece-ad-search-groups] + +You can configure how Elastic Cloud Enterprise will search for groups in the Active Directory + +To configure the group search: + +1. Provide the **Base DN** as the base context where groups are located in the Active Directory. +2. Set the **Search scope**: + + Sub-tree + : Searches all entries at all levels *under* the base DN, including the base DN itself. + + One level + : Searches for objects one level under the `Base DN` but not the `Base DN` or entries in lower levels. + + Base + : Searches only the entry defined as `Base DN`. + + + +## Create role mappings [ece-ad-role-mapping] + +When a user is authenticated, the role mapping assigns them roles in Elastic Cloud Enterprise. + +To assign all authenticated users a single role, select one of the **Default roles**. + +To assign roles according to the **User DN** of the user or **Group DN** of the group they belong to, use the **Add role mapping rule** fields. + + +## Custom configuration [ece-ad-custom-configuration] + +You can add any additional settings to the **Advanced configuration** YAML file. For example, if you need to ignore the SSL check for the SSL certificate of the Domain Controller in a testing environment, you might add `ssl.verification_mode: none`. Note that all keys should omit the `xpack.security.authc.realms.active_directory.$realm_id` prefix that is required in `elasticsearch.yml`, as ECE will insert this itself and automatically account for any differences in format across Elasticsearch versions. + +::::{important} +API keys created by Active Directory users are not automatically deleted or disabled when the user is deleted or disabled in Active Directory. When you delete a user in Active Directory, make sure to also remove the user’s API key or delete the user in ECE. +:::: + + diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md new file mode 100644 index 000000000..d303b8032 --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md @@ -0,0 +1,16 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-deployment-sso.html +--- + +# Configure SSO for deployments [ece-deployment-sso] + +The single sign-on (SSO) feature in ECE allows `platform admins` and `deployment managers` to log in to their Kibana and Enterprise Search instances automatically once they are logged in to ECE. + +::::{note} +Single sign-on is not available for system deployments; you need to use credentials to log in to them. +:::: + + +To use single sign-on you first need to [configure the API base URL](../../deploy/cloud-enterprise/change-ece-api-url.md). Once this is set, all new deployments are SSO-enabled automatically, and existing deployments become SSO-enabled after any plan changes are applied. + diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/ldap.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/ldap.md new file mode 100644 index 000000000..3524bed3c --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/ldap.md @@ -0,0 +1,129 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-create-ldap-profiles.html +--- + +# LDAP [ece-create-ldap-profiles] + +If you use a Lightweight Directory Access Protocol (LDAP) server to authenticate users, you can specify the servers, parameters, and the search modes that Elastic Cloud Enterprise uses to locate user credentials. There are several sections to the profile: + +* Specify the [general LDAP settings](#ece-ldap-general-settings). +* Optional: Prepare the [trusted CA certificates](#ece-prepare-ldap-certificates). +* Supply the [bind credentials](#ece-supply-ldap-bind-credentials). +* Select the [search mode and group search](#ece-ldap-search-mode) settings. +* Create [role mappings](#ece-ldap-role-mapping), either to all users that match the profile or assign roles to specific groups. +* Add any [custom configuration](#ece-ldap-custom-configuration) advanced settings to the YAML file. + +$$$ece-ldap-general-settings$$$Begin the provider profile by adding the general settings: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Users** and then **Authentication providers**. +3. From the **Add provider** drop-down menu, select **LDAP**. +4. Provide a unique profile name. This name becomes the realm ID, with any spaces replaced by hyphens. + + The name can be changed, but the realm ID cannot. The realm ID becomes part of the [certificate bundle](#ece-prepare-ldap-certificates). + +5. Add one or more LDAP server URLs and the port. You can use LDAP or LDAPS, but you can’t use a mix of types. + + Example: `ldaps://ldap.example.com:636` + +6. Choose how you want your load balancing to work: + + Failover + : The LDAP URLs are used in the order they were entered. The first LDAP server that we can connect to gets used for all subsequent connections. If the connection to that server fails, the next available will be used for all subsequent connections. + + DNS failover + : The request is sent to a DNS hostname and the associated server IP addresses are searched in the order they are listed by the DNS Server. Each request starts at the beginning of the retrieved IP address list, regardless of previous failures. + + Round robin + : Connections continuously iterate through the list of provided URLs until a connection can be made. + + DNS round robin + : The request is sent to a DNS hostname that is configured to with multiple IP addresses, rotating through until a connection is made. + + + +## Prepare certificates [ece-prepare-ldap-certificates] + +Though optional, you can add one or more certificate authorities (CAs) to validate the server certificate that the Domain Controller uses for SSL/TLS. Connecting through SSL/TLS ensures that the identity of the AD server is authenticated before Elastic Cloud Enterprise transmits the user credentials and that the contents of the connection are encrypted. + +1. Provide the URL to the ZIP file that contains a keystore with the CA certificate(s). + + The bundle should be a ZIP file containing a single `keystore.ks` file in the directory `/ldap/:id/truststore`, where `:id` is the value of the **Realm ID** field created in the [General settings](active-directory.md#ece-ad-general-settings). The keystore file can either be a JKS or a PKCS#12 keystore, but the name of the file should be `keystore.ks`. + +2. Select a keystore type. +3. If the keystore is password protected, add the password to decrypt the keystore. + + +## Supply the bind credentials [ece-supply-ldap-bind-credentials] + +You can either select **Bind anonymously** for user searches or you must specify the distinguished name (DN) of the user to bind and the bind password. When **Bind anonymously** is selected, all requests to the LDAP server will be performed with the credentials of the authenticating user. In the case that `Bind DN` and `Bind Password` are provided, requests are performed on behalf of this bind user. This can be useful in cases where the regular users can’t access all of the necessary items within your LDAP server. + +For user search templates, bind settings are not used even if configured. + + +## Configure the user search settings [ece-ldap-search-mode] + +The profile supports two modes of operation for searching users in the LDAP server, User search mode and Template mode. + +To configure the user search: + +1. Provide the **Base DN** as the base context where users are located in the LDAP server. +2. Set the **Search scope**: + + Sub-tree + : Searches all entries at all levels *under* the base DN, including the base DN itself. + + One level + : Searches for objects one level under the `Base DN` but not the `Base DN` or entries in lower levels. + + Base + : Searches only the entry defined as `Base DN`. + +3. Optional: Specify an additional LDAP filter used to search the directory in attempts to match an entry with the username provided by the user. Defaults to `(uid={{0}})`. `{{0}}` is substituted with the username provided by the user for authentication. +4. Optional: Specify the attribute to examine on the user object in LDAP for group membership. If any Group Search settings are specified, this setting is ignored. Defaults to `memberOf`. + +To configure the template search: + +1. Select **Template**. +2. Provide one or more **User DN templates**. This DN template can contain a single `{{0}}` which will be replaced by the username the user enters for authentication. For example: `cn={{0}}, ou=users, o=marketing, dc=example, dc=com` + + +## Configure the group search settings [ece-ldap-search-groups] + +You can configure how Elastic Cloud Enterprise searches for groups in the LDAP Server + +To configure the group search: + +1. Provide the **Base DN** as the base context where groups are located in the LDAP server. +2. Set the **Search scope**: + + Sub-tree + : Searches all entries at all levels *under* the base DN, including the base DN itself. + + One level + : Searches for objects one level under the `Base DN` but not the `Base DN` or entries in lower levels. + + Base + : Searches only the entry defined as `Base DN`. + + + +## Create role mappings [ece-ldap-role-mapping] + +When a user is authenticated, the role mapping assigns them roles in Elastic Cloud Enterprise. + +To assign all authenticated users a single role, select one of the **Default roles**. + +To assign roles according to the **User DN** of the user or **Group DN** of the group they belong to, use the **Add role mapping rule** fields. + + +## Custom configuration [ece-ldap-custom-configuration] + +You can add any additional settings to the **Advanced configuration** YAML file. For example, if you need to ignore the SSL check in a testing environment, you might add `ssl.verification_mode: none`. Note that all entries added should omit `xpack.security.authc.realms.ldap.$realm_id` prefix, as ECE will insert this itself and automatically account for any differences in format across Elasticsearch versions. + +::::{important} +API keys created by LDAP users are not automatically deleted or disabled when the user is deleted or disabled in LDAP. When you delete a user in LDAP, make sure to also remove the user’s API key or delete the user in ECE. +:::: + + diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md new file mode 100644 index 000000000..e5dfd7941 --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md @@ -0,0 +1,54 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-manage-system-passwords.html +--- + +# Manage system passwords [ece-manage-system-passwords] + +At the end of the Elastic Cloud Enterprise installation process on the first host, you are provided with the URL and user credentials for the administration console users `admin` and `readonly`. You use this information to log into the Cloud UI. Both users can access all parts of the Cloud UI, but only the `admin` user can make changes. We recommend that you keep this information secure. + + +## Retrieve user passwords [ece-retrieve-passwords] + +If you need to retrieve the system passwords at a later point, you can issue one of the following commands from the first host you installed on (requires that you have [jq](https://stedolan.github.io/jq/download/) installed). + +If you specified a different host storage path during installation, change `/mnt/data/elastic` to the path your installation is using. These commands require that the secrets file exists on the host where you run the command. (Don’t have a secrets file? You can also [reset the passwords](#ece-reset-passwords).) + +To retrieve the password for the `admin` user: + +```sh +jq -r '.adminconsole_root_password' /mnt/data/elastic/bootstrap-state/bootstrap-secrets.json +``` + +To retrieve the password for the `readonly` user: + +```sh +jq -r '.adminconsole_readonly_password' /mnt/data/elastic/bootstrap-state/bootstrap-secrets.json +``` + +You access the Cloud UI on port 12400 or port 12443 at IP address of the first host you installed on ([https://192.168.50.10:12443](https://192.168.50.10:12443), for example). + + +## Reset user passwords [ece-reset-passwords] + +You might need to reset the Cloud UI passwords for one of the following reasons: + +* To change the passwords for the `admin` and `readonly` users after installing Elastic Cloud Enterprise or periodically as part of your standard operating procedures. +* To reset passwords if you think they might have become compromised. + +The passwords for these users are stored in `/mnt/data/elastic/bootstrap-state/bootstrap-secrets.json` along with other secrets (unless you specified a different host storage path). + +To reset the password for the user `admim` on the administration console based on the secrets in `/mnt/data/elastic/bootstrap-state/bootstrap-secrets.json`: + +```sh +bash elastic-cloud-enterprise.sh reset-adminconsole-password --user admin +``` + +To reset the password for the `admin` user if no secrets file exists: + +```sh +bash elastic-cloud-enterprise.sh reset-adminconsole-password +``` + +For additional usage examples, check [`elastic-cloud-enterprise.sh reset-adminconsole-password` Reference](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-installation-script-reset.html). + diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md new file mode 100644 index 000000000..91c55f16e --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md @@ -0,0 +1,93 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-configure-rbac.html +--- + +# Manage users and roles [ece-configure-rbac] + +:::{image} ../../../images/cloud-enterprise-ece-rbac-intro.png +:alt: User groups +::: + +Role-based access control (RBAC) provides a way to add multiple users and restrict their access to specific platform resources. In addition to the system `admin` and `readonly` users, you can utilize pre-built roles to control access to platform operations, deployment assets, or API calls. + +Implementing RBAC in your environment benefits you in several ways: + +* Streamlines the process of assigning or updating privileges for users as a group, instead of painstakingly managing individual users. +* Limits access to just what’s needed for that user’s job function, isolating company assets. +* Assists with compliance to security and data standards or laws. +* Adds multiple users by: + + * Creating [native users](native-user-authentication.md) locally. + * Integrating with third-party authentication providers like [ActiveDirectory](active-directory.md), [LDAP](ldap.md) or [SAML](saml.md). + + +::::{important} +With RBAC, interacting with API endpoints now requires a [bearer token](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-api-command-line.html) or [API key](../../api-keys/elastic-cloud-enterprise-api-keys.md#ece-api-keys). +:::: + + + +## Before you begin [ece_before_you_begin_8] + +To prepare for RBAC, you should review the Elastic Cloud Enterprise [limitations and known issues](https://www.elastic.co/guide/en/cloud-enterprise/current/ece-limitations.html). + + +## Available roles and permissions [ece-user-role-permissions] + +Beyond the system users, there are several pre-built roles that you can apply to additional users: + +Platform admin +: Same access as the `admin` system user. + +Platform viewer +: Same access as the `readonly` system user, which includes being able to view secret and sensitive settings. + +Deployment manager +: Can create and manage non-system deployments, specify keystore security settings, and establish cross-cluster remote relationships. They can also reset the `elastic` password. + +Deployment viewer +: Can view non-system deployments, including their activity. Can prepare the diagnostic bundle, inspect the files, and download the bundle as a ZIP file. + + +## Configure security deployment [ece-configure-security-deployment] + +The security deployment is a system deployment that manages all of the Elastic Cloud Enterprise authentication and permissions. It is created automatically during installation. + +::::{important} +We strongly recommend using three availability zones with at least 1 GB Elasticsearch nodes. You can scale up if you expect a heavy authentication workload. +:::: + + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Deployments** a select the **security-cluster**. +3. Configure regular snapshots of the security deployment. This is critical if you plan to create any native users. +4. Optional: [Enable monitoring](../../monitor/stack-monitoring/enable-stack-monitoring-on-ece-deployments.md) on the security deployment to a dedicated monitoring deployment. + +If you have authentication issues, you check out the security deployment Elasticsearch logs. + + +## Change the order of provider profiles [ece-provider-order] + +Elastic Cloud Enterprise performs authentication checks against the configured providers, in order. When a match is found, the user search stops. The roles specified by that first profile match dictate which permissions the user is granted—​regardless of what permissions might be available in another, lower-order profile. + +To change the provider order: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Users** and then **Authentication providers**. +3. Use the carets to update the provider order. + +Changing the order is a configuration change and you can’t make changes to other providers until it is complete. + + +## Change the user settings [ece-rbac-user-settings] + +Platform admins and users can access user settings. Full name, contact email, and updating the password can be changed by either. The username cannot be changed. The platform admin can also assign roles and disable users. + +* For platform admins, the user settings are editable from the **Users** page. +* For users, they can edit their profile from the **Settings** page. + + + + + diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/native-user-authentication.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/native-user-authentication.md new file mode 100644 index 000000000..557730133 --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/native-user-authentication.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-add-native-users.html +--- + +# Native user authentication [ece-add-native-users] + +If you are adding a small number of users and don’t mind managing them manually, using the local *native* authentication might be the best fit for your team. + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Users** and then **Native users**. +3. Select **Create user**. +4. Provide the user details, select the role, and set their password. + + The password must be a minimum of eight characters. + +5. Save your changes. You might also want to verify their access with the credentials you created. + diff --git a/deploy-manage/users-roles/cloud-enterprise-orchestrator/saml.md b/deploy-manage/users-roles/cloud-enterprise-orchestrator/saml.md new file mode 100644 index 000000000..55977e2a8 --- /dev/null +++ b/deploy-manage/users-roles/cloud-enterprise-orchestrator/saml.md @@ -0,0 +1,125 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-create-saml-profiles.html +--- + +# SAML [ece-create-saml-profiles] + +You can configure Elastic Cloud Enterprise to delegate authentication of users to a Security Assertion Markup Language (SAML) authentication provider. Elastic Cloud Enterprise supports the SAML 2.0 Web Browser Single Sign On Profile only and this requires the use of a web browser. Due to this, SAML profiles should not be used for standard API clients. The security deployment acts as a SAML 2.0 compliant *service provider*. + +There are several sections to the profile: + +* Specify the [general SAML settings](#ece-saml-general-settings). +* Specify the necessary [attribute mappings](#ece-saml-attributes) +* Create [role mappings](#ece-saml-role-mapping), either to all users that match the profile or assign roles to specific attribute values. +* Add any [custom configuration](#ece-saml-custom-configuration) advanced settings to the YAML file. For example, if you need to ignore the SSL check for the SSL certificate of the Domain Controller in a testing environment, you might add `ssl.verification_mode: none`. Note that all entries added should omit `xpack.security.authc.realms.saml.$realm_id` prefix, as ECE will insert this itself and automatically account for any differences in format across Elasticsearch versions. +* Optional: Prepare the [trusted SSL certificate bundle](#ece-saml-ssl-certificates). +* Sign the [outgoing SAML messages](#ece-configure-saml-signing-certificates). +* [Encrypt SAML messages](#ece-encrypt-saml). + +$$$ece-saml-general-settings$$$Begin the provider profile by adding the general settings: + +1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md). +2. Go to **Users** and then **Authentication providers**. +3. From the **Add provider** drop-down menu, select **SAML**. +4. Provide a unique profile name. This name becomes the realm ID, with any spaces replaced by hyphens. + + The name can be changed, but the realm ID cannot. The realm ID becomes part of the [certificate bundle](#ece-saml-ssl-certificates). + +5. Enter the Assertion Consumer Service URL endpoint within Elastic Cloud Enterprise that receives the SAML assertion. + + Example: `https://HOSTNAME_OR_IP_ADDRESS:12443/api/v1/users/auth/saml/_callback` + +6. Enter the URL that receives logout messages from the authentication provider. + + Example: `https://HOSTNAME_OR_IP_ADDRESS:12443/api/v1/users/auth/_logout` + +7. Enter the URI for the SAML **identity provider entity ID**. The value for this will be usually provided by the Identity Provider administrator. + + Example: `urn:example:idp` + +8. Enter the URI for the SAML **service provider entity ID** that represents Elastic Cloud Enterprise. The only restriction is that this is a valid URI, but the common practice is to use the domain name where the Service Provider is available. + + Example: `http://SECURITY_DEPLOYMENT_IP:12443` + +9. Specify the HTTPS URL to the metadata file of the Identity Provider. + + Example: `https://HOSTNAME_OR_IP_ADDRESS:7000/metadata` + + + +## Map SAML attributes to User Properties [ece-saml-attributes] + +The SAML assertion about a user usually includes attribute names and values that can be used for role mapping. The configuration in this section allows to configure a mapping between these SAML attribute values and [Elasticsearch user properties](https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-authentication.html#saml-user-properties). When the attributes have been mapped to user properties such as `groups`, these can then be used to configure [role mappings](#ece-saml-role-mapping). Mapping the `principal` user property is required and the `groups` property is recommended for a minimum configuration. + +Note that some additional attention must be paid to the `principal` user property. Although the SAML specification does not have many restrictions on the type of value that is mapped, ECE requires that the mapped value is also a valid Elasticsearch native realm identifier. Specifically, this means the mapped identifier should not contain any commas or slashes, and should be otherwise URL friendly. + + +## Create role mappings [ece-saml-role-mapping] + +When a user is authenticated, the role mapping assigns them roles in Elastic Cloud Enterprise. You can assign roles by: + +* Assigning all authenticated users a single role, select one of the **Default roles**. +* Assigning roles according to the user properties (such as `dn`, `groups`, `username`), use the **Add role mapping rule** fields. + +In the following example, you have configured the Elasticsearch user property `groups` to map to the SAML attribute with name `SAML_Roles` and you want only users whose SAML assertion contains the `SAML_Roles` attribute with value `p_viewer` to get the `Platform viewer` role in Elastic Cloud Enterprise. + +To complete the role mapping: + +1. Select **Add role mapping rule**. +2. Select `groups` from the `User Property` drop down list. +3. Enter `p_viewer` in the `Value` field. +4. Select `Platform Viewer` in the `Roles` drop down list. +5. Select `Add role mapping`. + + +## Custom configuration [ece-saml-custom-configuration] + +You can add any additional settings to the **Advanced configuration** YAML file. + +You can also enable some other options: + +* **Use single logout (SLO)** makes sure that when a user logs out of Elastic Cloud Enterprise, they will also be redirected to the SAML Identity Provider so that they can logout there and subsequently logout from all of the other SAML sessions they might have with other SAML Service Providers. +* **Enable force authentication** means that the Identity Provider must re-authenticate the user for each new session, even if the user has an existing, authenticated session with the Identity Provider. + + +## Prepare SAML SSL certificates [ece-saml-ssl-certificates] + +Though optional, you can add one or more certificate authorities (CAs) to validate the SSL/TLS certificate of the server that is hosting the metadata file. This might be useful when the Identity Provider uses a certificate for TLS that is signed by an organization specific Certification Authority, that is not trusted by default by Elastic Cloud Enterprise. + +1. Expand the **Advanced settings**. +2. Provide the **SSL certificate URL** to the ZIP file. + + The bundle should be a ZIP file containing a single `keystore.ks` file in the directory `/saml/:id/truststore`, where `:id` is the value of the **Realm ID** field created in the [General settings](#ece-saml-general-settings). This keystore should contain the CA certificates to be trusted. The keystore file can either be a JKS or a PKCS#12 keystore, but the name of the file should be `keystore.ks`. + +3. Select a keystore type for the provided keystore. +4. If the keystore is password protected, add the password to decrypt the keystore. + + +## Configure SAML signing certificates [ece-configure-saml-signing-certificates] + +Elastic Cloud Enterprise can be configured to sign all outgoing SAML messages. Signing the outgoing messages provides assurance that the messages are coming from the expected service. + +1. Provide the **Signing certificate URL** to the ZIP file with the private key and certificate. + + The bundle should be a ZIP file containing two files named `signing.key` and `signing.pem` in the directory `/saml/:id/`, where `:id` is the value of the **Realm ID** field created in the [General settings](#ece-saml-general-settings). `signing.key` should be the private key and `signing.pem` should be the corresponding certificate to be used for signing outgoing messages. + +2. If the `signing.key` file is password protected, add the password to decrypt the private key. +3. Select which types of messages get signed. + + +## Configure for the encryption of SAML messages [ece-encrypt-saml] + +If your environment requires SAML messages to be encrypted communications, Elastic Cloud Enterprise can be configured with an encryption certificate and key pair. When the Identity Provider uses the public key in this certificate to encrypt the SAML Response ( or parts of it ), Elastic Cloud Enterprise will use the corresponding key to decrypt the message. + +1. Provide the **Encryption certificate URL** to the ZIP file with the private key and certificate. + + The bundle should be a ZIP file containing two files named `encryption.key` and `encryption.pem` in the directory `/saml/:id/`, where `:id` is the value of the **Realm ID** field created in the [General settings](#ece-saml-general-settings). `encryption.key` should be the private key and `encryption.pem` should be the corresponding certificate to be used to decrypt incoming SAML messages. + +2. If the `encryption.key` file is password protected, add the password to decrypt the private key. + +::::{important} +API keys created by users from SAML providers are not deleted or disabled when the user is deleted or disabled in the SAML realm. When you delete a user in the SAML provider, make sure to also remove the user’s API key or delete the user in ECE. +:::: + + diff --git a/deploy-manage/users-roles/cloud-organization.md b/deploy-manage/users-roles/cloud-organization.md new file mode 100644 index 000000000..f37cde0ad --- /dev/null +++ b/deploy-manage/users-roles/cloud-organization.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-organizations.html +--- + +# Cloud organization users [ec-organizations] + +When you sign up to Elastic Cloud, you create an organization. + +This organization is the umbrella for all of your Elastic Cloud resources, users, and account settings. Every organization has a unique identifier. Bills are invoiced according to the billing contact and details that you set for your organization. + +From the Organization page, you can: + +* [Manage members of your organization](cloud-organization/manage-users.md) +* [Leave an organization](cloud-organization/manage-users.md#ec-leave-organization) +* [Assign user roles and privileges](cloud-organization/user-roles.md) +* [Create API keys for using the Elastic Cloud API](../api-keys/elastic-cloud-api-keys.md#ec-api-keys) +* [Configure SAML single sign-on for your organization](cloud-organization/configure-saml-authentication.md) + diff --git a/deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md b/deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md new file mode 100644 index 000000000..a15b3eaf3 --- /dev/null +++ b/deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md @@ -0,0 +1,250 @@ +--- +navigation_title: "Configure {{ecloud}} SAML SSO" +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-saml-sso.html +--- + + + +# Configure SAML authentication [ec-saml-sso] + + +You can centrally control access to your {{ecloud}} organization by setting up SAML single sign-on (SSO) with a SAML 2.0 identity provider (IdP). + +When users log in to {{ecloud}} for the first time using SSO, they’re automatically added to your organization and their accounts are automatically provisioned. + +You can also enhance security by enforcing SSO authentication for members of your organization, and centrally manage role assignments by mapping IdP groups to {{ecloud}} roles. + + +## Should I use organization-level or deployment-level SSO? [ec_should_i_use_organization_level_or_deployment_level_sso_2] + +You can also integrate third-party authentication directly [at the deployment level](../cluster-or-deployment-auth.md). The option that you choose depends on your requirements: + +| Consideration | Organization-level | Deployment-level | +| --- | --- | --- | +| **Management experience** | Manage authentication and role mapping centrally for all deployments in the organization | Configure SSO for each deployment individually | +| **Authentication protocols** | SAML only | Multiple protocols, including LDAP, OIDC, and SAML | +| **Role mapping** | [Organization-level roles and instance access roles](user-roles.md), Serverless project [custom roles](https://docs.elastic.co/serverless/custom-roles.html) | [Built-in](../cluster-or-deployment-auth/built-in-roles.md) and [custom](../cluster-or-deployment-auth/defining-roles.md) stack-level roles | +| **User experience** | Users interact with Cloud | Users interact with the deployment directly | + +If you want to avoid exposing users to the {{ecloud}} UI, or have users who only interact with some deployments, then you might prefer users to interact with your deployment directly. + +In some circumstances, you might want to use both organization-level and deployment-level SSO. For example, if you have a data analyst who interacts only with data in specific deployments, then you might want to configure deployment-level SSO for them. If you manage multiple tenants in a single organization, then you might want to configure organization-level SSO to administer deployments, and deployment-level SSO for the users who are using each deployment. + + +## Prerequisites [ec_prerequisites_4] + +* This functionality requires an [Enterprise subscription](https://www.elastic.co/subscriptions/cloud). +* You must have a SAML 2.0 compatible identity provider. + + +## Risks and considerations [ec_risks_and_considerations] + +Before you configure SAML SSO, familiarize yourself with the following risks and considerations: + +* Actions taken on the IdP are not automatically reflected in {{ecloud}}. For example, if you remove a user from your IdP, they are not removed from the {{ecloud}} organization and their active sessions are not invalidated. + + To immediately revoke a user’s active sessions, an organization owner must [remove the user from the {{ecloud}} organization](https://cloud.elastic.co/account/members) or remove their assigned roles. + +* If you enforce SSO authentication, you can be locked out of {{ecloud}} if your IdP is unavailable or misconfigured. You might need to work with Elastic Support to regain access to your account. To avoid being locked out, you should maintain and store an [{{ecloud}} API key](../../api-keys/elastic-cloud-api-keys.md#ec-api-keys) with organization owner level privileges so that an administrator can disable enforcement in an emergency. +* If you do not enforce SSO authentication, users can still log in without authenticating with your IdP. You need to manage these users in Elastic Cloud. +* Cloud passwords are invalidated each time a user logs in using SSO. If a user needs sign in with their email and password again, they need to [change their password](../../../cloud-account/change-your-password.md). +* Role mappings only take effect when your organization’s members authenticate using SSO. If SSO authentication is not enforced, users might have roles that are inconsistent with the role mapping when they log in using other methods. +* Roles manually assigned using the {{ecloud}} UI are overwritten by the role mapping when the user logs in using SSO. + + +## Claim a domain [ec-saml-sso-claim-domain] + +Before you can register and use your IdP with {{ecloud}}, you must claim one or more domains. Only users that have email addresses that match claimed domains can authenticate with your IdP. + +If the members of your {{ecloud}} organization have email addresses from multiple domains, you can claim multiple domains. + +You must have authority to modify your domain’s DNS records and be a member of the **Organization owner** role in {{ecloud}} to complete this step. + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **Domains** section, click **Add domain**. +3. In the **Domain name** field, enter the domain that you want to claim and then click **Generate verification code**. +4. In the DNS provider settings for your domain, add a new TXT record with the name `_elastic_domain_challenge` and the verification code as the value. +5. Verify that your DNS provider settings are correct by running a `dig` command in a Linux terminal. For example, for the domain `example.com`: + + ```sh + dig _elastic_domain_challenge.example.com TXT + ... + ;; ANSWER SECTION: + _elastic_domain_challenge.example.com. 60 IN TXT "1234rvic48untuh8uckoroaelpz7iid4uk5b8g0m2e4q57b07kak66r7xetoge8zn" + ... + ``` + +6. In the {{ecloud}} UI, click **Verify and add domain**. + +::::{note} +It might take some time for the DNS records to be updated and propagated in the network. If verification isn’t successful, wait a while and try again. +:::: + + + +## Register a SAML IdP [ec-saml-sso-register-idp] + +After you have claimed one or more domains, you can register your IdP with {{ecloud}}. The steps vary by IdP; for more specific details, refer to [Register {{ecloud}} SAML in Microsoft Entra ID](register-elastic-cloud-saml-in-microsoft-entra-id.md) and [Register {{ecloud}} SAML in Okta](register-elastic-cloud-saml-in-okta.md). + + +### Create a new SAML 2 application [ec_create_a_new_saml_2_application] + +Create a new SAML 2 application in your IdP. + +1. Use placeholder values for the assertion consumer service (ACS) and SP entity ID/audience. Those values will be provided by {{ecloud}} in a later step. +2. Configure your application to send an `email` attribute statement with the email address of your organization members. The email should match the domain that you claimed. +3. Optionally configure the application to send `firstName` and `lastName` attribute statements, which will be used to set the respective fields of the user’s {{ecloud}} account. +4. If you’re planning to use role mappings, configure the application to send a `groups` attribute statement with the groups that you want to map to roles in {{ecloud}}. +5. Note the SAML issuer and the SSO URL, which is the URL of the IdP where users will be redirected at login. +6. Download the public certificate of the SAML 2 application. + + +### Register the IdP with {{ecloud}} [ec_register_the_idp_with_ecloud] + +Add the information that you collected to {{ecloud}}. + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **User authentication** section, click **Configure SSO**. +3. Fill the following fields: + + 1. **Identity Provider Entity ID**: The SAML issuer that you collected in the previous step. This is unique identifier of your identity provider that allows Elastic Cloud to verify the source of SAML assertions. + 2. **Identity Provider SSO URL**: The SSO URL that you collected in the previous step. This should be the HTTP-POST SAML binding of your identity provider. Users will be redirected to this URL when they attempt to log in. + 3. **Public x509 certificate**: The public certificate of the SAML 2 application that you downloaded in the previous step. This is the certificate that SAML responses will be signed with by your IdP. The certificate must be in PEM format. + 4. **Login identifier prefix**: A customizable piece of the {{ecloud}} SSO URL that your organization members can use to authenticate. This could be the name of your business. You can use lowercase alphanumeric characters and hyphens in this value, and you can change it later. + +4. Click **Update configuration**. + +::::{tip} +The **Only allow login through my identity provider** option is disabled by default. You must verify your SSO configuration by logging in using SSO to enable this option. +:::: + + +If your configuration is valid, the following details of the service provider (SP) will be displayed: + +* **SSO Login URL**: The URL that your organization members can use to log in to your organization using your IdP. + + If your IdP supports an application bookmark or tile, this is the URL that should be used. {{ecloud}} does not support IdP-initiated SSO. + +* **Service provider Entity ID**: The unique identifier that allows your IDP to recognize and validate requests from {{ecloud}}. +* **Service provider ACS URL**: The {{ecloud}} URL that receives SAML assertions from your IdP. +* **Metadata URL**: The link to an XML metadata file that contains the Elastic service provider metadata. If your IdP accepts metadata files, then you can use this file to configure your IdP. + + +### Update the SAML 2 application in your IdP [ec_update_the_saml_2_application_in_your_idp] + +Using the details returned in the previous step, update the assertion consumer service (ACS), SP entity ID/audience, and SSO login URL values in your SAML 2 application. + +::::{tip} +Additional details that you might want to use in your IdP configuration, such as the request signing certificate, are available in the downloadable metadata file. +:::: + + + +## Test SSO [ec_test_sso] + +After you register the IdP in {{ecloud}} and configure your IdP, you can test authentication. To begin SSO, open the identity provider SSO URL in an incognito browsing session. If everything is configured correctly, you should be redirected to your IdP for authentication and then redirected back to {{ecloud}} signed in. + +Users who are not a member of the {{ecloud}} organization can authenticate with your IdP to automatically create an {{ecloud}} account provided that their email matches the claimed domain. + + +## Enforce SSO [enforce-sso] + +After SSO is configured successfully, you might want to enforce SSO authentication for members of your organization. This enforcement requires members to authenticate with SSO through the organization’s SAML IdP and prevents them from logging in by any other methods. It ensures that users who have been off-boarded in your IdP can no longer authenticate to {{ecloud}}, and also ensures users have the appropriate role mappings applied at each login. + +::::{warning} +If you turn on enforcement, you will be unable to access {{ecloud}} if your IdP is unavailable or misconfigured or there is an {{ecloud}} incident. It is recommended that you maintain and store an {{ecloud}} API key with organization owner level privileges so that an administrator can disable enforcement in an emergency. Refer to [Create an API key](../../api-keys/elastic-cloud-api-keys.md#ec-api-keys). You can also open a support issue if you lose access to your {{ecloud}} account. + +:::: + + + +### Enable enforcement [ec_enable_enforcement] + +To protect your account from being accidentally locked out when this option is enabled, we validate that you are authenticated SSO with the latest applied configuration before enabling enforcement. + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **User authentication** section, click **Edit**. +3. Toggle the **Only allow login through my identity provider** option on to enable enforcement. + + +### Disable enforcement [ec_disable_enforcement] + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **User authentication** section, click **Edit**. +3. Toggle the **Only allow login through my identity provider** option off to disable enforcement. + +If you are unable to access the UI for any reason, use the following API call to disable enforcement. The API key that you use must have organization owner level privileges to disable enforcement. + +```sh +curl -XPUT \ +-H 'Content-Type: application/json' \ +-H "Authorization: ApiKey $EC_API_KEY" \ +"https://api.elastic-cloud.com/api/v1/organizations/$ORGANIZATION_ID" \ +-d ' +{ + "enforce_authentication_method": null +} +' +``` + + +## Role mappings [role-mappings] + +To automate [role](user-roles.md) assignments to your {{ecloud}} organization’s members, you can use role mappings. Role mappings map groups returned by your IdP in the `groups` SAML attribute to one or more {{ecloud}} roles. The mapping will be evaluated and the applicable roles will be assigned each time your organization’s members log into {{ecloud}} using SSO. + +::::{note} +If [SSO enforcement](#enforce-sso) is not enabled, user roles might not be consistent with your role mapping and additional manual role assignment might be needed. Roles manually assigned using the {{ecloud}} UI are overwritten by the role mapping when the user logs in using SSO. +:::: + + +::::{note} +If the `groups` attribute is not included in the SAML response, the user will keep whatever groups they were last assigned by the IdP. If you want to remove all groups for a user as part of an offboarding process, instead unassign the user from the {{ecloud}} application. +:::: + + +To configure role mappings: + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **Role mappings** section, click **Create role mapping**. +3. Add a name for the role mapping. The name helps to identify the role mapping to other members, and must be unique. +4. Click to configure the roles that you want to assign to users who meet the mapping rules, click **Add roles** and then select the roles. For more information, refer to [*User roles and privileges*](user-roles.md). +5. In the **Mapping rules** section, add rules for the role mapping: + + 1. Select **All are true** or **Any are true** to define how the rules are evaluated. + 2. Add group name or names that the member must have in their SAML assertion to be assigned the role. + + Use the wildcard character `*` to specify group name patterns. Wildcards will match 0 or more characters. + + + +## Disable SSO [ec_disable_sso] + +If SSO enforcement is enabled, then you must disable SSO enforcement before you disable SSO. + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **User authentication** section, click **Edit**. +3. Click **Disable SAML SSO**. + + +## Troubleshoot SSO [ec_troubleshoot_sso] + + +### SSO screen is not redirecting to my IdP [ec_sso_screen_is_not_redirecting_to_my_idp] + +Double check the `saml_idp.sso_url` provided during IdP registration. This should be the HTTP-POST binding URL to your IdP’s SAML application. {{ecloud}} will redirect to this URL during sign in. + + +### Failure to redirect back to {{ecloud}} after IdP log in, or redirected to `/access-denied` [ec_failure_to_redirect_back_to_ecloud_after_idp_log_in_or_redirected_to_access_denied] + +There could be a variety of issues that might result in sign in failure. Try tracing the SAML request and response with a SAML tracer. You should see a `SAMLRequest` field when redirecting to your IdP, and a `SAMLResponse` field when redirecting to the Cloud ACS. + +If there was an error in your IdP, there may be a non-success `Status` field which should describe the error that occurred. + +If the SAML response was successful, double-check the components of the SAML response: + +* The `Destination` and `Recipient` should match the `acs` provided by the {{ecloud}} IdP registration API. +* An `AttributeStatement` named `email` should be sent with the email matching a domain claimed by your {{ecloud}} organization. If the domain of the email doesn’t match a claimed domain, the authentication flow will not complete. +* The `AudienceRestriction` `Audience` should match the `sp_entity_id` provided by the {{ecloud}} IdP registration API. +* The `Issuer` should match the value provided to the {{ecloud}} IdP registration API. +* The signature of the SAML response should be verifiable by the certificate provided during IdP configuration in Cloud. diff --git a/deploy-manage/users-roles/cloud-organization/manage-users.md b/deploy-manage/users-roles/cloud-organization/manage-users.md new file mode 100644 index 000000000..b555daa64 --- /dev/null +++ b/deploy-manage/users-roles/cloud-organization/manage-users.md @@ -0,0 +1,39 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-invite-users.html + - https://www.elastic.co/guide/en/serverless/current/general-manage-organization.html + - https://www.elastic.co/guide/en/cloud/current/ec-api-organizations.html +--- + +# Manage users + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Scope notes: These can all be combined. The tasks are pretty similar between serverless and hosted. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-invite-users.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-manage-organization.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-api-organizations.md +% Notes: api examples + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$general-assign-user-roles$$$ + +$$$general-manage-access-to-organization$$$ + +$$$general-join-organization-from-existing-cloud-account$$$ + +$$$general-leave-an-organization$$$ + +$$$general-assign-user-roles-organization-level-roles$$$ + +$$$general-assign-user-roles-instance-access-roles$$$ + +$$$ec-leave-organization$$$ + +$$$ec-join-invitation$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cloud-organization/register-elastic-cloud-saml-in-microsoft-entra-id.md b/deploy-manage/users-roles/cloud-organization/register-elastic-cloud-saml-in-microsoft-entra-id.md new file mode 100644 index 000000000..07a81e683 --- /dev/null +++ b/deploy-manage/users-roles/cloud-organization/register-elastic-cloud-saml-in-microsoft-entra-id.md @@ -0,0 +1,60 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-saml-sso-entra.html +--- + +# Register Elastic Cloud SAML in Microsoft Entra ID [ec-saml-sso-entra] + +To [configure {{ecloud}} SAML SSO](configure-saml-authentication.md) with Microsoft Entra ID (formerly Azure AD) as the identity provider (IdP), perform the following steps. + + +## Create a new Entra ID Enterprise application [ec_create_a_new_entra_id_enterprise_application] + +In Microsoft Entra ID, create a new Entra ID Enterprise application. + +1. From the Microsoft Entra Gallery, create a non-gallery application. +2. Provide a name and basic information about the application. +3. In the **Single sign-on** section, select **SAML** as the single sign-on method. +4. In the basic SAML configuration, enter placeholder values for the entity ID and the reply or assertion consumer service (ACS) URL. +5. In the **Attributes & Claims** section, configure claims: + + 1. Configure a claim named `email` to send the email address of your users. This attribute is required in the SAML response. + 2. Optional: Configure a `firstName` and `lastName` claim to set the {{ecloud}} user’s name during SSO. + 3. Optional: If you plan to use [role mappings](configure-saml-authentication.md#role-mappings) to automate role assignments, add a group claim and customize which groups are sent. Make sure that you customize the name of the group claim under the **Advanced options** section to set the groups claim attribute name `groups`. + +6. Collect information about the application from the Entra ID screen. + + 1. Get the **Login URL** for the SSO URL, which is the URL where users will be redirected at login. + 2. Get the **Microsoft Entra Identifier** for use as the issuer. + 3. From the **SAML Certificates** section, download the Base64 signing certificate. + + + +## Register with {{ecloud}} [ec_register_with_ecloud_2] + +[Register the IdP with {{ecloud}}](configure-saml-authentication.md#ec-saml-sso-register-idp). + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **User authentication** section, click **Configure SSO**. +3. Fill the following fields: + + 1. **Identity Provider Entity ID**: Enter the **Microsoft Entra Identifier** that you collected in the previous step. + 2. **Identity Provider SSO URL**: Enter the **Login URL** that you collected in the previous step. Users will be redirected to this URL when they attempt to log in. + 3. **Public x509 certificate**: Paste the contents of the downloaded signing certificate. + 4. **Login identifier prefix**: A customizable piece of the {{ecloud}} SSO URL that your organization members can use to authenticate. This could be the name of your business. You can use lowercase alphanumeric characters and hyphens in this value, and you can change it later. + +4. Click **Update configuration**. + +If successful, the API will return additional details that will need to be provided to the IdP. + + +## Update the Entra ID Enterprise application [ec_update_the_entra_id_enterprise_application] + +Update the **Basic SAML Configuration** section of the Entra ID Enterprise application to use the values returned in the **User authentication** page. + +1. Set the entity ID to the **Service provider Entity ID** value. +2. Set the reply or ACS URL to the **Service provider ACS URL** value. +3. Set the sign on URL to the **SSO Login URL** value. +4. Optional: Fill in other details using information from the metadata file available at the **metadata URL**. + +When these steps are complete, you should be able to test SSO as described in [Configure {{ecloud}} SAML SSO](configure-saml-authentication.md). diff --git a/deploy-manage/users-roles/cloud-organization/register-elastic-cloud-saml-in-okta.md b/deploy-manage/users-roles/cloud-organization/register-elastic-cloud-saml-in-okta.md new file mode 100644 index 000000000..92fe458d0 --- /dev/null +++ b/deploy-manage/users-roles/cloud-organization/register-elastic-cloud-saml-in-okta.md @@ -0,0 +1,60 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud/current/ec-saml-sso-okta.html +--- + +# Register Elastic Cloud SAML in Okta [ec-saml-sso-okta] + +To [configure {{ecloud}} SAML SSO](configure-saml-authentication.md) with Okta as the identity provider (IdP), perform the following steps. + + +## Create a new SAML 2.0 application [ec_create_a_new_saml_2_0_application] + +Follow these steps to create a new SAML application for {{ecloud}} in Okta. + +1. In Okta, create a new app integration. select SAML 2.0 as the sign-in method. +2. Add a name for the application. +3. In the app visibility section, select the **Do not display appliation icon** options. {{ecloud}} does not support IdP-initiated login. + + If you want to create an Okta tile for {{ecloud}}, then set one up using [the Bookmark App integration](https://help.okta.com/en-us/content/topics/apps/apps_bookmark_app.htm) after you have configured SAML SSO. + +4. In the SAML settings, fill in the details for your new application. Enter placeholder SAML settings such as `http://example.com/sso` and `http://example.com/sp` for the single sign-on URL and audience URI. +5. Add attribute statements for your organization members' email addresses. These addresses should match the domains that you claimed using [Claim a domain](configure-saml-authentication.md#ec-saml-sso-claim-domain). Optionally add first and last names, which will be used to set the respective fields of the user’s {{ecloud}} account. +6. Optional: If you plan to use [role mappings](configure-saml-authentication.md#role-mappings) to automate role assignments, add a group attribute statement named `groups` and filter the groups as desired. +7. Save the application. +8. Collect information about the application from the Okta **Sign on** tab. + + 1. Get the SAML issuer and the SSO URL, which is the URL of the IdP where users will be redirected at login. + 2. Download the signing certificate of the SAML 2 application. + + + +## Register with {{ecloud}} [ec_register_with_ecloud] + +[Register the IdP with {{ecloud}}](configure-saml-authentication.md#ec-saml-sso-register-idp). + +1. Open your organization’s [**Security**](https://cloud.elastic.co/account/idp) tab. +2. In the **User authentication** section, click **Configure SSO**. +3. Fill the following fields: + + 1. **Identity Provider Entity ID**: Enter the SAML issuer that you collected in the previous step. + 2. **Identity Provider SSO URL**: Enter the SSO URL that you collected in the previous step. Users will be redirected to this URL when they attempt to log in. + 3. **Public x509 certificate**: Paste the contents of the downloaded signing certificate. + 4. **Login identifier prefix**: A customizable piece of the {{ecloud}} SSO URL that your organization members can use to authenticate. This could be the name of your business. You can use lowercase alphanumeric characters and hyphens in this value, and you can change it later. + +4. Click **Update configuration**. + +If successful, the API will return additional details that will need to be provided to the IdP. + + +## Update the application in Okta [ec_update_the_application_in_okta] + +Update your SAML 2 application in Okta to use the values returned in the **User authentication** page. + +1. Set the single sign-on URL to the **SSO Login URL**. +2. Set the audience URI (SP entity ID) to the **Service provider Entity ID**. +3. Optional: Fill in other details using information from the metadata file available at the **metadata URL**. + +When these steps are complete, you should be able to test SSO as described in [Configure {{ecloud}} SAML SSO](configure-saml-authentication.md). + +Optionally, if you want to create an Okta tile for {{ecloud}}, then you can set one up using [the Bookmark App integration](https://help.okta.com/en-us/content/topics/apps/apps_bookmark_app.htm) at this stage. diff --git a/deploy-manage/users-roles/cloud-organization/user-roles.md b/deploy-manage/users-roles/cloud-organization/user-roles.md new file mode 100644 index 000000000..a38cdf4d7 --- /dev/null +++ b/deploy-manage/users-roles/cloud-organization/user-roles.md @@ -0,0 +1,34 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-user-privileges.html + - https://www.elastic.co/guide/en/serverless/current/general-manage-organization.html + - https://www.elastic.co/guide/en/serverless/current/custom-roles.html +--- + +# User roles + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Scope notes: These can be combined, though the list of roles differs between serverless and hosted, but the tasks for managing them are similar. + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-user-privileges.md +% - [ ] ./raw-migrated-files/docs-content/serverless/general-manage-organization.md +% - [ ] ./raw-migrated-files/docs-content/serverless/custom-roles.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$general-assign-user-roles$$$ + +$$$general-manage-access-to-organization$$$ + +$$$general-join-organization-from-existing-cloud-account$$$ + +$$$general-leave-an-organization$$$ + +$$$general-assign-user-roles-organization-level-roles$$$ + +$$$general-assign-user-roles-instance-access-roles$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth.md b/deploy-manage/users-roles/cluster-or-deployment-auth.md new file mode 100644 index 000000000..7d1f2403e --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-clusters.html + - https://www.elastic.co/guide/en/cloud/current/ec-security.html +--- + +# Cluster or deployment auth + +% What needs to be done: Write from scratch + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-securing-clusters.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-security.md \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/access-agreement.md b/deploy-manage/users-roles/cluster-or-deployment-auth/access-agreement.md new file mode 100644 index 000000000..0de1c9205 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/access-agreement.md @@ -0,0 +1,38 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/xpack-security-access-agreement.html +--- + +# Access agreement [xpack-security-access-agreement] + +Access agreement is a [subscription feature](https://www.elastic.co/subscriptions) that requires users to acknowledge and accept an agreement before accessing {{kib}}. The agreement text supports Markdown format and can be specified using the `xpack.security.authc.providers...accessAgreement.message` setting. + +You can specify a default access agreement using the `xpack.security.accessAgreement.message` setting. This message will be used for each provider who doesn’t specify an access agreement. + +::::{note} +You need to acknowledge the access agreement only once per session, and {{kib}} reports the acknowledgement in the audit logs. + +:::: + + +Here is an example of defining an access agreement in `kibana.yml`: + +```yaml +xpack.security.authc.providers: + basic.basic1: + order: 0 + accessAgreement: + message: | + **You are accessing a system with sensitive information** + + By logging in, you acknowledge that information system usage + ...(shortened) +``` + +When you authenticate using `basic.basic1`, you’ll see the following agreement that you must acknowledge before you can access {{kib}}: + +:::{image} ../../../images/kibana-access-agreement.png +:alt: Access Agreement UI +:class: screenshot +::: + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/active-directory.md b/deploy-manage/users-roles/cluster-or-deployment-auth/active-directory.md new file mode 100644 index 000000000..6bcf54516 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/active-directory.md @@ -0,0 +1,29 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/active-directory-realm.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-clusters-ad.html +--- + +# Active directory + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/active-directory-realm.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-securing-clusters-ad.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ece-ad-configuration-with-bind-user$$$ + +$$$ece-ad-configuration-encrypt-communications$$$ + +$$$ad-realm-configuration$$$ + +$$$tls-active-directory$$$ + +$$$ad-user-metadata$$$ + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md b/deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md new file mode 100644 index 000000000..8845955b1 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md @@ -0,0 +1,29 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/anonymous-access.html +--- + +# Anonymous access [anonymous-access] + +::::{tip} +To embed {{kib}} dashboards or grant access to {{kib}} without requiring credentials, use {{kib}}'s [anonymous authentication](user-authentication.md#anonymous-authentication) feature instead. +:::: + + +Incoming requests are considered to be *anonymous* if no authentication token can be extracted from the incoming request. By default, anonymous requests are rejected and an authentication error is returned (status code `401`). + +To enable anonymous access, you assign one or more roles to anonymous users in the `elasticsearch.yml` configuration file. For example, the following configuration assigns anonymous users `role1` and `role2`: + +```yaml +xpack.security.authc: + anonymous: + username: anonymous_user <1> + roles: role1, role2 <2> + authz_exception: true <3> +``` + +1. The username/principal of the anonymous user. Defaults to `_es_anonymous_user` if not specified. +2. The roles to associate with the anonymous user. If no roles are specified, anonymous access is disabled—​anonymous requests will be rejected and return an authentication error. +3. When `true`, a 403 HTTP status code is returned if the anonymous user does not have the permissions needed to perform the requested action and the user will NOT be prompted to provide credentials to access the requested resource. When `false`, a 401 HTTP status code is returned if the anonymous user does not have the necessary permissions and the user is prompted for credentials to access the requested resource. If you are using anonymous access in combination with HTTP, you might need to set `authz_exception` to `false` if your client does not support preemptive basic authentication. Defaults to `true`. + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms.md b/deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms.md new file mode 100644 index 000000000..f8910b769 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms.md @@ -0,0 +1,51 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/realms.html +--- + +# Authentication realms [realms] + +The {{stack-security-features}} authenticate users by using realms and one or more [token-based authentication services](token-based-authentication-services.md). + +A *realm* is used to resolve and authenticate users based on authentication tokens. The {{security-features}} provide the following built-in realms: + +*native* +: An internal realm where users are stored in a dedicated {{es}} index. This realm supports an authentication token in the form of username and password, and is available by default when no realms are explicitly configured. The users are managed via the [user management APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html#security-user-apis). See [Native user authentication](native.md). + +*ldap* +: A realm that uses an external LDAP server to authenticate the users. This realm supports an authentication token in the form of username and password, and requires explicit configuration in order to be used. See [LDAP user authentication](ldap.md). + +*active_directory* +: A realm that uses an external Active Directory Server to authenticate the users. With this realm, users are authenticated by usernames and passwords. See [Active Directory user authentication](active-directory.md). + +*pki* +: A realm that authenticates users using Public Key Infrastructure (PKI). This realm works in conjunction with SSL/TLS and identifies the users through the Distinguished Name (DN) of the client’s X.509 certificates. See [PKI user authentication](pki.md). + +*file* +: An internal realm where users are defined in files stored on each node in the {{es}} cluster. This realm supports an authentication token in the form of username and password and is always available. See [File-based user authentication](file-based.md). + +*saml* +: A realm that facilitates authentication using the SAML 2.0 Web SSO protocol. This realm is designed to support authentication through {{kib}} and is not intended for use in the REST API. See [SAML authentication](saml.md). + +*kerberos* +: A realm that authenticates a user using Kerberos authentication. Users are authenticated on the basis of Kerberos tickets. See [Kerberos authentication](kerberos.md). + +*oidc* +: A realm that facilitates authentication using OpenID Connect. It enables {{es}} to serve as an OpenID Connect Relying Party (RP) and provide single sign-on (SSO) support in {{kib}}. See [Configuring single sign-on to the {{stack}} using OpenID Connect](openid-connect.md). + +*jwt* +: A realm that facilitates using JWT identity tokens as authentication bearer tokens. Compatible tokens are OpenID Connect ID Tokens, or custom JWTs containing the same claims. See [JWT authentication](jwt.md). + +The {{security-features}} also support custom realms. If you need to integrate with another authentication system, you can build a custom realm plugin. For more information, see [Integrating with other authentication systems](custom.md). + +## Internal and external realms [_internal_and_external_realms] + +Realm types can roughly be classified in two categories: + +Internal +: Realms that are internal to Elasticsearch and don’t require any communication with external parties. They are fully managed by the {{stack}} {security-features}. There can only be a maximum of one configured realm per internal realm type. The {{security-features}} provide two internal realm types: `native` and `file`. + +External +: Realms that require interaction with parties/components external to {{es}}, typically, with enterprise grade identity management systems. Unlike internal realms, there can be as many external realms as one would like - each with its own unique name and configuration. The {{security-features}} provide the following external realm types: `ldap`, `active_directory`, `saml`, `kerberos`, and `pki`. + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md new file mode 100644 index 000000000..78d7a2f5c --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md @@ -0,0 +1,80 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-authorization-delegation.html +--- + +# Authorization delegation [configuring-authorization-delegation] + +In some cases, after the user has been authenticated by a realm, we may want to delegate user lookup and assignment of roles to another realm. Any realm that supports [user lookup](looking-up-users-without-authentication.md) (without needing the user’s credentials) can be used as an authorization realm. + +For example, a user that is authenticated by the Kerberos realm can be looked up in the LDAP realm. The LDAP realm takes on responsibility for searching the user in LDAP and determining the role. In this case, the LDAP realm acts as an *authorization realm*. + +## LDAP realm as an authorization realm [_ldap_realm_as_an_authorization_realm] + +Following is an example configuration for the LDAP realm that can be used as an *authorization realm*. This LDAP realm is configured in user search mode with a specified filter. + +For more information on configuring LDAP realms see [LDAP user authentication](ldap.md). + +```yaml +xpack: + security: + authc: + realms: + ldap: + ldap1: + order: 0 + authentication.enabled: true <1> + user_search: + base_dn: "dc=example,dc=org" + filter: "(cn={0})" + group_search: + base_dn: "dc=example,dc=org" + files: + role_mapping: "ES_PATH_CONF/role_mapping.yml" + unmapped_groups_as_roles: false +``` + +1. Here, we explicitly allow the LDAP realm to be used for authentication (that is, users can authenticate using their LDAP username and password). If we wanted this LDAP realm to be used for authorization only, then we would set this to `false`. + + + +## Kerberos realm configured to delegate authorization [_kerberos_realm_configured_to_delegate_authorization] + +Following is an example configuration where the Kerberos realm authenticates a user and then delegates authorization to the LDAP realm. The Kerberos realm authenticates the user and extracts user principal name (usually of format `user@REALM`). In this example, we enable the `remove_realm_name` setting to remove the `@REALM` part from the user principal name to get the username. This username is used to do a user lookup by the configured authorization realms (in this case the LDAP realm). + +For more information on Kerberos realm see [Kerberos authentication](kerberos.md). + +```yaml +xpack: + security: + authc: + realms: + kerberos: + kerb1: + order: 1 + keytab.path: "ES_PATH_CONF/es.keytab" + remove_realm_name: true + authorization_realms: ldap1 +``` + + +## PKI realm configured to delegate authorization [_pki_realm_configured_to_delegate_authorization] + +We can similarly configure PKI realm to delegate authorization to LDAP realm. The user is authenticated by the PKI realm and the authorization is delegated to the LDAP realm. In this example, the username is the common name (CN) extracted from the DN of the client certificate. The LDAP realm uses this username to lookup user and assign the role. + +For more information on PKI realms see [PKI user authentication](pki.md). + +```yaml +xpack: + security: + authc: + realms: + pki: + pki1: + order: 2 + authorization_realms: ldap1 +``` + +Similar to the above examples, we can configure realms to delegate authorization to authorization realms (which have the capability to lookup users by the username and assign roles). + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md new file mode 100644 index 000000000..9a6d9e68e --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md @@ -0,0 +1,93 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/custom-roles-authorization.html +--- + +# Authorization plugins [custom-roles-authorization] + +If you need to retrieve user roles from a system not supported out-of-the-box or if the authorization system that is provided by the {{es}} {security-features} does not meet your needs, a SPI loaded security extension can be implemented to customize role retrieval and/or the authorization system. The SPI loaded security extension is part of an ordinary elasticsearch plugin. + +## Implementing a custom roles provider [implementing-custom-roles-provider] + +To create a custom roles provider: + +1. Implement the interface `BiConsumer, ActionListener>>`. That is to say, the implementation consists of one method that takes a set of strings, which are the role names to resolve, and an ActionListener, on which the set of resolved role descriptors are passed on as the response. +2. The custom roles provider implementation must take special care to not block on any I/O operations. It is the responsibility of the implementation to ensure asynchronous behavior and non-blocking calls, which is made easier by the fact that the `ActionListener` is provided on which to send the response when the roles have been resolved and the response is ready. + +To package your custom roles provider as a plugin: + +1. Implement an extension class for your roles provider that implements `org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to override one or more of the following methods: + + ```java + @Override + public List, ActionListener>>> + getRolesProviders(Settings settings, ResourceWatcherService resourceWatcherService) { + ... + } + ``` + + The `getRolesProviders` method is used to provide a list of custom roles providers that will be used to resolve role names, if the role names could not be resolved by the reserved roles or native roles stores. The list should be returned in the order that the custom role providers should be invoked to resolve roles. For example, if `getRolesProviders` returns two instances of roles providers, and both of them are able to resolve role `A`, then the resolved role descriptor that will be used for role `A` will be the one resolved by the first roles provider in the list. + + + +## Implementing an authorization engine [implementing-authorization-engine] + +To create an authorization engine, you need to: + +1. Implement the `org.elasticsearch.xpack.core.security.authz.AuthorizationEngine` interface in a class with the desired authorization behavior. +2. Implement the `org.elasticsearch.xpack.core.security.authz.Authorization.AuthorizationInfo` interface in a class that contains the necessary information to authorize the request. + +To package your authorization engine as a plugin: + +1. Implement an extension class for your authorization engine that extends `org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to override the following method: + + ```java + @Override + public AuthorizationEngine getAuthorizationEngine(Settings settings) { + ... + } + ``` + + The `getAuthorizationEngine` method is used to provide the authorization engine implementation. + + +Sample code that illustrates the structure and implementation of a custom authorization engine is provided in the [elasticsearch](https://github.com/elastic/elasticsearch/tree/master/plugins/examples/security-authorization-engine) repository on GitHub. You can use this code as a starting point for creating your own authorization engine. + + +## Implement an elasticsearch plugin [packing-extension-plugin] + +In order to register the security extension for your custom roles provider or authorization engine, you need to also implement an elasticsearch plugin that contains the extension: + +1. Implement a plugin class that extends `org.elasticsearch.plugins.Plugin` +2. Create a build configuration file for the plugin; Gradle is our recommendation. +3. Create a `plugin-descriptor.properties` file as described in [Help for plugin authors](https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugin-authors.html). +4. Create a `META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension` descriptor file for the extension that contains the fully qualified class name of your `org.elasticsearch.xpack.core.security.SecurityExtension` implementation +5. Bundle all in a single zip file. + + +## Using the security extension [using-security-extension] + +To use a security extension: + +1. Install the plugin with the extension on each node in the cluster. You run `bin/elasticsearch-plugin` with the `install` sub-command and specify the URL pointing to the zip file that contains the extension. For example: + + ```shell + bin/elasticsearch-plugin install file:////my-extension-plugin-1.0.zip + ``` + +2. Add any configuration parameters for implementations in the extension to the `elasticsearch.yml` file. The settings are not namespaced and you have access to any settings when constructing the extensions, although it is recommended to have a namespacing convention for extensions to keep your `elasticsearch.yml` configuration easy to understand. + + For example, if you have a custom roles provider that resolves roles from reading a blob in an S3 bucket on AWS, then you would specify settings in `elasticsearch.yml` such as: + + ```js + custom_roles_provider.s3_roles_provider.bucket: roles + custom_roles_provider.s3_roles_provider.region: us-east-1 + custom_roles_provider.s3_roles_provider.secret_key: xxx + custom_roles_provider.s3_roles_provider.access_key: xxx + ``` + + These settings are passed as arguments to the methods in the `SecurityExtension` interface. + +3. Restart Elasticsearch. + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md new file mode 100644 index 000000000..d8cda40c4 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md @@ -0,0 +1,22 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/built-in-roles.html + - https://www.elastic.co/guide/en/kibana/current/xpack-security-authorization.html +--- + +# Built-in roles + +% What needs to be done: Lift-and-shift + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md +% - [ ] ./raw-migrated-files/kibana/kibana/xpack-security-authorization.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$built-in-roles$$$ + +$$$built-in-roles-kibana-admin$$$ + +$$$built-in-roles-remote-monitoring-agent$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md new file mode 100644 index 000000000..5146f7837 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md @@ -0,0 +1,33 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/built-in-users.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-password-reset-elastic.html + - https://www.elastic.co/guide/en/cloud/current/ec-password-reset.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-password-reset.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-users-and-roles.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-rotate-credentials.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/change-passwords-native-users.html +--- + +# Built-in users + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-users.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-password-reset-elastic.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-password-reset.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-password-reset.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md +% Notes: just default elastic user +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-rotate-credentials.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/change-passwords-native-users.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$set-built-in-user-passwords$$$ + +$$$bootstrap-elastic-passwords$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/configure-operator-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/configure-operator-privileges.md new file mode 100644 index 000000000..6e6549b16 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/configure-operator-privileges.md @@ -0,0 +1,64 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/configure-operator-privileges.html +--- + +# Configure operator privileges [configure-operator-privileges] + +::::{note} +{cloud-only} +:::: + + +Before you can use operator privileges, you must [enable the feature](#enable-operator-privileges) on all nodes in the cluster and [designate operator users](#designate-operator-users). + +## Enable operator privileges [enable-operator-privileges] + +In order to use the operator privileges feature, it must be enabled explicitly on each node in the cluster. Add the following setting in each `elasticsearch.yml` file: + +```yaml +xpack.security.operator_privileges.enabled: true +``` + +If the node is already running before you make this change, you must restart the node for the feature to take effect. + +::::{warning} +The feature needs to be either enabled or disabled consistently across all nodes in a cluster. Otherwise, you can get inconsistent behaviour depending on which node first receives a request and which node executes it. +:::: + + +When operator privileges are enabled on a cluster, [specific functionalities](operator-only-functionality.md) are restricted and can be executed only by users who have been explicitly designated as operator users. If a regular user attempts to execute these functionalities (even if they have the `superuser` role), a security exception occurs. + + +## Designate operator users [designate-operator-users] + +Operator users are just normal {{es}} users with special rights to perform operator-only functionalities. They are specified in an `operator_users.yml` file, which is located in the config directory (as defined by the `ES_PATH_CONF` environment variable). Similar to [other security config files](file-based.md#file-realm-configuration), the `operator_users.yml` file is local to a node and does not apply globally to the cluster. This means, in most cases, the same file should be distributed or copied to all nodes in a cluster. + +The `operator_users.yml` file defines a set of criteria that an authenticating user must match to be considered as an operator user. The following snippet shows an example of such a file: + +```yaml +operator: <1> + - usernames: ["system_agent_1","system_agent_2"] <2> + realm_type: "file" <3> + auth_type: "realm" <4> +``` + +1. A fixed value of `operator` signals the beginning of the definition. +2. A list of user names allowed for operator users. This field is mandatory. +3. The type of the authenticating realm allowed for operator users. The default and only acceptable value is [`file`](file-based.md). +4. The authentication type allowed for operator users. The default and only acceptable value is `realm`. + + +You must specify at least the `usernames` field. If no other fields are specified, their default values are used. All fields must be matched for a user to be qualified as an operator user. You can also specify multiple groups of criteria. This is currently not very useful since this feature does not yet support other realms or authentication types. + +There are also two implicit rules that affect which users are operator users: + +1. If the authenticating user [runs as](submitting-requests-on-behalf-of-other-users.md) another user, neither of them are considered to be operator users. +2. All [Internal users](internal-users.md) are implicitly operator users. + +::::{important} +After a user is designated as an operator user, they are still subject to regular [RBAC user authorization](user-roles.md) checks. That is to say, in addition to specifying that a user is an operator user, you must also grant them the necessary {{es}} roles to perform their tasks. Consequently, it is entirely possible that an operator user can encounter an "access denied" error and fail to perform certain actions due to RBAC check failures. In short, an operator user is **not** automatically a `superuser`. +:::: + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md new file mode 100644 index 000000000..48ab27cb5 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md @@ -0,0 +1,24 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/document-level-security.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/field-level-security.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/field-and-document-access-control.html +--- + +# Controlling access at the document and field level + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$multiple-roles-dls-fls$$$ + +$$$templating-role-query$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-user-cache.md b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-user-cache.md new file mode 100644 index 000000000..b6d5ae31c --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-user-cache.md @@ -0,0 +1,42 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/controlling-user-cache.html +--- + +# Controlling the user cache [controlling-user-cache] + +User credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request. You can configure characteristics of the user cache with the `cache.ttl`, `cache.max_users`, and `cache.hash_algo` realm settings. + +::::{note} +JWT realms use `jwt.cache.ttl` and `jwt.cache.size` realm settings. +:::: + + +::::{note} +PKI and JWT realms do not cache user credentials, but do cache the resolved user object to avoid unnecessarily needing to perform role mapping on each request. +:::: + + +The cached user credentials are hashed in memory. By default, the {{es}} {security-features} use a salted `sha-256` hash algorithm. You can use a different hashing algorithm by setting the `cache.hash_algo` realm settings. See [User cache and password hash algorithms](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#hashing-settings). + +## Evicting users from the cache [cache-eviction-api] + +You can use the [clear cache API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html) to force the eviction of cached users . For example, the following request evicts all users from the `ad1` realm: + +```js +$ curl -XPOST 'http://localhost:9200/_security/realm/ad1/_clear_cache' +``` + +To clear the cache for multiple realms, specify the realms as a comma-separated list: + +```js +$ curl -XPOST 'http://localhost:9200/_security/realm/ad1,ad2/_clear_cache' +``` + +You can also evict specific users: + +```java +$ curl -XPOST 'http://localhost:9200/_security/realm/ad1/_clear_cache?usernames=rdeniro,alpacino' +``` + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/custom.md b/deploy-manage/users-roles/cluster-or-deployment-auth/custom.md new file mode 100644 index 000000000..f1f689edb --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/custom.md @@ -0,0 +1,74 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/custom-realms.html +--- + +# Custom [custom-realms] + +If you are using an authentication system that is not supported out-of-the-box by the {{es}} {security-features}, you can create a custom realm to interact with it to authenticate users. You implement a custom realm as an SPI loaded security extension as part of an ordinary elasticsearch plugin. + +## Implementing a custom realm [implementing-custom-realm] + +Sample code that illustrates the structure and implementation of a custom realm is provided in [https://github.com/elastic/elasticsearch/tree/master/x-pack/qa/security-example-spi-extension](https://github.com/elastic/elasticsearch/tree/master/x-pack/qa/security-example-spi-extension). You can use this code as a starting point for creating your own realm. + +To create a custom realm, you need to: + +1. Extend `org.elasticsearch.xpack.security.authc.Realm` to communicate with your authentication system to authenticate users. +2. Implement the `org.elasticsearch.xpack.security.authc.Realm.Factory` interface in a class that will be used to create the custom realm. +3. Extend `org.elasticsearch.xpack.security.authc.DefaultAuthenticationFailureHandler` to handle authentication failures when using your custom realm. + +To package your custom realm as a plugin: + +1. Implement an extension class for your realm that extends `org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to override one or more of the following methods: + + ```java + @Override + public Map getRealms() { + ... + } + ``` + + The `getRealms` method is used to provide a map of type names to the `Factory` that will be used to create the realm. + + ```java + @Override + public AuthenticationFailureHandler getAuthenticationFailureHandler() { + ... + } + ``` + + The `getAuthenticationFailureHandler` method is used to optionally provide a custom `AuthenticationFailureHandler`, which will control how the {{es}} {security-features} respond in certain authentication failure events. + + ```java + @Override + public List getSettingsFilter() { + ... + } + ``` + + The `Plugin#getSettingsFilter` method returns a list of setting names that should be filtered from the settings APIs as they may contain sensitive credentials. Note this method is not part of the `SecurityExtension` interface, it’s available as part of the elasticsearch plugin main class. + +2. Create a build configuration file for the plugin; Gradle is our recommendation. +3. Create a `META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension` descriptor file for the extension that contains the fully qualified class name of your `org.elasticsearch.xpack.core.security.SecurityExtension` implementation +4. Bundle all in a single zip file. + + +## Using a custom realm to authenticate users [using-custom-realm] + +To use a custom realm: + +1. Install the realm extension on each node in the cluster. You run `bin/elasticsearch-plugin` with the `install` sub-command and specify the URL pointing to the zip file that contains the extension. For example: + + ```shell + bin/elasticsearch-plugin install file:////my-realm-1.0.zip + ``` + +2. Add a realm configuration of the appropriate realm type to `elasticsearch.yml` under the `xpack.security.authc.realms` namespace. You must define your realm within the namespace that matches the type defined by the extension. The options you can set depend on the settings exposed by the custom realm. At a minimum, you must explicitly set the `order` attribute to control the order in which the realms are consulted during authentication. You must also make sure each configured realm has a distinct `order` setting. In the event that two or more realms have the same `order`, the node will fail to start. + + ::::{important} + When you configure realms in `elasticsearch.yml`, only the realms you specify are used for authentication. If you also want to use the `native` or `file` realms, you must include them in the realm chain. + :::: + +3. Restart Elasticsearch. + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md new file mode 100644 index 000000000..deb39bbe5 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -0,0 +1,41 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-users-and-roles.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html + - https://www.elastic.co/guide/en/kibana/current/tutorial-secure-access-to-kibana.html + - https://www.elastic.co/guide/en/kibana/current/kibana-role-management.html +--- + +# Defining roles + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md +% Notes: custom roles +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md +% - [ ] ./raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md +% - [ ] ./raw-migrated-files/kibana/kibana/kibana-role-management.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$roles-remote-indices-priv$$$ + +$$$roles-remote-cluster-priv$$$ + +$$$adding_kibana_privileges$$$ + +$$$adding_index_privileges$$$ + +$$$roles-management-file$$$ + +$$$roles-indices-priv$$$ + +$$$roles-management-ui$$$ + +$$$roles-management-api$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md new file mode 100644 index 000000000..85d1c10d3 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md @@ -0,0 +1,389 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html +--- + +# Elasticsearch privileges [security-privileges] + +This section lists the privileges that you can assign to a role. + +## Cluster privileges [privileges-list-cluster] + +`all` +: All cluster administration operations, like snapshotting, node shutdown/restart, settings update, rerouting, or managing users and roles. + +`cancel_task` +: Privileges to cancel tasks and delete async searches. See [delete async search](https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html#delete-async-search) API for more informations. + +`create_snapshot` +: Privileges to create snapshots for existing repositories. Can also list and view details on existing repositories and snapshots. + + This privilege is not available in {{serverless-full}}. + + +`cross_cluster_replication` +: Privileges to connect to [remote clusters configured with the API key based model](../../remote-clusters/remote-clusters-api-key.md) for cross-cluster replication. + + This privilege is not available in {{serverless-full}}. + + ::::{note} + This privilege should *not* be directly granted. It is used internally by [Create Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) and [Update Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-cross-cluster-api-key.html) to manage cross-cluster API keys. + :::: + + +`cross_cluster_search` +: Privileges to connect to [remote clusters configured with the API key based model](../../remote-clusters/remote-clusters-api-key.md) for cross-cluster search. + + This privilege is not available in {{serverless-full}}. + + ::::{note} + This privilege should *not* be directly granted. It is used internally by [Create Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) and [Update Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-cross-cluster-api-key.html) to manage cross-cluster API keys. + :::: + + +`grant_api_key` +: Privileges to create {{es}} API keys on behalf of other users. + + This privilege is not available in {{serverless-full}}. + + +`manage` +: Builds on `monitor` and adds cluster operations that change values in the cluster. This includes snapshotting, updating settings, and rerouting. It also includes obtaining snapshot and restore status. This privilege does not include the ability to manage security. + +`manage_api_key` +: All security-related operations on {{es}} REST API keys including [creating new API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), [retrieving information about API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html), [querying API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-query-api-key.html), [updating API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-api-key.html), [bulk updating API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-bulk-update-api-keys.html), and [invalidating API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html). + + ::::{note} + * When you create new API keys, they will always be owned by the authenticated user. + * When you have this privilege, you can invalidate your own API keys and those owned by other users. + + :::: + + +`manage_autoscaling` +: All operations related to managing autoscaling policies. + + This privilege is not available in {{serverless-full}}. + + +`manage_ccr` +: All {{ccr}} operations related to managing follower indices and auto-follow patterns. It also includes the authority to grant the privileges necessary to manage follower indices and auto-follow patterns. This privilege is necessary only on clusters that contain follower indices. + + This privilege is not available in {{serverless-full}}. + + +`manage_data_frame_transforms` +: All operations related to managing {{transforms}}. [7.5] Use `manage_transform` instead. + + This privilege is not available in {{serverless-full}}. + + +`manage_data_stream_global_retention` +: This privilege has no effect.[8.16] + +`manage_enrich` +: All operations related to managing and executing enrich policies. + +`manage_ilm` +: All {{ilm}} operations related to managing policies. + + This privilege is not available in {{serverless-full}}. + + +`manage_index_templates` +: All operations on index templates. + +`manage_inference` +: All operations related to managing {{infer}}. + +`manage_ingest_pipelines` +: All operations on ingest pipelines. + +`manage_logstash_pipelines` +: All operations on logstash pipelines. + +`manage_ml` +: All {{ml}} operations, such as creating and deleting {{dfeeds}}, jobs, and model snapshots. + + ::::{note} + {{dfeeds-cap}} that were created prior to version 6.2 or created when {{security-features}} were disabled run as a system user with elevated privileges, including permission to read all indices. Newer {{dfeeds}} run with the security roles of the user who created or updated them. + :::: + + +`manage_oidc` +: Enables the use of {{es}} APIs ([OpenID connect prepare authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-oidc-prepare-authentication.html), [OpenID connect authenticate](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-oidc-authenticate.html), and [OpenID connect logout](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-oidc-logout.html)) to initiate and manage OpenID Connect authentication on behalf of other users. + + This privilege is not available in {{serverless-full}}. + + +`manage_own_api_key` +: All security-related operations on {{es}} API keys that are owned by the current authenticated user. The operations include [creating new API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), [retrieving information about API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html), [querying API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-query-api-key.html), [updating API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-api-key.html), [bulk updating API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-bulk-update-api-keys.html), and [invalidating API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html). + +`manage_pipeline` +: All operations on ingest pipelines. + +`manage_rollup` +: All rollup operations, including creating, starting, stopping and deleting rollup jobs. + + This privilege is not available in {{serverless-full}}. + + +`manage_saml` +: Enables the use of internal {{es}} APIs to initiate and manage SAML authentication on behalf of other users. + + This privilege is not available in {{serverless-full}}. + + +`manage_search_application` +: All CRUD operations on [search applications](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-application-apis.html). + +`manage_search_query_rules` +: All CRUD operations on [query rules](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-rules-apis.html). + +`manage_search_synonyms` +: All synonyms management operations on [Synonyms APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/synonyms-apis.html). + +`manage_security` +: All security-related operations such as CRUD operations on users and roles and cache clearing. + +`manage_service_account` +: All security-related operations on {{es}} service accounts including [Get service accounts](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-service-accounts.html), [Create service account tokens](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html), [Delete service account token](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-service-token.html), and [Get service account credentials](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-service-credentials.html). + + This privilege is not available in {{serverless-full}}. + + +`manage_slm` +: All {{slm}} ({{slm-init}}) actions, including creating and updating policies and starting and stopping {{slm-init}}. + + This privilege is not available in {{serverless-full}}. + + [8.15] Also grants the permission to start and stop {{Ilm}}, using the [ILM start](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-start.html) and [ILM stop](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-stop.html) APIs. In a future major release, this privilege will not grant any {{Ilm}} permissions. + + +`manage_token` +: All security-related operations on tokens that are generated by the {{es}} Token Service. + + This privilege is not available in {{serverless-full}}. + + +`manage_transform` +: All operations related to managing {{transforms}}. + +`manage_watcher` +: All watcher operations, such as putting watches, executing, activate or acknowledging. + + This privilege is not available in {{serverless-full}}. + + ::::{note} + Watches that were created prior to version 6.1 or created when the {{security-features}} were disabled run as a system user with elevated privileges, including permission to read and write all indices. Newer watches run with the security roles of the user who created or updated them. + :::: + + +`monitor` +: All cluster read-only operations, like cluster health and state, hot threads, node info, node and cluster stats, and pending cluster tasks. + +`monitor_data_stream_global_retention` +: This privilege has no effect.[8.16] + +`monitor_enrich` +: All read-only operations related to managing and executing enrich policies. + +`monitor_inference` +: All read-only operations related to {{infer}}. + +`monitor_ml` +: All read-only {{ml}} operations, such as getting information about {{dfeeds}}, jobs, model snapshots, or results. + +`monitor_rollup` +: All read-only rollup operations, such as viewing the list of historical and currently running rollup jobs and their capabilities. + + This privilege is not available in {{serverless-full}}. + + +`monitor_snapshot` +: Privileges to list and view details on existing repositories and snapshots. + + This privilege is not available in {{serverless-full}}. + + +`monitor_stats` +: Privileges to list and view details of stats. + + This privilege is not available in {{serverless-full}}. + + +`monitor_text_structure` +: All read-only operations related to the [find structure API](https://www.elastic.co/guide/en/elasticsearch/reference/current/find-structure.html). + + This privilege is not available in {{serverless-full}}. + + +`monitor_transform` +: All read-only operations related to {{transforms}}. + +`monitor_watcher` +: All read-only watcher operations, such as getting a watch and watcher stats. + + This privilege is not available in {{serverless-full}}. + + +`read_ccr` +: All read-only {{ccr}} operations, such as getting information about indices and metadata for leader indices in the cluster. It also includes the authority to check whether users have the appropriate privileges to follow leader indices. This privilege is necessary only on clusters that contain leader indices. + + This privilege is not available in {{serverless-full}}. + + +`read_ilm` +: All read-only {{Ilm}} operations, such as getting policies and checking the status of {Ilm} + + This privilege is not available in {{serverless-full}}. + + +`read_pipeline` +: Read-only access to ingest pipeline (get, simulate). + +`read_slm` +: All read-only {{slm-init}} actions, such as getting policies and checking the {{slm-init}} status. + + This privilege is not available in {{serverless-full}}. + + [8.15] Also grants the permission to get the {{Ilm}} status, using the [ILM get status API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-status.html). In a future major release, this privilege will not grant any {{Ilm}} permissions. + + +`read_security` +: All read-only security-related operations, such as getting users, user profiles, {{es}} API keys, {{es}} service accounts, roles and role mappings. Allows [querying](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-query-api-key.html) and [retrieving information](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html) on all {{es}} API keys. + +`transport_client` +: All privileges necessary for a transport client to connect. Required by the remote cluster to enable [{{ccs}}](../../remote-clusters.md). + + This privilege is not available in {{serverless-full}}. + + + +## Indices privileges [privileges-list-indices] + +`all` +: Any action on an index or data stream. + +`auto_configure` +: Permits auto-creation of indices and data streams. An auto-create action is the result of an [index](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html) or [bulk](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html) request that targets a non-existent index or data stream rather than an explicit [create index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html) or [create data stream](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-data-stream.html) request. Also permits auto-update of mappings on indices and data streams if they do not contradict existing mappings. An auto-update mapping action is the result of an index or bulk request on an index or data stream that contains new fields that may be mapped rather than an explicit [update mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html) request. + +`create` +: Privilege to index documents. + + [8.0] Also grants the permission to update the index mapping (but not the data streams mapping), using the [updating mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html) or by relying on [dynamic field mapping](../../../manage-data/data-store/mapping/dynamic-mapping.md). In a future major release, this privilege will not grant any mapping update permissions. + + ::::{note} + This privilege does not restrict the index operation to the creation of documents but instead restricts API use to the index API. The index API allows a user to overwrite a previously indexed document. See the `create_doc` privilege for an alternative. + :::: + + +`create_doc` +: Privilege to index documents. It does not grant the permission to update or overwrite existing documents. + + [8.0] Also grants the permission to update the index mapping (but not the data streams mapping), using the [updating mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html) or by relying on [dynamic field mapping](../../../manage-data/data-store/mapping/dynamic-mapping.md). In a future major release, this privilege will not grant any mapping update permissions. + + ::::{note} + This privilege relies on the `op_type` of indexing requests ([Index](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html) and [Bulk](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html)). When ingesting documents as a user who has the `create_doc` privilege (and no higher privilege such as `index` or `write`), you must ensure that *op_type* is set to *create* through one of the following: + + * Explicitly setting the `op_type` in the index or bulk APIs + * Using the `_create` endpoint for the index API + * Creating a document with an auto-generated `_id` + + :::: + + +`create_index` +: Privilege to create an index or data stream. A create index request may contain aliases to be added to the index once created. In that case the request requires the `manage` privilege as well, on both the index and the aliases names. + +`cross_cluster_replication` +: Privileges to perform cross-cluster replication for indices located on [remote clusters configured with the API key based model](../../remote-clusters/remote-clusters-api-key.md). This privilege should only be used for the `privileges` field of [remote indices privileges](defining-roles.md#roles-remote-indices-priv). + + This privilege is not available in {{serverless-full}}. + + +`cross_cluster_replication_internal` +: Privileges to perform supporting actions for cross-cluster replication from [remote clusters configured with the API key based model](../../remote-clusters/remote-clusters-api-key.md). + + This privilege is not available in {{serverless-full}}. + + ::::{note} + This privilege should *not* be directly granted. It is used internally by [Create Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html) and [Update Cross-Cluster API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-cross-cluster-api-key.html) to manage cross-cluster API keys. + :::: + + +`delete` +: Privilege to delete documents. + +`delete_index` +: Privilege to delete an index or data stream. + +`index` +: Privilege to index and update documents. + + [8.0] Also grants the permission to update the index mapping (but not the data streams mapping), using the [updating mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html) or by relying on [dynamic field mapping](../../../manage-data/data-store/mapping/dynamic-mapping.md). In a future major release, this privilege will not grant any mapping update permissions. + + +`maintenance` +: Permits refresh, flush, synced flush and force merge index administration operations. No privilege to read or write index data or otherwise manage the index. + +`manage` +: All `monitor` privileges plus index and data stream administration (aliases, analyze, cache clear, close, delete, exists, flush, mapping, open, field capabilities, force merge, refresh, settings, search shards, validate query). + +`manage_data_stream_lifecycle` +: All [Data stream lifecycle](../../../manage-data/lifecycle/data-stream.md) operations relating to reading and managing the built-in lifecycle of a data stream. This includes operations such as adding and removing a lifecycle from a data stream. + +`manage_follow_index` +: All actions that are required to manage the lifecycle of a follower index, which includes creating a follower index, closing it, and converting it to a regular index. This privilege is necessary only on clusters that contain follower indices. + + This privilege is not available in {{serverless-full}}. + + +`manage_ilm` +: All {{Ilm}} operations relating to managing the execution of policies of an index or data stream. This includes operations such as retrying policies and removing a policy from an index or data stream. + + This privilege is not available in {{serverless-full}}. + + +`manage_leader_index` +: All actions that are required to manage the lifecycle of a leader index, which includes [forgetting a follower](https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-forget-follower.html). This privilege is necessary only on clusters that contain leader indices. + + This privilege is not available in {{serverless-full}}. + + +`monitor` +: All actions that are required for monitoring (recovery, segments info, index stats and status). + +`read` +: Read-only access to actions (count, explain, get, mget, get indexed scripts, more like this, multi percolate/search/termvector, percolate, scroll, clear_scroll, search, suggest, tv). + +`read_cross_cluster` +: Read-only access to the search action from a [remote cluster](../../remote-clusters.md). + + This privilege is not available in {{serverless-full}}. + + +`view_index_metadata` +: Read-only access to index and data stream metadata (aliases, exists, field capabilities, field mappings, get index, get data stream, ilm explain, mappings, search shards, settings, validate query). This privilege is available for use primarily by {{kib}} users. + +`write` +: Privilege to perform all write operations to documents, which includes the permission to index, update, and delete documents as well as performing bulk operations, while also allowing to dynamically update the index mapping. + + [8.0] It also grants the permission to update the index mapping (but not the data streams mapping), using the [updating mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html). This will be retracted in a future major release. + + + +## Run as privilege [_run_as_privilege] + +The `run_as` permission enables an authenticated user to submit requests on behalf of another user. The value can be a user name or a comma-separated list of user names. (You can also specify users as an array of strings or a YAML sequence.) For more information, see [Submitting requests on behalf of other users](submitting-requests-on-behalf-of-other-users.md). + +This privilege is not available in {{serverless-full}}. + + +## Application privileges [application-privileges] + +Application privileges are managed within {{es}} and can be retrieved with the [has privileges API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges.html) and the [get application privileges API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html). They do not, however, grant access to any actions or resources within {{es}}. Their purpose is to enable applications to represent and store their own privilege models within {{es}} roles. + +To create application privileges, use the [add application privileges API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-privileges.html). You can then associate these application privileges with roles, as described in [Defining roles](defining-roles.md). + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication.md b/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication.md new file mode 100644 index 000000000..a2bbca6e0 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication.md @@ -0,0 +1,3 @@ +# External authentication + +% What needs to be done: Write from scratch \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md new file mode 100644 index 000000000..a2718bfde --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -0,0 +1,19 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/file-realm.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-users-and-roles.html +--- + +# File-based + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/file-realm.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md +% Notes: file realm content + +$$$file-realm-configuration$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md b/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md new file mode 100644 index 000000000..e3cc720c3 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md @@ -0,0 +1,71 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/securing-aliases.html +--- + +# Granting privileges for data streams and aliases [securing-aliases] + +{{es}} {security-features} allow you to secure operations executed against [data streams](../../../manage-data/data-store/index-types/data-streams.md) and [aliases](../../../manage-data/data-store/aliases.md). + +## Data stream privileges [data-stream-privileges] + +Use [index privileges](elasticsearch-privileges.md#privileges-list-indices) to control access to a data stream. Granting privileges on a data stream grants the same privileges on its backing indices. + +For example, `my-data-stream` consists of two backing indices: `.ds-my-data-stream-2099.03.07-000001` and `.ds-my-data-stream-2099.03.08-000002`. + +A user is granted the `read` privilege to `my-data-stream`. + +```js +{ + "names" : [ "my-data-stream" ], + "privileges" : [ "read" ] +} +``` + +Because the user is automatically granted the same privileges to the stream’s backing indices, the user can retrieve a document directly from `.ds-my-data-stream-2099.03.08-000002`: + +```console +GET .ds-my-data-stream-2099.03.08-000002/_doc/2 +``` + +Later `my-data-stream` [rolls over](../../../manage-data/data-store/index-types/use-data-stream.md#manually-roll-over-a-data-stream). This creates a new backing index: `.ds-my-data-stream-2099.03.09-000003`. Because the user still has the `read` privilege for `my-data-stream`, the user can retrieve documents directly from `.ds-my-data-stream-2099.03.09-000003`: + +```console +GET .ds-my-data-stream-2099.03.09-000003/_doc/2 +``` + + +## Alias privileges [index-alias-privileges] + +Use [index privileges](elasticsearch-privileges.md#privileges-list-indices) to control access to an [alias](../../../manage-data/data-store/aliases.md). Privileges on an index or data stream do not grant privileges on its aliases. For information about managing aliases, see [*Aliases*](../../../manage-data/data-store/aliases.md). + +::::{important} +Don’t use [filtered aliases](../../../manage-data/data-store/aliases.md#filter-alias) in place of [document level security](controlling-access-at-document-field-level.md). {{es}} doesn’t always apply alias filters. +:::: + + +For example, the `current_year` alias points only to the `2015` index. A user is granted the `read` privilege for the `2015` index. + +```js +{ + "names" : [ "2015" ], + "privileges" : [ "read" ] +} +``` + +When the user attempts to retrieve a document from the `current_year` alias, {{es}} rejects the request. + +```console +GET current_year/_doc/1 +``` + +To retrieve documents from `current_year`, the user must have the `read` index privilege for the alias. + +```js +{ + "names" : [ "current_year" ], + "privileges" : [ "read" ] +} +``` + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/internal-authentication.md b/deploy-manage/users-roles/cluster-or-deployment-auth/internal-authentication.md new file mode 100644 index 000000000..835d5e397 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/internal-authentication.md @@ -0,0 +1,3 @@ +# Internal authentication + +% What needs to be done: Write from scratch \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/internal-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/internal-users.md new file mode 100644 index 000000000..41c9fe1bb --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/internal-users.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/internal-users.html +--- + +# Internal users [internal-users] + +::::{note} +These users are designed for internal use by {{es}} only. Authenticating with these users is not supported. +:::: + + +The {{stack-security-features}} use eight *internal* users (`_system`, `_xpack`, `_xpack_security`, `_async_search`, `_security_profile`, `_data_stream_lifecycle`, `_synonyms` and `_storage`), which are responsible for the operations that take place inside an {{es}} cluster. + +These users are only used by requests that originate from within the cluster. For this reason, they cannot be used to authenticate against the API and there is no password to manage or reset. + +From time-to-time you may find a reference to one of these users inside your logs, including [audit logs](../../monitor/logging-configuration/enabling-elasticsearch-audit-logs.md). + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md new file mode 100644 index 000000000..8dc82c84e --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -0,0 +1,24 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud/current/ec-securing-clusters-JWT.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-clusters-JWT.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-securing-clusters-JWT.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/jwt-auth-realm.html +--- + +# JWT + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud/ec-securing-clusters-JWT.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-securing-clusters-JWT.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-securing-clusters-JWT.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/jwt-auth-realm.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$jwt-realm-runas$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kerberos.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kerberos.md new file mode 100644 index 000000000..8d71b1972 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kerberos.md @@ -0,0 +1,20 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-secure-clusters-kerberos.html + - https://www.elastic.co/guide/en/cloud/current/ec-secure-clusters-kerberos.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-secure-clusters-kerberos.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/kerberos-realm.html +--- + +# Kerberos + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-secure-clusters-kerberos.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-secure-clusters-kerberos.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-secure-clusters-kerberos.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/kerberos-realm.md \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md new file mode 100644 index 000000000..bc27c1b1d --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md @@ -0,0 +1,99 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/kibana-privileges.html +--- + +# Kibana privileges [kibana-privileges] + +{{kib}} privileges grant users access to features within {{kib}}. Roles have privileges to determine whether users have write or read access. + +## Base privileges [_base_privileges] + +Assigning a base privilege grants access to all {{kib}} features, such as **Discover**, **Dashboard**, **Visualize Library**, and **Canvas**. + +$$$kibana-privileges-all$$$ + +`all` +: Grants full read-write access. + +`read` +: Grants read-only access. + +### Assigning base privileges [_assigning_base_privileges] + +From the role management screen: + +:::{image} ../../../images/kibana-assign-base-privilege.png +:alt: Assign base privilege +:class: screenshot +::: + +Using the [role APIs](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-roles): + +```js +PUT /api/security/role/my_kibana_role +{ + "elasticsearch": { + "cluster" : [ ], + "indices" : [ ] + }, + "kibana": [ + { + "base": ["all"], + "feature": {}, + "spaces": ["marketing"] + } + ] +} +``` + + + +## Feature privileges [kibana-feature-privileges] + +Assigning a feature privilege grants access to a specific feature. + +`all` +: Grants full read-write access. + +`read` +: Grants read-only access. + +### Sub-feature privileges [_sub_feature_privileges] + +Some features allow for finer access control than the `all` and `read` privileges. This additional level of control is a [subscription feature](https://www.elastic.co/subscriptions). + + +### Assigning feature privileges [_assigning_feature_privileges] + +From the role management screen: + +:::{image} ../../../images/kibana-assign-subfeature-privilege.png +:alt: Assign feature privilege +:class: screenshot +::: + +Using the [role APIs](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-roles): + +```js +PUT /api/security/role/my_kibana_role +{ + "elasticsearch": { + "cluster" : [ ], + "indices" : [ ] + }, + "kibana": [ + { + "base": [], + "feature": { + "visualize_v2": ["all"], + "dashboard_v2": ["read", "url_create"] + }, + "spaces": ["marketing"] + } + ] +} +``` + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md b/deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md new file mode 100644 index 000000000..d286aac88 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md @@ -0,0 +1,26 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/ldap-realm.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-clusters-ldap.html +--- + +# LDAP + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/ldap-realm.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-securing-clusters-ldap.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ldap-realm-configuration$$$ + +$$$tls-ldap$$$ + +$$$mapping-roles-ldap$$$ + +$$$ldap-user-metadata$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/looking-up-users-without-authentication.md b/deploy-manage/users-roles/cluster-or-deployment-auth/looking-up-users-without-authentication.md new file mode 100644 index 000000000..a29a5e0a2 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/looking-up-users-without-authentication.md @@ -0,0 +1,40 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/user-lookup.html +--- + +# Looking up users without authentication [user-lookup] + +{{es}} [realms](authentication-realms.md) exist primarily to support [user authentication](user-authentication.md). Some realms authenticate users with a password (such as the [`native`](native.md) and [`ldap`](ldap.md) realms), and other realms use more complex authentication protocols (such as the [`saml`](saml.md) and [`oidc`](openid-connect.md) realms). In each case, the *primary* purpose of the realm is to establish the identity of the user who has made a request to the {{es}} API. + +However, some {{es}} features need to *look up* a user without using their credentials. + +* The [`run_as`](submitting-requests-on-behalf-of-other-users.md) feature executes requests on behalf of another user. An authenticated user with `run_as` privileges can perform requests on behalf of another unauthenticated user. +* The [delegated authorization](realm-chains.md#authorization_realms) feature links two realms together so that a user who authenticates against one realm can have the roles and metadata associated with a user from a different realm. + +In each of these cases, a user must first authenticate to one realm and then {{es}} will query the second realm to find another user. The authenticated user credentials are used to authenticate in the first realm only, The user in the second realm is retrieved by username, without needing credentials. + +When {{es}} resolves a user using their credentials (as performed in the first realm), it is known as *user authentication*. + +When {{es}} resolves a user using the username only (as performed in the second realm), it is known as *user lookup*. + +See the [run_as](submitting-requests-on-behalf-of-other-users.md) and [delegated authorization](realm-chains.md#authorization_realms) documentation to learn more about these features, including which realms and authentication methods support `run_as` or delegated authorization. In both cases, only the following realms can be used for the user lookup: + +* The reserved, [`native`](native.md) and [`file`](file-based.md) realms always support user lookup. +* The [`ldap`](ldap.md) realm supports user lookup when the realm is configured in [*user search* mode](ldap.md#ldap-realm-configuration). User lookup is not support when the realm is configured with `user_dn_templates`. +* User lookup support in the [`active_directory`](active-directory.md) realm requires that the realm be configured with a [`bind_dn`](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-ad-settings) and a bind password. + +The `pki`, `saml`, `oidc`, `kerberos` and `jwt` realms do not support user lookup. + +::::{note} +If you want to use a realm only for user lookup and prevent users from authenticating against that realm, you can [configure the realm](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-realm-settings) and set `authentication.enabled` to `false` +:::: + + +The user lookup feature is an internal capability that is used to implement the `run-as` and delegated authorization features - there are no APIs for user lookup. If you wish to test your user lookup configuration, then you can do this with `run_as`. Use the [Authenticate](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-authenticate.html) API, authenticate as a `superuser` (e.g. the builtin `elastic` user) and specify the [`es-security-runas-user` request header](submitting-requests-on-behalf-of-other-users.md). + +::::{note} +The [Get users](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-user.html) API and [User profiles](user-profiles.md) feature are alternative ways to retrieve information about a {{stack}} user. Those APIs are not related to the user lookup feature. +:::: + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md b/deploy-manage/users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md new file mode 100644 index 000000000..f682cc419 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md @@ -0,0 +1,497 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-auth-config-using-stack-config-policy.html +--- + +# Manage authentication for multiple clusters [k8s-auth-config-using-stack-config-policy] + +::::{warning} +We have identified an issue with Elasticsearch 8.15.1 and 8.15.2 that prevents security role mappings configured via Stack configuration policies to work correctly. Avoid these versions and upgrade to 8.16.0 to remedy this issue if you are affected. +:::: + + +::::{note} +This requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +ECK `2.11.0` extends the functionality of [Elastic Stack configuration policies](../../deploy/cloud-on-k8s/elastic-stack-configuration-policies.md) so that it becomes possible to configure Elasticsearch security realms for more than one Elastic stack at once. The authentication will apply to all Elasticsearch clusters and Kibana instances managed by the Elastic Stack configuration policy. + +Examples for configuring some of the authentication methods can be found below: + +* [LDAP authentication using Elastic Stack configuration policy](#k8s-ldap-using-stack-config-policy) +* [OpenID Connect authentication using Elastic Stack configuration policy](#k8s-oidc-stack-config-policy) +* [JWT authentication using Elastic Stack configuration policy](#k8s-jwt-stack-config-policy) + +## LDAP using Elastic stack configuration policy [k8s-ldap-using-stack-config-policy] + +::::{warning} +We have identified an issue with Elasticsearch 8.15.1 and 8.15.2 that prevents security role mappings configured via Stack configuration policies to work correctly. Avoid these versions and upgrade to 8.16.0 to remedy this issue if you are affected. +:::: + + +::::{note} +This requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +::::{tip} +Make sure you check the complete [guide to setting up LDAP with Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/ldap-realm.html). +:::: + + +### To configure LDAP using Elastic Stack configuration policy with user search: [k8s_to_configure_ldap_using_elastic_stack_configuration_policy_with_user_search] + +1. Add a realm configuration to the `config` field under `elasticsearch` in the `xpack.security.authc.realms.ldap` namespace. At a minimum, you must specify the URL of the LDAP server and the order of the LDAP realm compared to other configured security realms. You also have to set `user_search.base_dn` to the container DN where the users are searched for. Refer to [LDAP realm settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-ldap-settings) for all of the options you can set for an LDAP realm. For example, the following snippet shows an LDAP realm configured with a user search: + + ```yaml + elasticsearch: + config: + xpack.security.authc.realms: + ldap: + ldap1: + order: 0 + url: "ldap://openldap.default.svc.cluster.local:1389" + bind_dn: "cn=admin,dc=example,dc=org" + user_search: + base_dn: "dc=example,dc=org" + filter: "(cn={0})" + group_search: + base_dn: "dc=example,dc=org" + unmapped_groups_as_roles: false + ``` + +2. The password for the `bind_dn` user should be configured by adding the appropriate `secure_bind_password` setting to the Elasticsearch keystore. This can be done using the Elastic Stack configuration policy by following the below steps: + + 1. Create a secret that has the `secure_bind_password` in the same namespace as the operator + + ```sh + kubectl create secret generic ldap-secret --from-literal=xpack.security.authc.realms.ldap.ldap1.secure_bind_password= + ``` + + 2. Add the secret name to the `secureSettings` field under `elasticsearch` in the Elastic Stack configuration policy + + ```yaml + spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + secureSettings: + - secretName: ldap-secret + ``` + +3. Map LDAP groups to roles. In the below example, LDAP users get the Elasticsearch `superuser` role. `dn: "cn=users,dc=example,dc=org"` is the LDAP distinguished name (DN) of the users group. + + ```yaml + securityRoleMappings: + ldap_role: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "ldap1" } + - field: { dn: "cn=users,dc=example,dc=org" } + enabled: true + ``` + + +Simple full example Elastic Stack config policy to configure LDAP realm with user search + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy +spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + secureSettings: + - secretName: ldap-secret + securityRoleMappings: + ldap_role: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "ldap1" } + - field: { dn: "cn=users,dc=example,dc=org" } + enabled: true + config: + xpack.security.authc.realms: + ldap: + ldap1: + order: 0 + url: "ldap://openldap.default.svc.cluster.local:1389" + bind_dn: "cn=admin,dc=example,dc=org" + user_search: + base_dn: "dc=example,dc=org" + filter: "(cn={0})" + group_search: + base_dn: "dc=example,dc=org" + unmapped_groups_as_roles: false +``` + + +### To configure an LDAP realm with user DN templates: [k8s_to_configure_an_ldap_realm_with_user_dn_templates] + +Add a realm configuration to `elasticsearch.yml` in the xpack.security.authc.realms.ldap namespace. At a minimum, you must specify the url and order of the LDAP server, and specify at least one template with the user_dn_templates option. Check [LDAP realm settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-ldap-settings) for all of the options you can set for an ldap realm. + +For example, the following snippet shows an LDAP realm configured with user DN templates: + +```yaml +xpack: + security: + authc: + realms: + ldap: + ldap1: + order: 0 + url: "ldaps://ldap.example.com:636" + user_dn_templates: + - "cn={0}, ou=users, dc=example, dc=org" + group_search: + base_dn: "dc=example,dc=org" + unmapped_groups_as_roles: false +``` + +Example Elastic Stack config policy to configure LDAP realm with user DN templates: + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy +spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + securityRoleMappings: + ldap_role: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "ldap1" } + - field: { dn: "*,ou=users,dc=example,dc=org" } + enabled: true + config: + xpack.security.authc.realms: + ldap: + ldap1: + order: 0 + url: "ldaps://ldap.example.com:636" + user_dn_templates: + - "cn={0}, ou=users, dc=example, dc=org" + group_search: + base_dn: "dc=example,dc=org" + unmapped_groups_as_roles: false +``` + +The `bind_dn` setting is not used in template mode. All LDAP operations run as the authenticating user. So there is no need of setting up any additional secrets to be stored in the keystore. + + + +## OIDC using Elastic stack configuration policy [k8s-oidc-stack-config-policy] + +::::{warning} +We have identified an issue with Elasticsearch 8.15.1 and 8.15.2 that prevents security role mappings configured via Stack configuration policies to work correctly. Avoid these versions and upgrade to 8.16.0 to remedy this issue if you are affected. +:::: + + +::::{note} +This requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +::::{tip} +Make sure you check the complete [guide to setting up OpenID Connect with Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/oidc-guide.html). +:::: + + +Configuring OpenID Connect using Elastic Stack configuration policy + +1. Add OIDC realm to the `elasticsearch.yml` file using the `config` field under `elasticsearch` in the Elastic Stack configuration policy, also enable token service. + + ::::{note} + Below snippet is an example of using Google as OpenID provider, the values will change depending on the provider being used. + :::: + + + ```yaml + elasticsearch: + config: + xpack: + security: + authc: + token.enabled: true + realms: + oidc: + oidc1: + order: 2 + rp.client_id: "" + rp.response_type: "code" + rp.requested_scopes: ["openid", "email"] + rp.redirect_uri: "${KIBANA_URL}/api/security/oidc/callback" + op.issuer: "https://accounts.google.com" + op.authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth" + op.token_endpoint: "https://oauth2.googleapis.com/token" + op.userinfo_endpoint: "https://openidconnect.googleapis.com/v1/userinfo" + op.jwkset_path: "https://www.googleapis.com/oauth2/v3/certs" + claims.principal: email + claim_patterns.principal: "^([^@]+)@elastic\\.co$" + ``` + +2. Another piece of configuration of the OpenID Connect realm is to set the Client Secret that was assigned to the Relying Parties (RP) during registration in the OpenID Connect Provider (OP). This is a secure setting and as such is not defined in the realm configuration in `elasticsearch.yml` but added to the Elasticsearch keystore. To set this up using Elastic Stack configuration policy, use the following steps. + + 1. Create a secret in the operator namespace that has the Client Secret + + ```sh + kubectl create secret generic oidc-client-secret --from-literal=xpack.security.authc.realms.oidc.oidc1.rp.client_secret= + ``` + + 2. Add the secret name to the `secureSettings` field under `elasticsearch` + + ```yaml + elasticsearch: + secureSettings: + - secretName: oidc-client-secret + ``` + +3. When a user authenticates using OpenID Connect, they are identified to the Elastic Stack, but this does not automatically grant them access to perform any actions or access any data. Your OpenID Connect users cannot do anything until they are assigned roles. Roles can be assigned by adding role mappings to the Elastic Stack configuration policy. The below example is giving a specific user access as a superuser to Elasticsearch, if you want to assign roles to all users authenticating with OIDC, you can remove the username field. + + ```yaml + elasticsearch: + secureSettings: + - secretName: oidc-client-secret + securityRoleMappings: + oidc_kibana: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "oidc1" } + - field: { username: "" } + enabled: true + ``` + +4. Update Kibana to use OpenID Connect as the authentication provider: + + ```yaml + kibana: + config: + xpack.security.authc.providers: + oidc.oidc1: + order: 0 + realm: oidc1 + description: "Log in with GCP" + ``` + + +Example full Elastic Stack configuration policy to configure oidc + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy +spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + secureSettings: + - secretName: oidc-client-secret + securityRoleMappings: + oidc_kibana: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "oidc1" } + - field: { username: "" } + enabled: true + config: + logger.org.elasticsearch.discovery: DEBUG + xpack: + security: + authc: + token.enabled: true + realms: + oidc: + oidc1: + order: 2 + rp.client_id: "" + rp.response_type: "code" + rp.requested_scopes: ["openid", "email"] + rp.redirect_uri: "${KIBANA_URL}/api/security/oidc/callback" <1> + op.issuer: "https://accounts.google.com" + op.authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth" + op.token_endpoint: "https://oauth2.googleapis.com/token" + op.userinfo_endpoint: "https://openidconnect.googleapis.com/v1/userinfo" + op.jwkset_path: "https://www.googleapis.com/oauth2/v3/certs" + claims.principal: email + claim_patterns.principal: "^([^@]+)@elastic\\.co$" + kibana: + config: + xpack.security.authc.providers: + oidc.oidc1: + order: 0 + realm: oidc1 + description: "Log in with GCP" + basic.basic1: + order: 1 +``` + +1. The Kibana URL should be an environment variable that should be configured on the Elasticsearch Clusters managed by the Elastic Stack Configuration policy. This can be done by adding an environment variable to the pod template in the Elasticsearch CR.```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: quickstart + namespace: kvalliy + labels: + env: my-label +spec: + version: 8.10.3 + nodeSets: + - name: default + count: 1 + config: + node.store.allow_mmap: false + podTemplate: + spec: + containers: + - name: elasticsearch + env: + - name: KIBANA_URL + value: "https://kibana.eck-ocp.elastic.dev" +``` + + + +::::{note} +The OpenID Connect Provider (OP) should have support to configure multiple Redirect URLs, so that the same `rp.client_id` and `client_secret` can be used for all the Elasticsearch clusters managed by the Elastic Stack configuration policy. +:::: + + + +## JWT using Elastic Stack configuration policy [k8s-jwt-stack-config-policy] + +::::{warning} +We have identified an issue with Elasticsearch 8.15.1 and 8.15.2 that prevents security role mappings configured via Stack configuration policies to work correctly. Avoid these versions and upgrade to 8.16.0 to remedy this issue if you are affected. +:::: + + +::::{note} +This requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +::::{tip} +Make sure you check the complete [guide to setting up JWT with Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/jwt-auth-realm.html). +:::: + + +Configuring JWT with Elastic Stack configuration policy + +1. Add your JWT realm to the `elasticsearch.yml` file using the `config` field under `elasticsearch` in the Elastic Stack configuration policy + + ```yaml + elasticsearch: + config: + xpack.security.authc.realms.jwt.jwt1: + order: -98 + token_type: id_token + client_authentication.type: shared_secret + allowed_issuer: "https://es.k8s.elastic.co" + allowed_audiences: [ "elasticsearch" ] + allowed_subjects: ["elastic-user"] + allowed_signature_algorithms: [RS512] + pkc_jwkset_path: jwks/jwkset.json + claims.principal: sub + ``` + +2. Add the `shared_secret` setting that will be used for client authentication to the Elasticsearch keystore. + + 1. Create a secret in the operator namespace containing the shared secret + + ```sh + kubectl create secret generic shared-secret --from-literal=xpack.security.authc.realms.jwt.jwt1.client_authentication.shared_secret= + ``` + + 2. Add the secret name to the `secureSettings` field under `elasticsearch` in the Elastic Stack configuration policy + + ```yaml + elasticsearch: + secureSettings: + : - secretName: shared-secret + ``` + +3. Add an additional volume to the Elasticsearch pods that contain the JSON Web Keys, it should be mounted to the path that is configured for the `xpack.security.authc.realms.jwt.jwt1.pkc_jwkset_path` config. The file path is resolved relative to the Elasticsearch configuration directory. + + 1. Create a secret in the operator namespace that has the jwk set + + ```sh + kubectl create secret generic jwks-secret --from-file=jwkset.json + ``` + + 2. Add the secret name and mountpath to the `secretMounts` field under `elasticsearch` in the Elastic Stack configuration policy + + ```yaml + secretMounts: + - secretName: jwks-secret + mountPath: "/usr/share/elasticsearch/config/jwks" + ``` + +4. You can use the `securityRoleMappings` field under `elasticsearch` in the Elastic Stack configuration policy to define role mappings that determine which roles should be assigned to each user based on their username, groups, or other metadata. + + ```yaml + securityRoleMappings: + jwt1-user-role: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "jwt1" } + - field: { username: "jwt-user" } + enabled: true + ``` + + +The following example demonstrates how an Elastic Stack configuration policy can be used to configure a JWT realm: + +```yaml +apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1 +kind: StackConfigPolicy +metadata: + name: test-stack-config-policy +spec: + resourceSelector: + matchLabels: + env: my-label + elasticsearch: + secureSettings: + - secretName: shared-secret + securityRoleMappings: + jwt1-user-role: + roles: [ "superuser" ] + rules: + all: + - field: { realm.name: "jwt1" } + - field: { username: "jwt-user" } + enabled: true + config: + xpack.security.authc.realms.jwt.jwt1: + order: -98 + token_type: id_token + client_authentication.type: shared_secret + allowed_issuer: "https://es.k8s.elastic.co" + allowed_audiences: [ "elasticsearch" ] + allowed_subjects: ["elastic-user"] + allowed_signature_algorithms: [RS512] + pkc_jwkset_path: jwks/jwkset.json + claims.principal: sub + secretMounts: + - secretName: jwks-secret + mountPath: "/usr/share/elasticsearch/config/jwks" +``` + + +$$$k8s-jwt-stack-config-policy$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md new file mode 100644 index 000000000..02c25c269 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md @@ -0,0 +1,28 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-roles.html + - https://www.elastic.co/guide/en/kibana/current/role-mappings.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/role-mapping-resources.html +--- + +# Mapping users and groups to roles + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md +% - [ ] ./raw-migrated-files/kibana/kibana/role-mappings.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$mapping-roles-file$$$ + +$$$ldap-role-mapping$$$ + +$$$mapping-roles-api$$$ + +$$$mapping-roles-rule-field$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/native.md b/deploy-manage/users-roles/cluster-or-deployment-auth/native.md new file mode 100644 index 000000000..4c1103626 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/native.md @@ -0,0 +1,27 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/native-realm.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-users-and-roles.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/change-passwords-native-users.html + - https://www.elastic.co/guide/en/kibana/current/tutorial-secure-access-to-kibana.html +--- + +# Native + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/native-realm.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md +% Notes: native realm content +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/change-passwords-native-users.md +% - [ ] ./raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$k8s-default-elastic-user$$$ + +$$$managing-native-users$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md new file mode 100644 index 000000000..78e259b9b --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md @@ -0,0 +1,69 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/oidc-realm.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/oidc-guide.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-secure-clusters-oidc.html + - https://www.elastic.co/guide/en/cloud/current/ec-secure-clusters-oidc.html + - https://www.elastic.co/guide/en/cloud/current/ec-securing-clusters-oidc-op.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-secure-clusters-oidc.html +--- + +# OpenID Connect + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/oidc-realm.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/oidc-guide.md +% Notes: some steps not needed for cloud / don't work +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-secure-clusters-oidc.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-secure-clusters-oidc.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-securing-clusters-oidc-op.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-secure-clusters-oidc.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$ec-securing-oidc-azure$$$ + +$$$ec-oidc-client-secret$$$ + +$$$ec-oidc-user-settings$$$ + +$$$ec-securing-oidc-google$$$ + +$$$ec-securing-oidc-okta$$$ + +$$$ec-summary-and-references$$$ + +$$$ece-oidc-client-secret$$$ + +$$$ece-oidc-user-settings$$$ + +$$$ech-oidc-client-secret$$$ + +$$$ech-oidc-user-settings$$$ + +$$$oidc-claim-to-property$$$ + +$$$oidc-claims-mappings$$$ + +$$$oidc-configure-kibana$$$ + +$$$oidc-create-realm$$$ + +$$$oidc-elasticsearch-authentication$$$ + +$$$oidc-enable-http$$$ + +$$$oidc-enable-token$$$ + +$$$oidc-guide-op$$$ + +$$$oidc-role-mappings$$$ + +$$$oidc-user-metadata$$$ + +$$$oidc-user-properties$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/operator-only-functionality.md b/deploy-manage/users-roles/cluster-or-deployment-auth/operator-only-functionality.md new file mode 100644 index 000000000..7e148f55e --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/operator-only-functionality.md @@ -0,0 +1,53 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/operator-only-functionality.html +--- + +# Operator-only functionality [operator-only-functionality] + +::::{note} +{cloud-only} +:::: + + +Operator privileges provide protection for APIs and dynamic cluster settings. Any API or cluster setting that is protected by operator privileges is known as *operator-only functionality*. When the operator privileges feature is enabled, operator-only APIs can be executed only by operator users. Likewise, operator-only settings can be updated only by operator users. The list of operator-only APIs and dynamic cluster settings are pre-determined in the codebase. The list may evolve in future releases but it is otherwise fixed in a given {{es}} version. + +## Operator-only APIs [operator-only-apis] + +* [Voting configuration exclusions](https://www.elastic.co/guide/en/elasticsearch/reference/current/voting-config-exclusions.html) +* [Delete license](https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-license.html) +* [Update license](https://www.elastic.co/guide/en/elasticsearch/reference/current/update-license.html) +* [Create or update autoscaling policy](https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-put-autoscaling-policy.html) +* [Delete autoscaling policy](https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-delete-autoscaling-policy.html) +* [Create or update desired nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/update-desired-nodes.html) +* [Get desired nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-desired-nodes.html) +* [Delete desired nodes](https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-desired-nodes.html) +* [Get desired balance](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-desired-balance.html) +* [Reset desired balance](https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-desired-balance.html) + + +## Operator-only dynamic cluster settings [operator-only-dynamic-cluster-settings] + +* All [IP filtering](../../security/ip-traffic-filtering.md) settings +* The following dynamic [machine learning settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-settings.html): + + * `xpack.ml.node_concurrent_job_allocations` + * `xpack.ml.max_machine_memory_percent` + * `xpack.ml.use_auto_machine_memory_percent` + * `xpack.ml.max_lazy_ml_nodes` + * `xpack.ml.process_connect_timeout` + * `xpack.ml.nightly_maintenance_requests_per_second` + * `xpack.ml.max_ml_node_size` + * `xpack.ml.enable_config_migration` + * `xpack.ml.persist_results_max_retries` + +* The [`cluster.routing.allocation.disk.threshold_enabled` setting](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-routing-disk-threshold) +* The following [recovery settings for managed services](https://www.elastic.co/guide/en/elasticsearch/reference/current/recovery.html#recovery-settings-for-managed-services): + + * `node.bandwidth.recovery.operator.factor` + * `node.bandwidth.recovery.operator.factor.read` + * `node.bandwidth.recovery.operator.factor.write` + * `node.bandwidth.recovery.operator.factor.max_overcommit` + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges-for-snapshot-restore.md b/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges-for-snapshot-restore.md new file mode 100644 index 000000000..b32204ed3 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges-for-snapshot-restore.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/operator-only-snapshot-and-restore.html +--- + +# Operator privileges for snapshot and restore [operator-only-snapshot-and-restore] + +::::{note} +{cloud-only} +:::: + + +Invoking [operator-only APIs](operator-only-functionality.md#operator-only-apis) or updating [operator-only dynamic cluster settings](operator-only-functionality.md#operator-only-dynamic-cluster-settings) typically results in changes in the cluster state. The cluster state can be included in a cluster [snapshot](../../tools/snapshot-and-restore.md). Snapshots are a great way to preserve the data of a cluster, which can later be restored to bootstrap a new cluster, perform migration, or disaster recovery, for example. In a traditional self-managed environment, the intention is for the restore process to copy the entire cluster state over when requested. However, in a more managed environment, such as [{{ess}}](https://cloud.elastic.co/registration?page=docs&placement=docs-body), data that is associated with [operator-only functionality](operator-only-functionality.md) is explicitly managed by the infrastructure code. + +Restoring snapshot data associated with operator-only functionality could be problematic because: + +1. A snapshot could contain incorrect values for operator-only functionalities. For example, the snapshot could have been taken in a different cluster where requirements are different or the operator privileges feature is not enabled. Restoring data associated with operator-only functionality breaks the guarantee of operator privileges. +2. Even when the infrastructure code can correct the values immediately after a restore, there will always be a short period of time when the cluster could be in an inconsistent state. +3. The infrastructure code prefers to configure operator-only functionality from a single place, that is to say, through API calls. + +Therefore, [**when the operator privileges feature is enabled**](configure-operator-privileges.md), snapshot data that is associated with any operator-only functionality is **not** restored. + +::::{note} +That information is still included when taking a snapshot so that all data is always preserved. +:::: + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges.md new file mode 100644 index 000000000..9e530ee70 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/operator-privileges.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/operator-privileges.html +--- + +# Operator privileges [operator-privileges] + +::::{note} +{cloud-only} +:::: + + +With a typical {{es}} deployment, people who administer the cluster also operate the cluster at the infrastructure level. User authorization based on [role-based access control (RBAC)](user-roles.md) is effective and reliable for this environment. However, in more managed environments, such as [{{ess}}](https://cloud.elastic.co/registration?page=docs&placement=docs-body), there is a distinction between the operator of the cluster infrastructure and the administrator of the cluster. + +Operator privileges limit some functionality to operator users *only*. Operator users are just regular {{es}} users with access to specific [operator-only functionality](operator-only-functionality.md). These privileges are not available to cluster administrators, even if they log in as a highly privileged user such as the `elastic` user or another user with the `superuser` role. By limiting system access, operator privileges enhance the {{es}} security model while safeguarding user capabilities. + +Operator privileges are enabled on {{ecloud}}, which means that some infrastructure management functionality is restricted and cannot be accessed by your administrative users. This capability protects your cluster from unintended infrastructure changes. + + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md new file mode 100644 index 000000000..9cb96aaff --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -0,0 +1,198 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/pki-realm.html +--- + +# PKI [pki-realm] + +You can configure {{es}} to use Public Key Infrastructure (PKI) certificates to authenticate users. In this scenario, clients connecting directly to {{es}} must present X.509 certificates. First, the certificates must be accepted for authentication on the SSL/TLS layer on {{es}}. Then they are optionally further validated by a PKI realm. See [PKI authentication for clients connecting directly to {{es}}](#pki-realm-for-direct-clients). + +You can also use PKI certificates to authenticate to {{kib}}, however this requires some additional configuration. On {{es}}, this configuration enables {{kib}} to act as a proxy for SSL/TLS authentication and to submit the client certificates to {{es}} for further validation by a PKI realm. See [PKI authentication for clients connecting to {{kib}}](#pki-realm-for-proxied-clients). + +## PKI authentication for clients connecting directly to {{es}} [pki-realm-for-direct-clients] + +To use PKI in {{es}}, you configure a PKI realm, enable client authentication on the desired network layers (transport or http), and map the Distinguished Names (DNs) from the Subject field in the user certificates to roles. You create the mappings in a role mapping file or use the role mappings API. + +1. Add a realm configuration for a `pki` realm to `elasticsearch.yml` under the `xpack.security.authc.realms.pki` namespace. You must explicitly set the `order` attribute. See [PKI realm settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-pki-settings) for all of the options you can set for a `pki` realm. + + For example, the following snippet shows the most basic `pki` realm configuration: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + ``` + + With this configuration, any certificate trusted by the {{es}} SSL/TLS layer is accepted for authentication. The username is the common name (CN) extracted from the DN in the Subject field of the end-entity certificate. This configuration is not sufficient to permit PKI authentication to {{kib}}; additional steps are required. + + ::::{important} + When you configure realms in `elasticsearch.yml`, only the realms you specify are used for authentication. If you also want to use the `native` or `file` realms, you must include them in the realm chain. + :::: + +2. Optional: The username is defined by the [username_pattern](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-pki-settings). If you want to use something other than the CN of the Subject DN as the username, you can specify a regex to extract the desired username. The regex is applied on the Subject DN. + + For example, the regex in the following configuration extracts the email address from the Subject DN: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" + ``` + + ::::{note} + If the regex is too restrictive and does not match the Subject DN of the client’s certificate, then the realm does not authenticate the certificate. + :::: + +3. Optional: If you want the same users to also be authenticated using certificates when they connect to {{kib}}, you must configure the {{es}} PKI realm to allow delegation. See [PKI authentication for clients connecting to {{kib}}](#pki-realm-for-proxied-clients). +4. Restart {{es}} because realm configuration is not reloaded automatically. If you’re following through with the next steps, you might wish to hold the restart for last. +5. [Enable SSL/TLS](../../security/secure-cluster-communications.md#encrypt-internode-communication). +6. Enable client authentication on the desired network layers (transport or http). + + ::::{important} + To use PKI when clients connect directly to {{es}}, you must enable SSL/TLS with client authentication. That is to say, you must set `xpack.security.transport.ssl.client_authentication` and `xpack.security.http.ssl.client_authentication` to `optional` or `required`. If the setting value is `optional`, clients without certificates can authenticate with other credentials. + :::: + + + When clients connect directly to {{es}} and are not proxy-authenticated, the PKI realm relies on the TLS settings of the node’s network interface. The realm can be configured to be more restrictive than the underlying network connection. That is, it is possible to configure the node such that some connections are accepted by the network interface but then fail to be authenticated by the PKI realm. However, the reverse is not possible. The PKI realm cannot authenticate a connection that has been refused by the network interface. + + In particular this means: + + * The transport or http interface must request client certificates by setting `client_authentication` to `optional` or `required`. + * The interface must *trust* the certificate that is presented by the client by configuring either the `truststore` or `certificate_authorities` paths, or by setting `verification_mode` to `none`. + * The *protocols* supported by the interface must be compatible with those used by the client. + + For an explanation of these settings, see [General TLS settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ssl-tls-settings). + + The relevant network interface (transport or http) must be configured to trust any certificate that is to be used within the PKI realm. However, it is possible to configure the PKI realm to trust only a *subset* of the certificates accepted by the network interface. This is useful when the SSL/TLS layer trusts clients with certificates that are signed by a different CA than the one that signs your users' certificates. + + To configure the PKI realm with its own truststore, specify the `truststore.path` option. The path must be located within the Elasticsearch configuration directory (`ES_PATH_CONF`). For example: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + truststore: + path: "pki1_truststore.jks" + ``` + + If the truststore is password protected, the password should be configured by adding the appropriate `secure_password` setting to the {{es}} keystore. For example, the following command adds the password for the example realm above: + + ```shell + bin/elasticsearch-keystore add \ + xpack.security.authc.realms.pki.pki1.truststore.secure_password + ``` + + The `certificate_authorities` option can be used as an alternative to the `truststore.path` setting, when the certificate files are PEM formatted. The setting accepts a list. The two options are exclusive, they cannot be both used simultaneously. + +7. Map roles for PKI users. + + You map roles for PKI users through the [role mapping APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html#security-role-mapping-apis) or by using a file stored on each node. Both configuration options are merged together. When a user authenticates against a PKI realm, the privileges for that user are the union of all privileges defined by the roles to which the user is mapped. + + You identify a user by the distinguished name in their certificate. For example, the following mapping configuration maps `John Doe` to the `user` role using the role mapping API: + + ```console + PUT /_security/role_mapping/users + { + "roles" : [ "user" ], + "rules" : { "field" : { + "dn" : "cn=John Doe,ou=example,o=com" <1> + } }, + "enabled": true + } + ``` + + 1. The distinguished name (DN) of a PKI user. + + + Alternatively, use a role-mapping file. For example: + + ```yaml + user: <1> + - "cn=John Doe,ou=example,o=com" <2> + ``` + + 1. The name of a role. + 2. The distinguished name (DN) of a PKI user. + + + The file’s path defaults to `ES_PATH_CONF/role_mapping.yml`. You can specify a different path (which must be within `ES_PATH_CONF`) by using the `files.role_mapping` realm setting (e.g. `xpack.security.authc.realms.pki.pki1.files.role_mapping`). + + The distinguished name for a PKI user follows X.500 naming conventions which place the most specific fields (like `cn` or `uid`) at the beginning of the name and the most general fields (like `o` or `dc`) at the end of the name. Some tools, such as *openssl*, may print out the subject name in a different format. + + One way that you can determine the correct DN for a certificate is to use the [authenticate API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-authenticate.html) (use the relevant PKI certificate as the means of authentication) and inspect the metadata field in the result. The user’s distinguished name will be populated under the `pki_dn` key. You can also use the authenticate API to validate your role mapping. + + For more information, see [Mapping users and groups to roles](mapping-users-groups-to-roles.md). + + ::::{note} + The PKI realm supports [authorization realms](realm-chains.md#authorization_realms) as an alternative to role mapping. + :::: + + + +## PKI authentication for clients connecting to {{kib}} [pki-realm-for-proxied-clients] + +By default, the PKI realm relies on the node’s network interface to perform the SSL/TLS handshake and extract the client certificate. This behaviour requires that clients connect directly to {{es}} so that their SSL connection is terminated by the {{es}} node. If SSL/TLS authentication is to be performed by {{kib}}, the PKI realm must be configured to permit delegation. + +Specifically, when clients presenting X.509 certificates connect to {{kib}}, {{kib}} performs the SSL/TLS authentication. {{kib}} then forwards the client’s certificate chain (by calling an {{es}} API) to have them further validated by the PKI realms that have been configured for delegation. + +To permit authentication delegation for a specific {{es}} PKI realm, start by configuring the realm for the usual case, as detailed in the [PKI authentication for clients connecting directly to {{es}}](#pki-realm-for-direct-clients) section. In this scenario, when you enable TLS, it is mandatory that you [encrypt HTTP client communications](../../security/secure-http-communications.md#encrypt-http-communication). + +You must also explicitly configure a `truststore` (or, equivalently `certificate_authorities`) even though it is the same trust configuration that you have configured on the network layer. The `xpack.security.authc.token.enabled` and `delegation.enabled` settings must also be `true`. For example: + +```yaml +xpack: + security: + authc: + token.enabled: true + realms: + pki: + pki1: + order: 1 + delegation.enabled: true + truststore: + path: "pki1_truststore.jks" +``` + +After you restart {{es}}, this realm can validate delegated PKI authentication. You must then [configure {{kib}} to allow PKI certificate authentication](user-authentication.md#pki-authentication). + +A PKI realm with `delegation.enabled` still works unchanged for clients connecting directly to {{es}}. Directly authenticated users and users that are PKI authenticated by delegation to {{kib}} both follow the same [role mapping rules](mapping-users-groups-to-roles.md) or [authorization realms configurations](realm-chains.md#authorization_realms). + +If you use the [role mapping APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html#security-role-mapping-apis), however, you can distinguish between users that are authenticated by delegation and users that are authenticated directly. The former have the extra fields `pki_delegated_by_user` and `pki_delegated_by_realm` in the user’s metadata. In the common setup, where authentication is delegated to {{kib}}, the values of these fields are `kibana` and `reserved`, respectively. For example, the following role mapping rule assigns the `role_for_pki1_direct` role to all users that have been authenticated directly by the `pki1` realm, by connecting to {{es}} instead of going through {{kib}}: + +```console +PUT /_security/role_mapping/direct_pki_only +{ + "roles" : [ "role_for_pki1_direct" ], + "rules" : { + "all": [ + { + "field": {"realm.name": "pki1"} + }, + { + "field": { + "metadata.pki_delegated_by_user": null <1> + } + } + ] + }, + "enabled": true +} +``` + +1. If this metadata field is set (that is to say, it is **not** `null`), the user has been authenticated in the delegation scenario. + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/quickstart.md b/deploy-manage/users-roles/cluster-or-deployment-auth/quickstart.md new file mode 100644 index 000000000..aab11649c --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/quickstart.md @@ -0,0 +1,149 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/tutorial-secure-access-to-kibana.html +--- + +# Quickstart [tutorial-secure-access-to-kibana] + +{{kib}} is home to an ever-growing suite of powerful features, which help you get the most out of your data. Your data is important, and should be protected. {{kib}} allows you to secure access to your data and control how users are able to interact with your data. + +For example, some users might only need to view your stunning dashboards, while others might need to manage your fleet of Elastic agents and run machine learning jobs to detect anomalous behavior in your network. + +This guide introduces you to three of {{kib}}'s security features: spaces, roles, and users. By the end of this tutorial, you will learn how to manage these entities, and how you can leverage them to secure access to both {{kib}} and your data. + + +## Spaces [_spaces] + +Do you have multiple teams using {{kib}}? Do you want a “playground” to experiment with new visualizations or rules? If so, then [{{kib}} Spaces](../../manage-spaces.md) can help. + +Think of a space as another instance of {{kib}}. A space allows you to organize your [dashboards](../../../explore-analyze/dashboards.md), [rules](../../../explore-analyze/alerts/kibana.md), [machine learning jobs](../../../explore-analyze/machine-learning/machine-learning-in-kibana.md), and much more into their own categories. For example, you might have a Marketing space for your marketeers to track the results of their campaigns, and an Engineering space for your developers to [monitor application performance](https://www.elastic.co/guide/en/apm/guide/current/apm-overview.html). + +The assets you create in one space are isolated from other spaces, so when you enter a space, you only see the assets that belong to that space. + +Refer to the [Spaces documentation](../../manage-spaces.md) for more information. + + +## Roles [_roles] + +Once your spaces are setup, the next step to securing access is to provision your roles. Roles are a collection of privileges that allow you to perform actions in {{kib}} and Elasticsearch. Roles are assigned to users, and to [system accounts](built-in-users.md) that power the Elastic Stack. + +You can create your own roles, or use any of the [built-in roles](built-in-roles.md). Some built-in roles are intended for Elastic Stack components and should not be assigned to end users directly. + +One of the more useful built-in roles is `kibana_admin`. Assigning this role to your users will grant access to all of {{kib}}'s features. This includes the ability to manage Spaces. + +The built-in roles are great for getting started with the Elastic Stack, and for system administrators who do not need more restrictive access. With so many features, it’s not possible to ship more granular roles to accommodate everyone’s needs. This is where custom roles come in. + +As an administrator, you have the ability to create your own roles to describe exactly the kind of access your users should have. For example, you might create a `marketing_user` role, which you then assign to all users in your marketing department. This role would grant access to all of the necessary data and features for this team to be successful, without granting them access they don’t require. + + +## Users [_users] + +Once your roles are setup, the next step to securing access is to create your users, and assign them one or more roles. {{kib}}'s user management allows you to provision accounts for each of your users. + +::::{tip} +Want Single Sign-on? {{kib}} supports a wide range of SSO implementations, including SAML, OIDC, LDAP/AD, and Kerberos. [Learn more about {{kib}}'s SSO features](user-authentication.md). +:::: + + + +## Example: Create a user with access only to dashboards [tutorial-secure-kibana-dashboards-only] + +Let’s work through an example together. Consider a marketing analyst who wants to monitor the effectiveness of their campaigns. They should be able to see their team’s dashboards, but not be allowed to view or manage anything else in {{kib}}. All of the team’s dashboards are located in the Marketing space. + + +### Create a space [_create_a_space] + +Create a Marketing space for your marketing analysts to use. + +1. Go to the **Spaces** management page using the navigation menu or the [global search field](../../../get-started/the-stack.md#kibana-navigation-search). +2. Click **Create a space**. +3. Give this space a unique name. For example: `Marketing`. +4. Click **Create space**. + + If you’ve followed the example above, you should end up with a space that looks like this: + + :::{image} ../../../images/kibana-tutorial-secure-access-example-1-space.png + :alt: Create space UI + :class: screenshot + ::: + + + +### Create a role [_create_a_role] + +To effectively use dashboards, create a role that describes the privileges you want to grant. In this example, a marketing analyst will need: + +* Access to **read** the data that powers the dashboards +* Access to **read** the dashboards within the `Marketing` space + +To create the role: + +1. Go to the **Roles** management page using the navigation menu or the [global search field](../../../get-started/the-stack.md#kibana-navigation-search). +2. Click **Create role**. +3. Give this role a unique name. For example: `marketing_dashboards_role`. +4. For this example, you want to store all marketing data in the `acme-marketing-*` set of indices. To grant this access, locate the **Index privileges** section and enter: + + 1. `acme-marketing-*` in the **Indices** field. + 2. `read` and `view_index_metadata` in the **Privileges** field. + + ::::{tip} + You can add multiple patterns of indices, and grant different access levels to each. Click **Add index privilege** to grant additional access. + :::: + +5. To grant access to dashboards in the `Marketing` space, locate the {{kib}} section, and click **Add {{kib}} privilege**: + + 1. From the **Spaces** dropdown, select the `Marketing` space. + 2. Expand the **Analytics*** section, and select the ***Read*** privilege for ***Dashboard**. + 3. Click **Add Kibana privilege**. + +6. Click **Create role**. + + If you’ve followed the example above, you should end up with a role that looks like this: + + :::{image} ../../../images/kibana-tutorial-secure-access-example-1-role.png + :alt: Create role UI + :class: screenshot + ::: + + + +### Create a user [_create_a_user] + +Now that you created a role, create a user account. + +1. Navigate to **Stack Management**, and under **Security**, select **Users**. +2. Click **Create user**. +3. Give this user a descriptive username, and choose a secure password. +4. Assign the **marketing_dashboards_role** that you previously created to this new user. +5. Click **Create user**. + +:::{image} ../../../images/kibana-tutorial-secure-access-example-1-user.png +:alt: Create user UI +:class: screenshot +::: + + +### Verify [_verify] + +Verify that the user and role are working correctly. + +1. Logout of {{kib}} if you are already logged in. +2. In the login screen, enter the username and password for the account you created. + + You’re taken into the `Marketing` space, and the main navigation shows only the **Dashboard** application. + + :::{image} ../../../images/kibana-tutorial-secure-access-example-1-test.png + :alt: Verifying access to dashboards + :class: screenshot + ::: + + + +## What’s next? [_whats_next_2] + +This guide is an introduction to {{kib}}'s security features. Check out these additional resources to learn more about authenticating and authorizing your users. + +* View the [authentication guide](user-authentication.md) to learn more about single-sign on and other login features. +* View the [authorization guide](defining-roles.md) to learn more about authorizing access to {{kib}}'s features. + +Still have questions? Ask on our [Kibana discuss forum](https://discuss.elastic.co/c/kibana) and a fellow community member or Elastic engineer will help out. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md b/deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md new file mode 100644 index 000000000..78da3d93a --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md @@ -0,0 +1,66 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/realm-chains.html +--- + +# Realm chains [realm-chains] + +[Realms](authentication-realms.md) live within a *realm chain*. It is essentially a prioritized list of configured realms (typically of various types). Realms are consulted in ascending order (that is to say, the realm with the lowest `order` value is consulted first). You must make sure each configured realm has a distinct `order` setting. In the event that two or more realms have the same `order`, the node will fail to start. + +During the authentication process, {{stack}} {security-features} consult and try to authenticate the request one realm at a time. Once one of the realms successfully authenticates the request, the authentication is considered to be successful. The authenticated user is associated with the request, which then proceeds to the authorization phase. If a realm cannot authenticate the request, the next realm in the chain is consulted. If all realms in the chain cannot authenticate the request, the authentication is considered to be unsuccessful and an authentication error is returned (as HTTP status code `401`). + +::::{note} +Some systems (e.g. Active Directory) have a temporary lock-out period after several successive failed login attempts. If the same username exists in multiple realms, unintentional account lockouts are possible. For more information, see [Users are frequently locked out of Active Directory](../../../troubleshoot/elasticsearch/security/trouble-shoot-active-directory.md). +:::: + + +The default realm chain contains the `file` and `native` realms. To explicitly configure a realm chain, you specify the chain in the `elasticsearch.yml` file. If your realm chain does not contain `file` or `native` realm or does not disable them explicitly, `file` and `native` realms will be added automatically to the beginning of the realm chain in that order. To opt-out from the automatic behaviour, you can explicitly configure the `file` and `native` realms with the `order` and `enabled` settings. + +The following snippet configures a realm chain that enables the `file` realm as well as two LDAP realms and an Active Directory realm, but disables the `native` realm. + +```yaml +xpack.security.authc.realms: + file.file1: + order: 0 + + ldap.ldap1: + order: 1 + enabled: false + url: 'url_to_ldap1' + ... + + ldap.ldap2: + order: 2 + url: 'url_to_ldap2' + ... + + active_directory.ad1: + order: 3 + url: 'url_to_ad' + + native.native1: + enabled: false +``` + +As can be seen above, each realm has a unique name that identifies it. Each type of realm dictates its own set of required and optional settings. That said, there are [settings that are common to all realms](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-realm-settings). + +## Delegating authorization to another realm [authorization_realms] + +Some realms have the ability to perform *authentication* internally, but delegate the lookup and assignment of roles (that is, *authorization*) to another realm. + +For example, you may wish to use a PKI realm to authenticate your users with TLS client certificates, then lookup that user in an LDAP realm and use their LDAP group assignments to determine their roles in Elasticsearch. + +Any realm that supports retrieving users (without needing their credentials) can be used as an *authorization realm* (that is, its name may appear as one of the values in the list of `authorization_realms`). See [Looking up users without authentication](looking-up-users-without-authentication.md) for further explanation on which realms support this. + +For realms that support this feature, it can be enabled by configuring the `authorization_realms` setting on the authenticating realm. Check the list of [supported settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#realm-settings) for each realm to see if they support the `authorization_realms` setting. + +If delegated authorization is enabled for a realm, it authenticates the user in its standard manner (including relevant caching) then looks for that user in the configured list of authorization realms. It tries each realm in the order they are specified in the `authorization_realms` setting. The user is retrieved by principal - the user must have identical usernames in the *authentication* and *authorization realms*. If the user cannot be found in any of the authorization realms, authentication fails. + +See [Configuring authorization delegation](authorization-delegation.md) for more details. + +::::{note} +Delegated authorization requires that you have a [subscription](https://www.elastic.co/subscriptions) that includes custom authentication and authorization realms. +:::: + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md b/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md new file mode 100644 index 000000000..a4a1b7abf --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md @@ -0,0 +1,52 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/role-restriction.html +--- + +# Role restriction [role-restriction] + +Role restriction can be used to specify conditions under which a role should be effective. When conditions are not met, the role will be disabled, which will result in access being denied. Not specifying restriction means the role is not restricted and thus always effective. This is the default behaviour. + +::::{note} +Currently, the role restriction is only supported for [API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), with limitation that the API key can only have a single role descriptor. +:::: + + +## Workflows [workflows-restriction] + +Workflows allow to restrict the role to be effective exclusively when calling certain REST APIs. Calling a REST API that is not allowed by a workflow, will result in the role being disabled. The below section lists workflows that you can restrict the role to: + +`search_application_query` +: This workflow restricts the role to the [Search Application Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-application-search.html) only. + +::::{note} +Workflow names are case-sensitive. +:::: + + + +### Examples [_examples_5] + +The following example creates an API key with a [restriction]() to the `search_application_query` workflow, which allows to call only [Search Application Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-application-search.html): + +```console +POST /_security/api_key +{ + "name": "my-restricted-api-key", + "role_descriptors": { + "my-restricted-role-descriptor": { + "indices": [ + { + "names": ["my-search-app"], + "privileges": ["read"] + } + ], + "restriction": { + "workflows": ["search_application_query"] + } + } + } +} +``` + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md b/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md new file mode 100644 index 000000000..5673ccee8 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md @@ -0,0 +1,69 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-realm.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece_sign_outgoing_saml_message.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece_optional_settings.html + - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-securing-clusters-SAML.html + - https://www.elastic.co/guide/en/cloud/current/ec-securing-clusters-SAML.html + - https://www.elastic.co/guide/en/cloud/current/ec-sign-outgoing-saml-message.html + - https://www.elastic.co/guide/en/cloud/current/ec-securing-clusters-saml-azure.html + - https://www.elastic.co/guide/en/cloud-heroku/current/ech-securing-clusters-SAML.html + - https://www.elastic.co/guide/en/cloud-heroku/current/echsign-outgoing-saml-message.html + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-saml-authentication.html + - https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-stack.html +--- + +# SAML + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/saml-realm.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece_sign_outgoing_saml_message.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece_optional_settings.md +% - [ ] ./raw-migrated-files/cloud/cloud-enterprise/ece-securing-clusters-SAML.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-securing-clusters-SAML.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-sign-outgoing-saml-message.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-securing-clusters-saml-azure.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/ech-securing-clusters-SAML.md +% - [ ] ./raw-migrated-files/cloud/cloud-heroku/echsign-outgoing-saml-message.md +% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-saml-authentication.md +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/saml-guide-stack.md +% Notes: some steps not needed for cloud / don't work needs clarification that there is an orch level + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$saml-create-realm$$$ + +$$$saml-attributes-mapping$$$ + +$$$saml-attribute-mapping-nameid$$$ + +$$$saml-kibana-basic$$$ + +$$$ec-securing-clusters-saml-azure-kibana$$$ + +$$$ec-securing-clusters-saml-azure-enterprise-search$$$ + +$$$saml-role-mapping$$$ + +$$$saml-configure-kibana$$$ + +$$$saml-logout$$$ + +$$$saml-enable-http$$$ + +$$$saml-enable-token$$$ + +$$$saml-es-user-properties$$$ + +$$$saml-enc-sign$$$ + +$$$saml-user-metadata$$$ + +$$$saml-elasticsearch-authentication$$$ + +$$$saml-no-kibana-sp-init-sso$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/security-domains.md b/deploy-manage/users-roles/cluster-or-deployment-auth/security-domains.md new file mode 100644 index 000000000..6def0f65b --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/security-domains.md @@ -0,0 +1,91 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-domain.html +--- + +# Security domains [security-domain] + +Security domains are a method of grouping multiple [realms](authentication-realms.md) under the same domain so that the {{stack}} can recognize when a single user authenticates with these realms. Users can authenticate with any of the realms in the domain group, and have access to the same set of resources regardless of which realm they authenticated with. + +For example, a single [user profile](user-profiles.md) is associated with a user, enabling preferences, notifications, and other user data to be shared across realms. The user can view results from an asynchronous search request or a scrolling search across realms. If the user has the necessary privileges, they can also view and manage API keys across realms. + +## Resource sharing across domains [security-domain-resource-sharing] + +Some types of resources in {{es}} are owned by a single user, such as [async search contexts](https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html), [API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), and [user profiles](user-profiles.md). When a user creates a resource, {{es}} captures the user’s username and realm information as part of the resource’s metadata. Likewise, if a user updates a resource, such as an API key, {{es}} automatically re-captures the user’s current realm information. + +When a user later attempts to access the resource, {{es}} compares the captured username and realm information against those from the accessing user. {{es}} will deny access unless both the realm and username match. If {{es}} detects that a username from two different realms is attempting to access a resource, {{es}} assumes that these users are distinct and doesn’t allow resources to be shared between those users. + +However, there are cases where the same user can authenticate with multiple realms and needs to share the same set of resources across realms. For example, an [LDAP realm](ldap.md) and a [SAML realm](saml.md) can be backed by the same directory service. Additionally, [authorization delegation](authorization-delegation.md) allows one realm to delegate authorization to another realm. If both realms authenticate users with the same username, it’s reasonable to treat these users as the same user from a resource ownership perspective. + +Security domains make resource sharing across realms possible by grouping those realms under the same domain. {{es}} always enforces the privileges that are associated with the currently authenticated user, which remains true with security domains. Security domains don’t bypass [user authorization](user-roles.md) when resource sharing requires them. For example, a user requires the `manage_own_api_key` privilege to manage their own API keys. If that user doesn’t have this privilege when authenticating with one realm, they won’t be able to manage API keys while authenticating with another realm. + +### Managing roles across realms [security-domain-realm-roles] + +{{es}} provides multiple ways to consistently apply roles across realms. For example, you can use [authorization delegation](authorization-delegation.md) to ensure that a user is assigned the same roles from multiple realms. You can also manually configure multiple realms that are backed by the same directory service. Though it’s possible to configure different [roles](user-roles.md#roles) for the same user when authenticating with different realms, it is *not* recommended. + + + +## Configure a security domain [security-domain-configure] + +::::{important} +:name: security-domain-warning + +Security domains are an advanced feature that requires careful configuration. Misconfiguration or misuse can lead to unexpected behaviors. + +:::: + + +Security domains must be configured consistently across all nodes in cluster. Inconsistent configuration can lead to issues such as: + +* Duplicated user profiles +* Different ownership of resources depending on the authenticating node’s configuration + +To configure a security domain: + +1. Add a security domain configuration to `elasticsearch.yml` in the `xpack.security.authc.domains` namespace: + + ```yaml + xpack: + security: + authc: + domains: + my_domain: + realms: [ 'default_native', 'saml1' ] <1> + ``` + + 1. This configuration defines a security domain called `my_domain`, which contains two realms named `default_native` and `saml1`. + + + The specified realms must be defined in `elasticsearch.yml`, but do not need to be enabled. + + ::::{note} + The [file realm](file-based.md) and [native realm](native.md) are automatically enabled as `default_file` and `default_native`, respectively, without any explicit configuration. You can list these realms under domains even when they are not explicitly defined in `elasticsearch.yml`. + :::: + +2. Restart {{es}}. + + ::::{important} + {{es}} can fail to start if the domain configuration is invalid, such as: + + * The same realm is configured under multiple domains. + * Any undefined realm, synthetic realm, or the reserved realm is configured to be under a domain. + + :::: + +3. Apply the same configuration across all nodes in the cluster before performing operations related to security domains, including creating and managing resources such as [user profiles](user-profiles.md), [API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html), and [async search](https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html). + + When adding realms to a security domain, avoid authenticating with a newly-added realm until changes are fully applied to all nodes. + + + +## Removing realms from a security domain [security-domain-remove-realm] + +Removing realms from a security domain can lead to unexpected behaviors and is not recommended. Resources created or updated before the removal can be owned by different users depending on the resource type: + +* [User profiles](user-profiles.md) are owned by the user for whom the profile was last [activated](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-activate-user-profile.html). For users whose realms are no longer in the same domain as the owner user, a new user profile will be created for them next time the activate user profile API is called. +* An API key is owned by the user who originally [created](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) or last [updated](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-api-key.html) it. Users, including the original creator of the API key, will lose ownership if their realms are no longer in the same domain as those of the current API key owner. +* Resources such as async search contexts are owned by the user who originally created them. + +Instead of removing realms, consider disabling them and keeping them as part of the security domain. Under all circumstances, resource sharing across realms is only possible between users with the same username. + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/service-accounts.md b/deploy-manage/users-roles/cluster-or-deployment-auth/service-accounts.md new file mode 100644 index 000000000..10e60da14 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/service-accounts.md @@ -0,0 +1,106 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html +--- + +# Service accounts [service-accounts] + +The {{stack-security-features}} provide *service accounts* specifically for integration with external services that connect to {{es}}, such as {{fleet}} server. Service accounts have a fixed set of privileges and cannot authenticate until you create a service account token for them. Additionally, service accounts are predefined in code, and are always enabled. + +A service account corresponds to a specific external service. You create service account tokens for a service account. The service can then authenticate with the token and perform relevant actions. For example, {{fleet}} server can use its service token to authenticate with {{es}} and then manage its own API keys. + +You can create multiple service tokens for the same service account, which prevents credential sharing between multiple instances of the same external service. Each instance can assume the same identity while using their own distinct service token for authentication. + +Service accounts provide flexibility over [built-in users](built-in-users.md) because they: + +* Do not rely on the [internal `native` realm](native.md), and aren’t always required to rely on the `.security` index +* Use a [role descriptor](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html#security-api-create-api-key-request-body) named after the service account principal instead of traditional roles +* Support multiple credentials through service account tokens + +Service accounts are not included in the response of the [get users API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-user.html). To retrieve a service account, use the [get service accounts API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-service-accounts.html). Use the [get service account credentials API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-service-credentials.html) to retrieve all service credentials for a service account. + + +## Service accounts usage [service-accounts-explanation] + +Service accounts have a [unique principal](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-service-accounts.html#security-api-get-service-accounts-path-params) that takes the format of `/`, where the `namespace` is a top-level grouping of service accounts, and `service` is the name of the service and must be unique within its namespace. + +Service accounts are predefined in code. The following service accounts are available: + +`elastic/fleet-server` +: The service account used by the {{fleet}} server to communicate with {{es}}. + +`elastic/kibana` +: The service account used by {{kib}} to communicate with {{es}}. + +`elastic/enterprise-search-server` +: The service account used by Enterprise Search to communicate with {{es}}. + +::::{important} +Do not attempt to use service accounts for authenticating individual users. Service accounts can only be authenticated with service tokens, which are not applicable to regular users. +:::: + + + +## Service account tokens [service-accounts-tokens] + +A service account token, or service token, is a unique string that a service uses to authenticate with {{es}}. For a given service account, each token must have a unique name. Because tokens include access credentials, they should always be kept secret by whichever client is using them. + +Service tokens can be backed by either the `.security` index (recommended) or the `service_tokens` file. You can create multiple service tokens for a single service account, which enables multiple instances of the same service to run with different credentials. + +You must create a service token to use a service account. You can create a service token using either: + +* The [create service account token API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html), which saves the new service token in the `.security` index and returns the bearer token in the HTTP response. +* The [elasticsearch-service-tokens](https://www.elastic.co/guide/en/elasticsearch/reference/current/service-tokens-command.html) CLI tool, which saves the new service token in the `$ES_HOME/config/service_tokens` file and outputs the bearer token to your terminal + +We recommend that you create service tokens via the REST API rather than the CLI. The API stores service tokens within the `.security` index which means that the tokens are available for authentication on all nodes, and will be backed up within cluster snapshots. The use of the CLI is intended for cases where there is an external orchestration process (such as [{{ece}}](https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}) or [{{eck}}](https://www.elastic.co/guide/en/cloud-on-k8s/current)) that will manage the creation and distribution of the `service_tokens` file. + +Both of these methods (API and CLI) create a service token with a guaranteed secret string length of `22`. The minimal, acceptable length of a secret string for a service token is `10`. If the secret string doesn’t meet this minimal length, authentication with {{es}} will fail without even checking the value of the service token. + +Service tokens never expire. You must actively [delete](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-service-token.html) them if they are no longer needed. + + +## Authenticate with service tokens [authenticate-with-service-account-token] + +::::{note} +Service accounts currently do not support basic authentication. +:::: + + +To use a service account token, include the generated token value in a request with an `Authorization: Bearer` header: + +```shell +curl -H "Authorization: Bearer AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" http://localhost:9200/_security/_authenticate +``` + +A successful authentication response includes a `token` field, which contains a `name` field for the name of the service token and a `type` field for the type of the service token: + +```js +{ + "username": "elastic/fleet-server", + "roles": [], + "full_name": "Service account - elastic/fleet-server", + "email": null, + "token": { + "name": "token1", <1> + "type": "_service_account_index" <2> + }, + "metadata": { + "_elastic_service_account": true + }, + "enabled": true, + "authentication_realm": { + "name": "_service_account", + "type": "_service_account" + }, + "lookup_realm": { + "name": "_service_account", + "type": "_service_account" + }, + "authentication_type": "token" +} +``` + +1. Name of the service account token. +2. Type of service account token. The value always begins with `_service_account_` and is followed by a string that indicates the service token backend in use (can be either `file` or `index`). + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md new file mode 100644 index 000000000..c1807f413 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md @@ -0,0 +1,158 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html +--- + +# Submitting requests on behalf of other users [run-as-privilege] + +{{es}} roles support a `run_as` privilege that enables an authenticated user to submit requests on behalf of other users. For example, if your external application is trusted to authenticate users, {{es}} can authenticate the external application and use the *run as* mechanism to issue authorized requests as other users without having to re-authenticate each user. + +To "run as" (impersonate) another user, the first user (the authenticating user) must be authenticated by a mechanism that supports run-as delegation. The second user (the `run_as` user) must be authorized by a mechanism that supports delegated run-as lookups by username. + +The `run_as` privilege essentially operates like a secondary form of [delegated authorization](realm-chains.md#authorization_realms). Delegated authorization applies to the authenticating user, and the `run_as` privilege applies to the user who is being impersonated. + +true +For the authenticating user, the following realms (plus API keys) all support `run_as` delegation: `native`, `file`, Active Directory, JWT, Kerberos, LDAP and PKI. + +Service tokens, the {{es}} Token Service, SAML 2.0, and OIDC 1.0 do not support `run_as` delegation. + +true +{{es}} supports `run_as` for any realm that supports user lookup. Not all realms support user lookup. Refer to the list of [supported realms](looking-up-users-without-authentication.md) and ensure that the realm you wish to use is configured in a manner that supports user lookup. + +The `run_as` user must be retrieved from a [realm](authentication-realms.md) - it is not possible to run as a [service account](service-accounts.md), [API key](token-based-authentication-services.md#token-authentication-api-key) or [access token](token-based-authentication-services.md#token-authentication-access-token). + +To submit requests on behalf of other users, you need to have the `run_as` privilege in your [roles](defining-roles.md). For example, the following request creates a `my_director` role that grants permission to submit request on behalf of `jacknich` or `redeniro`: + +```console +POST /_security/role/my_director?refresh=true +{ + "cluster": ["manage"], + "indices": [ + { + "names": [ "index1", "index2" ], + "privileges": [ "manage" ] + } + ], + "run_as": [ "jacknich", "rdeniro" ], + "metadata" : { + "version" : 1 + } +} +``` + +To submit a request as another user, you specify the user in the `es-security-runas-user` request header. For example: + +```sh +curl -H "es-security-runas-user: jacknich" -u es-admin -X GET http://localhost:9200/ +``` + +The `run_as` user passed in through the `es-security-runas-user` header must be available from a realm that supports delegated authorization lookup by username. Realms that don’t support user lookup can’t be used by `run_as` delegation from other realms. + +For example, JWT realms can authenticate external users specified in JWTs, and execute requests as a `run_as` user in the `native` realm. {{es}} will retrieve the indicated `runas` user and execute the request as that user using their roles. + +## Apply the `run_as` privilege to roles [run-as-privilege-apply] + +You can apply the `run_as` privilege when creating roles with the [create or update roles API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html). Users who are assigned a role that contains the `run_as` privilege inherit all privileges from their role, and can also submit requests on behalf of the indicated users. + +::::{note} +Roles for the authenticated user and the `run_as` user are not merged. If a user authenticates without specifying the `run_as` parameter, only the authenticated user’s roles are used. If a user authenticates and their roles include the `run_as` parameter, only the `run_as` user’s roles are used. +:::: + + +After a user successfully authenticates to {{es}}, an authorization process determines whether the user behind an incoming request is allowed to run that request. If the authenticated user has the `run_as` privilege in their list of permissions and specifies the run-as header, {{es}} *discards* the authenticated user and associated roles. It then looks in each of the configured realms in the realm chain until it finds the username that’s associated with the `run_as` user, and uses those roles to execute any requests. + +Consider an admin role and an analyst role. The admin role has higher privileges, but might also want to submit requests as another user to test and verify their permissions. + +First, we’ll create an admin role named `my_admin_role`. This role has `manage` [privileges](elasticsearch-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. + +```console +POST /_security/role/my_admin_role?refresh=true +{ + "cluster": ["manage"], + "indices": [ + { + "names": [ "index1", "index2" ], + "privileges": [ "manage" ] + } + ], + "applications": [ + { + "application": "myapp", + "privileges": [ "admin", "read" ], + "resources": [ "*" ] + } + ], + "run_as": [ "analyst_user" ], + "metadata" : { + "version" : 1 + } +} +``` + +Next, we’ll create an analyst role named `my_analyst_role`, which has more restricted `monitor` cluster privileges and `manage` privileges on a subset of indices. + +```console +POST /_security/role/my_analyst_role?refresh=true +{ + "cluster": [ "monitor"], + "indices": [ + { + "names": [ "index1", "index2" ], + "privileges": ["manage"] + } + ], + "applications": [ + { + "application": "myapp", + "privileges": [ "read" ], + "resources": [ "*" ] + } + ], + "metadata" : { + "version" : 1 + } +} +``` + +We’ll create an administrator user and assign them the role named `my_admin_role`, which allows this user to submit requests as the `analyst_user`. + +```console +POST /_security/user/admin_user?refresh=true +{ + "password": "l0ng-r4nd0m-p@ssw0rd", + "roles": [ "my_admin_role" ], + "full_name": "Eirian Zola", + "metadata": { "intelligence" : 7} +} +``` + +We can also create an analyst user and assign them the role named `my_analyst_role`. + +```console +POST /_security/user/analyst_user?refresh=true +{ + "password": "l0nger-r4nd0mer-p@ssw0rd", + "roles": [ "my_analyst_role" ], + "full_name": "Monday Jaffe", + "metadata": { "innovation" : 8} +} +``` + +You can then authenticate to {{es}} as the `admin_user` or `analyst_user`. However, the `admin_user` could optionally submit requests on behalf of the `analyst_user`. The following request authenticates to {{es}} with a `Basic` authorization token and submits the request as the `analyst_user`: + +```sh +curl -s -X GET -H "Authorization: Basic YWRtaW5fdXNlcjpsMG5nLXI0bmQwbS1wQHNzdzByZA==" -H "es-security-runas-user: analyst_user" https://localhost:9200/_security/_authenticate +``` + +The response indicates that the `analyst_user` submitted this request, using the `my_analyst_role` that’s assigned to that user. When the `admin_user` submitted the request, {{es}} authenticated that user, discarded their roles, and then used the roles of the `run_as` user. + +```sh +{"username":"analyst_user","roles":["my_analyst_role"],"full_name":"Monday Jaffe","email":null, +"metadata":{"innovation":8},"enabled":true,"authentication_realm":{"name":"native", +"type":"native"},"lookup_realm":{"name":"native","type":"native"},"authentication_type":"realm"} +% +``` + +The `authentication_realm` and `lookup_realm` in the response both specify the `native` realm because both the `admin_user` and `analyst_user` are from that realm. If the two users are in different realms, the values for `authentication_realm` and `lookup_realm` are different (such as `pki` and `native`). + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services.md b/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services.md new file mode 100644 index 000000000..6ea700d1f --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services.md @@ -0,0 +1,53 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/token-authentication-services.html +--- + +# Token-based authentication services [token-authentication-services] + +The {{stack-security-features}} authenticate users by using realms and one or more token-based authentication services. The token-based authentication services are used for authenticating and managing tokens. You can attach these tokens to requests that are sent to {{es}} and use them as credentials. When {{es}} receives a request that must be authenticated, it consults the token-based authentication services first, and then the realm chain. + +The {{security-features}} provide the following built-in token-based authentication services, which are listed in the order they are consulted: + +*service-accounts* +: The [service accounts](service-accounts.md) use either the [create service account token API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html) or the [elasticsearch-service-tokens](https://www.elastic.co/guide/en/elasticsearch/reference/current/service-tokens-command.html) CLI tool to generate service account tokens. + +To use a service account token, include the generated token value in a request with an `Authorization: Bearer` header: + +```shell +curl -H "Authorization: Bearer AAEAAWVsYXN0aWMvZ...mXQtc2VydmMTpyNXdkYmRib1FTZTl2R09Ld2FKR0F3" http://localhost:9200/_cluster/health +``` + +::::{important} +Do not attempt to use service accounts for authenticating individual users. Service accounts can only be authenticated with service tokens, which are not applicable to regular users. +:::: + + + +$$$token-authentication-access-token$$$ + +*token-service* +: The token service uses the [get token API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-token.html) to generate access tokens and refresh tokens based on the OAuth2 specification. The access token is a short-lived token. By default, it expires after 20 minutes but it can be configured to last a maximum of 1 hour. It can be refreshed by using a refresh token, which has a lifetime of 24 hours. The access token is a bearer token. You can use it by sending a request with an `Authorization` header with a value that has the prefix "Bearer " followed by the value of the access token. For example: + + ```shell + curl -H "Authorization: Bearer dGhpcyBpcyBub3Qx5...F0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health + ``` + + +$$$token-authentication-api-key$$$ + +*api-key-service* +: The API key service uses the [create API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) to generate API keys. By default, the API keys do not expire. When you make a request to create API keys, you can specify an expiration and permissions for the API key. The permissions are limited by the authenticated user’s permissions. You can use the API key by sending a request with an `Authorization` header with a value that has the prefix "ApiKey " followed by the credentials. The credentials are the base64 encoding of the API key ID and the API key joined by a colon. For example: + + ```shell + curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrU...W0tZTVhT3g6dWkybHAyYXhUTm1zeWFrd0dk5udw==" http://localhost:9200/_cluster/health + ``` + + +Depending on your use case, you may want to decide on the lifetime of the tokens generated by these services. You can then use this information to decide which service to use to generate and manage the tokens. Non-expiring API keys may seem like the easy option but you must consider the security implications that come with non-expiring keys. Both the *token-service* and *api-key-service* permit you to invalidate the tokens. See [invalidate token API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-token.html) and [invalidate API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html). + +::::{important} +Authentication support for JWT bearer tokens was introduced in {{es}} 8.2 through the [JWT authentication](jwt.md), which cannot be enabled through token-authentication services. Realms offer flexible order and configurations of zero, one, or multiple JWT realms. +:::: + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md new file mode 100644 index 000000000..36dd2e304 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md @@ -0,0 +1,41 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html + - https://www.elastic.co/guide/en/kibana/current/kibana-authentication.html +--- + +# User authentication + +% What needs to be done: Refine + +% GitHub issue: https://github.com/elastic/docs-projects/issues/347 + +% Scope notes: reference ECE SSO, cloud SSO + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/setting-up-authentication.md +% - [ ] ./raw-migrated-files/kibana/kibana/kibana-authentication.md +% Notes: this is a good overview + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$pki-authentication$$$ + +$$$anonymous-authentication$$$ + +$$$basic-authentication$$$ + +$$$embedded-content-authentication$$$ + +$$$http-authentication$$$ + +$$$kerberos$$$ + +$$$multiple-authentication-providers$$$ + +$$$oidc$$$ + +$$$saml$$$ + +$$$token-authentication$$$ \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-profiles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-profiles.md new file mode 100644 index 000000000..66f837d98 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-profiles.md @@ -0,0 +1,61 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/user-profile.html +--- + +# User profiles [user-profile] + +::::{note} +The user profile feature is designed only for use by {{kib}} and Elastic’s {{observability}}, {{ents}}, and {{elastic-sec}} solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. +:::: + + +Because the {{stack}} supports externally-managed users (such as users who authenticate via SAML, or users stored in an LDAP directory), there’s a distinction between *users* and their *profile*. + +*Users* refer to the entities that authenticate requests to the {{stack}}. Each user has a username and a set of privileges (represented by [roles](user-roles.md#roles)) that determine which types of requests they can issue. Users can be ephemeral; they might exist only for the duration of a request to an {{es}} API or for the lifetime of a session in {{kib}}. These users cannot be retrieved after the session ends, and can’t store preferences across sessions. + +*User profiles* provide persistent and stable representations of users. A user profile exists even if the user is offline, so their profile persists across sessions. The unique identifier assigned to each profile doesn’t change throughout the lifetime of a deployment, providing a stable way of referring to the associated user. Each profile has a unique identifier, is searchable, and can store user data such as format and notification preferences. + +The capability of uniquely referring to users regardless of whether they’re actively online is a critical function that underpins important features like personalization and collaboration in {{kib}}. + +## User profiles in {{kib}} [_user_profiles_in_kib] + +A user profile is the persistent record that the {{stack}} stores for each interactive user that authenticates to {{kib}}. + +When a user logs in to {{kib}}, a profile is automatically created for the user, or an existing profile is updated to reflect the user’s active session. By using the unique ID of the user profile, {{kib}} can store user-level data such as preferences separately for each user, which is key to fine-grained levels of customization. {{kib}} uses this unique ID to route messages and notifications to a distinct user, regardless of whether they’re logged in. + +### Usernames and user profiles [_usernames_and_user_profiles] + +You can use the same username across multiple realms for a single user. In {{es}}, it’s possible for two different realms to authenticate users with the same username and different roles. {{es}} doesn’t assume that these users are the same person, and treats them as separate individuals with distinct user profiles by default. + +::::{note} +For use cases where one individual can authenticate against multiple realms, you can use the [security domain](security-domains.md) feature so that these distinct users are considered to be the same identity and share a single user profile. +:::: + + + + +## Create and manage user profiles [_create_and_manage_user_profiles] + +To create a new user profile or update an existing one, use the [activate user profile API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-activate-user-profile.html). When you submit a request, {{es}} attempts to locate an existing profile document for the specified user. If one doesn’t exist, {{es}} creates a new profile document. + +In either case, the profile document captures the user’s `full_name`, `email`, `roles`, and `realms`, and also includes the profile unique ID and timestamp of the operation. You can retrieve a user profile with the [get user profile API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-user-profile.html) by including the profile’s unique ID (`uid`). + +In addition to the user’s basic information, you can add data to a profile document with the [update user profile API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-update-user-profile-data.html). For example, you can add user-specific preferences as part of the profile data. + +Use the [suggest user profile API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-suggest-user-profile.html) to retrieve profiles that match given criteria. This API is designed to support user-suggestions, in collaboration with features such as those found in {{kib}}. However, the suggest user profile API is not intended to provide a general-purpose search API. + +Lastly, you can use the [has privileges API for user profiles](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges-user-profile.html) to check the privileges of multiple users by specifying their profiles' unique IDs. This can be used in conjunction with the suggest user profile API in order to restrict the suggestions only to users that have the necessary permissions to actually perform the action in the context. + + +## Limitations [_limitations_10] + +* Creating a new user profile requires a user’s authentication details (`username` and `password` or its [OAuth2 access token](token-based-authentication-services.md)). This means that a user must authenticate at least one time to create a user profile. Users who have never authenticated to {{kib}} (or another profile-aware application) won’t have a user profile, and the [suggest user profile API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-suggest-user-profile.html) won’t return any results for those users. +* User profiles are meant for interactive users, such as a human user who interacts with {{kib}}. Therefore, user profiles don’t support API keys or [service accounts](service-accounts.md). + + ::::{note} + [OAuth2 tokens](token-based-authentication-services.md) that represent an interactive end-user are supported. + :::: + + + diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md new file mode 100644 index 000000000..76640be8c --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md @@ -0,0 +1,70 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/authorization.html +--- + +# User roles [authorization] + +The {{stack-security-features}} add *authorization*, which is the process of determining whether the user behind an incoming request is allowed to execute the request. + +This process takes place after the user is successfully identified and [authenticated](user-authentication.md). + + +## Role-based access control [roles] + +The {{security-features}} provide a role-based access control (RBAC) mechanism, which enables you to authorize users by assigning privileges to roles and assigning roles to users or groups. + +:::{image} ../../../images/elasticsearch-reference-authorization.png +:alt: This image illustrates role-based access control +::: + +The authorization process revolves around the following constructs: + +*Secured Resource* +: A resource to which access is restricted. Indices, aliases, documents, fields, users, and the {{es}} cluster itself are all examples of secured objects. + +*Privilege* +: A named group of one or more actions that a user may execute against a secured resource. Each secured resource has its own sets of available privileges. For example, `read` is an index privilege that represents all actions that enable reading the indexed/stored data. For a complete list of available privileges see [Security privileges](elasticsearch-privileges.md). + +*Permissions* +: A set of one or more privileges against a secured resource. Permissions can easily be described in words, here are few examples: + + * `read` privilege on the `products` data stream or index + * `manage` privilege on the cluster + * `run_as` privilege on `john` user + * `read` privilege on documents that match query X + * `read` privilege on `credit_card` field + + +*Role* +: A named set of permissions + +*User* +: The authenticated user. + +*Group* +: One or more groups to which a user belongs. Groups are not supported in some realms, such as native, file, or PKI realms. + +A role has a unique name and identifies a set of permissions that translate to privileges on resources. You can associate a user or group with an arbitrary number of roles. When you map roles to groups, the roles of a user in that group are the combination of the roles assigned to that group and the roles assigned to that user. Likewise, the total set of permissions that a user has is defined by the union of the permissions in all its roles. + +The method for assigning roles to users varies depending on which realms you use to authenticate users. For more information, see [Mapping users and groups to roles](mapping-users-groups-to-roles.md). + + +## Attribute-based access control [attributes] + +The {{security-features}} also provide an attribute-based access control (ABAC) mechanism, which enables you to use attributes to restrict access to documents in search queries and aggregations. For example, you can assign attributes to users and documents, then implement an access policy in a role definition. Users with that role can read a specific document only if they have all the required attributes. + +For more information, see [Document-level attribute-based access control with X-Pack 6.1](https://www.elastic.co/blog/attribute-based-access-control-with-xpack). + + + + + + + + + + + + + diff --git a/docset.yml b/docset.yml index 33d87116e..838501ee0 100644 --- a/docset.yml +++ b/docset.yml @@ -1,15 +1,495 @@ -project: "docs-content" +project: 'Elastic documentation' exclude: - - '_*.md' - 'README.md' toc: - file: index.md - - toc: elastic-basics + - toc: get-started - toc: solutions - toc: manage-data - toc: explore-analyze - toc: deploy-manage + - toc: cloud-account - toc: troubleshoot - - toc: extend - - toc: whats-new - - toc: reference \ No newline at end of file + - toc: raw-migrated-files + +subs: + ref: "https://www.elastic.co/guide/en/elasticsearch/reference/current" + ref-bare: "https://www.elastic.co/guide/en/elasticsearch/reference" + ref-8x: "https://www.elastic.co/guide/en/elasticsearch/reference/8.1" + ref-80: "https://www.elastic.co/guide/en/elasticsearch/reference/8.0" + ref-7x: "https://www.elastic.co/guide/en/elasticsearch/reference/7.17" + ref-70: "https://www.elastic.co/guide/en/elasticsearch/reference/7.0" + ref-60: "https://www.elastic.co/guide/en/elasticsearch/reference/6.0" + ref-64: "https://www.elastic.co/guide/en/elasticsearch/reference/6.4" + xpack-ref: "https://www.elastic.co/guide/en/x-pack/6.2" + logstash-ref: "https://www.elastic.co/guide/en/logstash/current" + kibana-ref: "https://www.elastic.co/guide/en/kibana/current" + kibana-ref-all: "https://www.elastic.co/guide/en/kibana" + beats-ref-root: "https://www.elastic.co/guide/en/beats" + beats-ref: "https://www.elastic.co/guide/en/beats/libbeat/current" + beats-ref-60: "https://www.elastic.co/guide/en/beats/libbeat/6.0" + beats-ref-63: "https://www.elastic.co/guide/en/beats/libbeat/6.3" + beats-devguide: "https://www.elastic.co/guide/en/beats/devguide/current" + auditbeat-ref: "https://www.elastic.co/guide/en/beats/auditbeat/current" + packetbeat-ref: "https://www.elastic.co/guide/en/beats/packetbeat/current" + metricbeat-ref: "https://www.elastic.co/guide/en/beats/metricbeat/current" + filebeat-ref: "https://www.elastic.co/guide/en/beats/filebeat/current" + functionbeat-ref: "https://www.elastic.co/guide/en/beats/functionbeat/current" + winlogbeat-ref: "https://www.elastic.co/guide/en/beats/winlogbeat/current" + heartbeat-ref: "https://www.elastic.co/guide/en/beats/heartbeat/current" + journalbeat-ref: "https://www.elastic.co/guide/en/beats/journalbeat/current" + ingest-guide: "https://www.elastic.co/guide/en/ingest/current" + fleet-guide: "https://www.elastic.co/guide/en/fleet/current" + apm-guide-ref: "https://www.elastic.co/guide/en/apm/guide/current" + apm-guide-7x: "https://www.elastic.co/guide/en/apm/guide/7.17" + apm-app-ref: "https://www.elastic.co/guide/en/kibana/current" + apm-agents-ref: "https://www.elastic.co/guide/en/apm/agent" + apm-android-ref: "https://www.elastic.co/guide/en/apm/agent/android/current" + apm-py-ref: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-py-ref-3x: "https://www.elastic.co/guide/en/apm/agent/python/3.x" + apm-node-ref-index: "https://www.elastic.co/guide/en/apm/agent/nodejs" + apm-node-ref: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-node-ref-1x: "https://www.elastic.co/guide/en/apm/agent/nodejs/1.x" + apm-rum-ref: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-dotnet-ref: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref: "https://www.elastic.co/guide/en/apm/agent/php/current" + apm-ios-ref: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-lambda-ref: "https://www.elastic.co/guide/en/apm/lambda/current" + apm-attacher-ref: "https://www.elastic.co/guide/en/apm/attacher/current" + docker-logging-ref: "https://www.elastic.co/guide/en/beats/loggingplugin/current" + esf-ref: "https://www.elastic.co/guide/en/esf/{{esf_version}}" + kinesis-firehose-ref: "https://www.elastic.co/guide/en/kinesis/{{kinesis_version}}" + estc-welcome-current: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome-all: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions" + hadoop-ref: "https://www.elastic.co/guide/en/elasticsearch/hadoop/current" + stack-ref: "https://www.elastic.co/guide/en/elastic-stack/current" + stack-ref-67: "https://www.elastic.co/guide/en/elastic-stack/6.7" + stack-ref-68: "https://www.elastic.co/guide/en/elastic-stack/6.8" + stack-ref-70: "https://www.elastic.co/guide/en/elastic-stack/7.0" + stack-ref-80: "https://www.elastic.co/guide/en/elastic-stack/8.0" + stack-ov: "https://www.elastic.co/guide/en/elastic-stack-overview/current" + stack-gs: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + stack-gs-current: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + javaclient: "https://www.elastic.co/guide/en/elasticsearch/client/java-api/current" + java-api-client: "https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current" + java-rest: "https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current" + jsclient: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + jsclient-current: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + es-ruby-client: "https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current" + es-dotnet-client: "https://www.elastic.co/guide/en/elasticsearch/client/net-api/current" + es-php-client: "https://www.elastic.co/guide/en/elasticsearch/client/php-api/current" + es-python-client: "https://www.elastic.co/guide/en/elasticsearch/client/python-api/current" + defguide: "https://www.elastic.co/guide/en/elasticsearch/guide/2.x" + painless: "https://www.elastic.co/guide/en/elasticsearch/painless/current" + plugins: "https://www.elastic.co/guide/en/elasticsearch/plugins/current" + plugins-8x: "https://www.elastic.co/guide/en/elasticsearch/plugins/8.1" + plugins-7x: "https://www.elastic.co/guide/en/elasticsearch/plugins/7.17" + plugins-6x: "https://www.elastic.co/guide/en/elasticsearch/plugins/6.8" + glossary: "https://www.elastic.co/guide/en/elastic-stack-glossary/current" + upgrade_guide: "https://www.elastic.co/products/upgrade_guide" + blog-ref: "https://www.elastic.co/blog/" + curator-ref: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + curator-ref-current: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + metrics-ref: "https://www.elastic.co/guide/en/metrics/current" + metrics-guide: "https://www.elastic.co/guide/en/metrics/guide/current" + logs-ref: "https://www.elastic.co/guide/en/logs/current" + logs-guide: "https://www.elastic.co/guide/en/logs/guide/current" + uptime-guide: "https://www.elastic.co/guide/en/uptime/current" + observability-guide: "https://www.elastic.co/guide/en/observability/current" + observability-guide-all: "https://www.elastic.co/guide/en/observability" + siem-guide: "https://www.elastic.co/guide/en/siem/guide/current" + security-guide: "https://www.elastic.co/guide/en/security/current" + security-guide-all: "https://www.elastic.co/guide/en/security" + endpoint-guide: "https://www.elastic.co/guide/en/endpoint/current" + sql-odbc: "https://www.elastic.co/guide/en/elasticsearch/sql-odbc/current" + ecs-ref: "https://www.elastic.co/guide/en/ecs/{{ecs_version}}" + ecs-logging-ref: "https://www.elastic.co/guide/en/ecs-logging/overview/{{ecs-logging}}" + ecs-logging-go-logrus-ref: "https://www.elastic.co/guide/en/ecs-logging/go-logrus/{{ecs-logging-go-logrus}}" + ecs-logging-go-zap-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/{{ecs-logging-go-zap}}" + ecs-logging-go-zerolog-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/{{ecs-logging-go-zerolog}}" + ecs-logging-java-ref: "https://www.elastic.co/guide/en/ecs-logging/java/{{ecs-logging-java}}" + ecs-logging-dotnet-ref: "https://www.elastic.co/guide/en/ecs-logging/dotnet/{{ecs-logging-dotnet}}" + ecs-logging-nodejs-ref: "https://www.elastic.co/guide/en/ecs-logging/nodejs/{{ecs-logging-nodejs}}" + ecs-logging-php-ref: "https://www.elastic.co/guide/en/ecs-logging/php/{{ecs-logging-php}}" + ecs-logging-python-ref: "https://www.elastic.co/guide/en/ecs-logging/python/{{ecs-logging-python}}" + ecs-logging-ruby-ref: "https://www.elastic.co/guide/en/ecs-logging/ruby/{{ecs-logging-ruby}}" + ml-docs: "https://www.elastic.co/guide/en/machine-learning/current" + eland-docs: "https://www.elastic.co/guide/en/elasticsearch/client/eland/current" + eql-ref: "https://eql.readthedocs.io/en/latest/query-guide" + subscriptions: "https://www.elastic.co/subscriptions" + extendtrial: "https://www.elastic.co/trialextension" + wikipedia: "https://en.wikipedia.org/wiki" + forum: "https://discuss.elastic.co/" + xpack-forum: "https://discuss.elastic.co/c/50-x-pack" + security-forum: "https://discuss.elastic.co/c/x-pack/shield" + watcher-forum: "https://discuss.elastic.co/c/x-pack/watcher" + monitoring-forum: "https://discuss.elastic.co/c/x-pack/marvel" + graph-forum: "https://discuss.elastic.co/c/x-pack/graph" + apm-forum: "https://discuss.elastic.co/c/apm" + enterprise-search-ref: "https://www.elastic.co/guide/en/enterprise-search/current" + app-search-ref: "https://www.elastic.co/guide/en/app-search/current" + workplace-search-ref: "https://www.elastic.co/guide/en/workplace-search/current" + enterprise-search-node-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/enterprise-search-node/current" + enterprise-search-php-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/php/current" + enterprise-search-python-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/python/current" + enterprise-search-ruby-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current" + elastic-maps-service: "https://maps.elastic.co" + integrations-docs: "https://docs.elastic.co/en/integrations" + integrations-devguide: "https://www.elastic.co/guide/en/integrations-developer/current" + time-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units" + byte-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units" + apm-py-ref-v: "https://www.elastic.co/guide/en/apm/agent/python/{{apm-py-branch}}" + apm-node-ref-v: "https://www.elastic.co/guide/en/apm/agent/nodejs/{{apm-node-branch}}" + apm-rum-ref-v: "https://www.elastic.co/guide/en/apm/agent/rum-js/{{apm-rum-branch}}" + apm-ruby-ref-v: "https://www.elastic.co/guide/en/apm/agent/ruby/{{apm-ruby-branch}}" + apm-java-ref-v: "https://www.elastic.co/guide/en/apm/agent/java/{{apm-java-branch}}" + apm-go-ref-v: "https://www.elastic.co/guide/en/apm/agent/go/{{apm-go-branch}}" + apm-ios-ref-v: "https://www.elastic.co/guide/en/apm/agent/swift/{{apm-ios-branch}}" + apm-dotnet-ref-v: "https://www.elastic.co/guide/en/apm/agent/dotnet/{{apm-dotnet-branch}}" + apm-php-ref-v: "https://www.elastic.co/guide/en/apm/agent/php/{{apm-php-branch}}" + ecloud: "Elastic Cloud" + esf: "Elastic Serverless Forwarder" + ess: "Elasticsearch Service" + ece: "Elastic Cloud Enterprise" + eck: "Elastic Cloud on Kubernetes" + serverless-full: "Elastic Cloud Serverless" + serverless-short: "Serverless" + es-serverless: "Elasticsearch Serverless" + es3: "Elasticsearch Serverless" + obs-serverless: "Elastic Observability Serverless" + sec-serverless: "Elastic Security Serverless" + serverless-docs: "https://docs.elastic.co/serverless" + cloud: "https://www.elastic.co/guide/en/cloud/current" + ess-utm-params: "?page=docs&placement=docs-body" + ess-baymax: "?page=docs&placement=docs-body" + ess-trial: "https://cloud.elastic.co/registration?page=docs&placement=docs-body" + ess-product: "https://www.elastic.co/cloud/elasticsearch-service?page=docs&placement=docs-body" + ess-console: "https://cloud.elastic.co?page=docs&placement=docs-body" + ess-console-name: "Elasticsearch Service Console" + ess-deployments: "https://cloud.elastic.co/deployments?page=docs&placement=docs-body" + ece-ref: "https://www.elastic.co/guide/en/cloud-enterprise/{{ece-version-link}}" + eck-ref: "https://www.elastic.co/guide/en/cloud-on-k8s/current" + ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. https://cloud.elastic.co/registration{ess-utm-params}[Try the Elasticsearch Service for free]." + ess-leadin-short: "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can https://cloud.elastic.co/registration{ess-utm-params}[try it for free]." + ess-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elasticsearch Service\"]" + ece-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud_ece.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elastic Cloud Enterprise\"]" + cloud-only: "This feature is designed for indirect use by https://cloud.elastic.co/registration{ess-utm-params}[Elasticsearch Service], https://www.elastic.co/guide/en/cloud-enterprise/{ece-version-link}[Elastic Cloud Enterprise], and https://www.elastic.co/guide/en/cloud-on-k8s/current[Elastic Cloud on Kubernetes]. Direct use is not supported." + ess-setting-change: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"{ess-trial}\", title=\"Supported on {ess}\"] indicates a change to a supported https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html[user setting] for Elasticsearch Service." + ess-skip-section: "If you use Elasticsearch Service, skip this section. Elasticsearch Service handles these changes for you." + api-cloud: "https://www.elastic.co/docs/api/doc/cloud" + api-ece: "https://www.elastic.co/docs/api/doc/cloud-enterprise" + api-kibana-serverless: "https://www.elastic.co/docs/api/doc/serverless" + es-feature-flag: "This feature is in development and not yet available for use. This documentation is provided for informational purposes only." + es-ref-dir: "'{{elasticsearch-root}}/docs/reference'" + apm-app: "APM app" + uptime-app: "Uptime app" + synthetics-app: "Synthetics app" + logs-app: "Logs app" + metrics-app: "Metrics app" + infrastructure-app: "Infrastructure app" + siem-app: "SIEM app" + security-app: "Elastic Security app" + ml-app: "Machine Learning" + dev-tools-app: "Dev Tools" + ingest-manager-app: "Ingest Manager" + stack-manage-app: "Stack Management" + stack-monitor-app: "Stack Monitoring" + alerts-ui: "Alerts and Actions" + rules-ui: "Rules" + rac-ui: "Rules and Connectors" + connectors-ui: "Connectors" + connectors-feature: "Actions and Connectors" + stack-rules-feature: "Stack Rules" + user-experience: "User Experience" + ems: "Elastic Maps Service" + ems-init: "EMS" + hosted-ems: "Elastic Maps Server" + ipm-app: "Index Pattern Management" + ingest-pipelines: "ingest pipelines" + ingest-pipelines-app: "Ingest Pipelines" + ingest-pipelines-cap: "Ingest pipelines" + ls-pipelines: "Logstash pipelines" + ls-pipelines-app: "Logstash Pipelines" + maint-windows: "maintenance windows" + maint-windows-app: "Maintenance Windows" + maint-windows-cap: "Maintenance windows" + custom-roles-app: "Custom Roles" + data-source: "data view" + data-sources: "data views" + data-source-caps: "Data View" + data-sources-caps: "Data Views" + data-source-cap: "Data view" + data-sources-cap: "Data views" + project-settings: "Project settings" + manage-app: "Management" + index-manage-app: "Index Management" + data-views-app: "Data Views" + rules-app: "Rules" + saved-objects-app: "Saved Objects" + tags-app: "Tags" + api-keys-app: "API keys" + transforms-app: "Transforms" + connectors-app: "Connectors" + files-app: "Files" + reports-app: "Reports" + maps-app: "Maps" + alerts-app: "Alerts" + crawler: "Enterprise Search web crawler" + ents: "Enterprise Search" + app-search-crawler: "App Search web crawler" + agent: "Elastic Agent" + agents: "Elastic Agents" + fleet: "Fleet" + fleet-server: "Fleet Server" + integrations-server: "Integrations Server" + ingest-manager: "Ingest Manager" + ingest-management: "ingest management" + package-manager: "Elastic Package Manager" + integrations: "Integrations" + package-registry: "Elastic Package Registry" + artifact-registry: "Elastic Artifact Registry" + aws: "AWS" + stack: "Elastic Stack" + xpack: "X-Pack" + es: "Elasticsearch" + kib: "Kibana" + esms: "Elastic Stack Monitoring Service" + esms-init: "ESMS" + ls: "Logstash" + beats: "Beats" + auditbeat: "Auditbeat" + filebeat: "Filebeat" + heartbeat: "Heartbeat" + metricbeat: "Metricbeat" + packetbeat: "Packetbeat" + winlogbeat: "Winlogbeat" + functionbeat: "Functionbeat" + journalbeat: "Journalbeat" + es-sql: "Elasticsearch SQL" + esql: "ES|QL" + elastic-agent: "Elastic Agent" + k8s: "Kubernetes" + log-driver-long: "Elastic Logging Plugin for Docker" + security: "X-Pack security" + security-features: "security features" + operator-feature: "operator privileges feature" + es-security-features: "Elasticsearch security features" + stack-security-features: "Elastic Stack security features" + endpoint-sec: "Endpoint Security" + endpoint-cloud-sec: "Endpoint and Cloud Security" + elastic-defend: "Elastic Defend" + elastic-sec: "Elastic Security" + elastic-endpoint: "Elastic Endpoint" + swimlane: "Swimlane" + sn: "ServiceNow" + sn-itsm: "ServiceNow ITSM" + sn-itom: "ServiceNow ITOM" + sn-sir: "ServiceNow SecOps" + jira: "Jira" + ibm-r: "IBM Resilient" + webhook: "Webhook" + webhook-cm: "Webhook - Case Management" + opsgenie: "Opsgenie" + bedrock: "Amazon Bedrock" + gemini: "Google Gemini" + hive: "TheHive" + monitoring: "X-Pack monitoring" + monitor-features: "monitoring features" + stack-monitor-features: "Elastic Stack monitoring features" + watcher: "Watcher" + alert-features: "alerting features" + reporting: "X-Pack reporting" + report-features: "reporting features" + graph: "X-Pack graph" + graph-features: "graph analytics features" + searchprofiler: "Search Profiler" + xpackml: "X-Pack machine learning" + ml: "machine learning" + ml-cap: "Machine learning" + ml-init: "ML" + ml-features: "machine learning features" + stack-ml-features: "Elastic Stack machine learning features" + ccr: "cross-cluster replication" + ccr-cap: "Cross-cluster replication" + ccr-init: "CCR" + ccs: "cross-cluster search" + ccs-cap: "Cross-cluster search" + ccs-init: "CCS" + ilm: "index lifecycle management" + ilm-cap: "Index lifecycle management" + ilm-init: "ILM" + dlm: "data lifecycle management" + dlm-cap: "Data lifecycle management" + dlm-init: "DLM" + search-snap: "searchable snapshot" + search-snaps: "searchable snapshots" + search-snaps-cap: "Searchable snapshots" + slm: "snapshot lifecycle management" + slm-cap: "Snapshot lifecycle management" + slm-init: "SLM" + rollup-features: "data rollup features" + ipm: "index pattern management" + ipm-cap: "Index pattern" + rollup: "rollup" + rollup-cap: "Rollup" + rollups: "rollups" + rollups-cap: "Rollups" + rollup-job: "rollup job" + rollup-jobs: "rollup jobs" + rollup-jobs-cap: "Rollup jobs" + dfeed: "datafeed" + dfeeds: "datafeeds" + dfeed-cap: "Datafeed" + dfeeds-cap: "Datafeeds" + ml-jobs: "machine learning jobs" + ml-jobs-cap: "Machine learning jobs" + anomaly-detect: "anomaly detection" + anomaly-detect-cap: "Anomaly detection" + anomaly-job: "anomaly detection job" + anomaly-jobs: "anomaly detection jobs" + anomaly-jobs-cap: "Anomaly detection jobs" + dataframe: "data frame" + dataframes: "data frames" + dataframe-cap: "Data frame" + dataframes-cap: "Data frames" + watcher-transform: "payload transform" + watcher-transforms: "payload transforms" + watcher-transform-cap: "Payload transform" + watcher-transforms-cap: "Payload transforms" + transform: "transform" + transforms: "transforms" + transform-cap: "Transform" + transforms-cap: "Transforms" + dataframe-transform: "transform" + dataframe-transform-cap: "Transform" + dataframe-transforms: "transforms" + dataframe-transforms-cap: "Transforms" + dfanalytics-cap: "Data frame analytics" + dfanalytics: "data frame analytics" + dataframe-analytics-config: "'{dataframe} analytics config'" + dfanalytics-job: "'{dataframe} analytics job'" + dfanalytics-jobs: "'{dataframe} analytics jobs'" + dfanalytics-jobs-cap: "'{dataframe-cap} analytics jobs'" + cdataframe: "continuous data frame" + cdataframes: "continuous data frames" + cdataframe-cap: "Continuous data frame" + cdataframes-cap: "Continuous data frames" + cdataframe-transform: "continuous transform" + cdataframe-transforms: "continuous transforms" + cdataframe-transforms-cap: "Continuous transforms" + ctransform: "continuous transform" + ctransform-cap: "Continuous transform" + ctransforms: "continuous transforms" + ctransforms-cap: "Continuous transforms" + oldetection: "outlier detection" + oldetection-cap: "Outlier detection" + olscore: "outlier score" + olscores: "outlier scores" + fiscore: "feature influence score" + evaluatedf-api: "evaluate {dataframe} analytics API" + evaluatedf-api-cap: "Evaluate {dataframe} analytics API" + binarysc: "binary soft classification" + binarysc-cap: "Binary soft classification" + regression: "regression" + regression-cap: "Regression" + reganalysis: "regression analysis" + reganalysis-cap: "Regression analysis" + depvar: "dependent variable" + feature-var: "feature variable" + feature-vars: "feature variables" + feature-vars-cap: "Feature variables" + classification: "classification" + classification-cap: "Classification" + classanalysis: "classification analysis" + classanalysis-cap: "Classification analysis" + infer-cap: "Inference" + infer: "inference" + lang-ident-cap: "Language identification" + lang-ident: "language identification" + data-viz: "Data Visualizer" + file-data-viz: "File Data Visualizer" + feat-imp: "feature importance" + feat-imp-cap: "Feature importance" + nlp: "natural language processing" + nlp-cap: "Natural language processing" + apm-agent: "APM agent" + apm-go-agent: "Elastic APM Go agent" + apm-go-agents: "Elastic APM Go agents" + apm-ios-agent: "Elastic APM iOS agent" + apm-ios-agents: "Elastic APM iOS agents" + apm-java-agent: "Elastic APM Java agent" + apm-java-agents: "Elastic APM Java agents" + apm-dotnet-agent: "Elastic APM .NET agent" + apm-dotnet-agents: "Elastic APM .NET agents" + apm-node-agent: "Elastic APM Node.js agent" + apm-node-agents: "Elastic APM Node.js agents" + apm-php-agent: "Elastic APM PHP agent" + apm-php-agents: "Elastic APM PHP agents" + apm-py-agent: "Elastic APM Python agent" + apm-py-agents: "Elastic APM Python agents" + apm-ruby-agent: "Elastic APM Ruby agent" + apm-ruby-agents: "Elastic APM Ruby agents" + apm-rum-agent: "Elastic APM Real User Monitoring (RUM) JavaScript agent" + apm-rum-agents: "Elastic APM RUM JavaScript agents" + apm-lambda-ext: "Elastic APM AWS Lambda extension" + project-monitors: "project monitors" + project-monitors-cap: "Project monitors" + private-location: "Private Location" + private-locations: "Private Locations" + pwd: "YOUR_PASSWORD" + esh: "ES-Hadoop" + default-dist: "default distribution" + oss-dist: "OSS-only distribution" + observability: "Observability" + api-request-title: "Request" + api-prereq-title: "Prerequisites" + api-description-title: "Description" + api-path-parms-title: "Path parameters" + api-query-parms-title: "Query parameters" + api-request-body-title: "Request body" + api-response-codes-title: "Response codes" + api-response-body-title: "Response body" + api-example-title: "Example" + api-examples-title: "Examples" + api-definitions-title: "Properties" + multi-arg: "†footnoteref:[multi-arg,This parameter accepts multiple arguments.]" + multi-arg-ref: "†footnoteref:[multi-arg]" + yes-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png[Yes,20,15]" + no-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png[No,20,15]" + es-repo: "https://github.com/elastic/elasticsearch/" + es-issue: "https://github.com/elastic/elasticsearch/issues/" + es-pull: "https://github.com/elastic/elasticsearch/pull/" + es-commit: "https://github.com/elastic/elasticsearch/commit/" + kib-repo: "https://github.com/elastic/kibana/" + kib-issue: "https://github.com/elastic/kibana/issues/" + kibana-issue: "'{kib-repo}issues/'" + kib-pull: "https://github.com/elastic/kibana/pull/" + kibana-pull: "'{kib-repo}pull/'" + kib-commit: "https://github.com/elastic/kibana/commit/" + ml-repo: "https://github.com/elastic/ml-cpp/" + ml-issue: "https://github.com/elastic/ml-cpp/issues/" + ml-pull: "https://github.com/elastic/ml-cpp/pull/" + ml-commit: "https://github.com/elastic/ml-cpp/commit/" + apm-repo: "https://github.com/elastic/apm-server/" + apm-issue: "https://github.com/elastic/apm-server/issues/" + apm-pull: "https://github.com/elastic/apm-server/pull/" + kibana-blob: "https://github.com/elastic/kibana/blob/current/" + apm-get-started-ref: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-server-ref: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-v: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-m: "https://www.elastic.co/guide/en/apm/server/master" + apm-server-ref-62: "https://www.elastic.co/guide/en/apm/server/6.2" + apm-server-ref-64: "https://www.elastic.co/guide/en/apm/server/6.4" + apm-server-ref-70: "https://www.elastic.co/guide/en/apm/server/7.0" + apm-overview-ref-v: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-overview-ref-70: "https://www.elastic.co/guide/en/apm/get-started/7.0" + apm-overview-ref-m: "https://www.elastic.co/guide/en/apm/get-started/master" + infra-guide: "https://www.elastic.co/guide/en/infrastructure/guide/current" + a-data-source: "a data view" + icon-bug: "pass:[]" + icon-checkInCircleFilled: "pass:[]" + icon-warningFilled: "pass:[]" diff --git a/elastic-basics/index.md b/elastic-basics/index.md deleted file mode 100644 index e8ee207ea..000000000 --- a/elastic-basics/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Elastic Basics ---- \ No newline at end of file diff --git a/elastic-basics/toc.yml b/elastic-basics/toc.yml deleted file mode 100644 index f69f3fdee..000000000 --- a/elastic-basics/toc.yml +++ /dev/null @@ -1,3 +0,0 @@ -project: 'Elastic Basics' -toc: - - file: index.md \ No newline at end of file diff --git a/explore-analyze/aggregations.md b/explore-analyze/aggregations.md new file mode 100644 index 000000000..6b0cdd288 --- /dev/null +++ b/explore-analyze/aggregations.md @@ -0,0 +1,309 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html +--- + +# Aggregations [search-aggregations] + +An aggregation summarizes your data as metrics, statistics, or other analytics. Aggregations help you answer questions like: + +* What’s the average load time for my website? +* Who are my most valuable customers based on transaction volume? +* What would be considered a large file on my network? +* How many products are in each product category? + +{{es}} organizes aggregations into three categories: + +* [Metric](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics.html) aggregations that calculate metrics, such as a sum or average, from field values. +* [Bucket](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket.html) aggregations that group documents into buckets, also called bins, based on field values, ranges, or other criteria. +* [Pipeline](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline.html) aggregations that take input from other aggregations instead of documents or fields. + + +## Run an aggregation [run-an-agg] + +You can run aggregations as part of a [search](../solutions/search/querying-for-search-searching-with-the-search-api.md) by specifying the [search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html)'s `aggs` parameter. The following search runs a [terms aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) on `my-field`: + +```console +GET /my-index-000001/_search +{ + "aggs": { + "my-agg-name": { + "terms": { + "field": "my-field" + } + } + } +} +``` + +Aggregation results are in the response’s `aggregations` object: + +```console-result +{ + "took": 78, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 5, + "relation": "eq" + }, + "max_score": 1.0, + "hits": [...] + }, + "aggregations": { + "my-agg-name": { <1> + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0, + "buckets": [] + } + } +} +``` + +1. Results for the `my-agg-name` aggregation. + + + +## Change an aggregation’s scope [change-agg-scope] + +Use the `query` parameter to limit the documents on which an aggregation runs: + +```console +GET /my-index-000001/_search +{ + "query": { + "range": { + "@timestamp": { + "gte": "now-1d/d", + "lt": "now/d" + } + } + }, + "aggs": { + "my-agg-name": { + "terms": { + "field": "my-field" + } + } + } +} +``` + + +## Return only aggregation results [return-only-agg-results] + +By default, searches containing an aggregation return both search hits and aggregation results. To return only aggregation results, set `size` to `0`: + +```console +GET /my-index-000001/_search +{ + "size": 0, + "aggs": { + "my-agg-name": { + "terms": { + "field": "my-field" + } + } + } +} +``` + + +## Run multiple aggregations [run-multiple-aggs] + +You can specify multiple aggregations in the same request: + +```console +GET /my-index-000001/_search +{ + "aggs": { + "my-first-agg-name": { + "terms": { + "field": "my-field" + } + }, + "my-second-agg-name": { + "avg": { + "field": "my-other-field" + } + } + } +} +``` + + +## Run sub-aggregations [run-sub-aggs] + +Bucket aggregations support bucket or metric sub-aggregations. For example, a terms aggregation with an [avg](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-avg-aggregation.html) sub-aggregation calculates an average value for each bucket of documents. There is no level or depth limit for nesting sub-aggregations. + +```console +GET /my-index-000001/_search +{ + "aggs": { + "my-agg-name": { + "terms": { + "field": "my-field" + }, + "aggs": { + "my-sub-agg-name": { + "avg": { + "field": "my-other-field" + } + } + } + } + } +} +``` + +The response nests sub-aggregation results under their parent aggregation: + +```console-result +{ + ... + "aggregations": { + "my-agg-name": { <1> + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0, + "buckets": [ + { + "key": "foo", + "doc_count": 5, + "my-sub-agg-name": { <2> + "value": 75.0 + } + } + ] + } + } +} +``` + +1. Results for the parent aggregation, `my-agg-name`. +2. Results for `my-agg-name`'s sub-aggregation, `my-sub-agg-name`. + + + +## Add custom metadata [add-metadata-to-an-agg] + +Use the `meta` object to associate custom metadata with an aggregation: + +```console +GET /my-index-000001/_search +{ + "aggs": { + "my-agg-name": { + "terms": { + "field": "my-field" + }, + "meta": { + "my-metadata-field": "foo" + } + } + } +} +``` + +The response returns the `meta` object in place: + +```console-result +{ + ... + "aggregations": { + "my-agg-name": { + "meta": { + "my-metadata-field": "foo" + }, + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0, + "buckets": [] + } + } +} +``` + + +## Return the aggregation type [return-agg-type] + +By default, aggregation results include the aggregation’s name but not its type. To return the aggregation type, use the `typed_keys` query parameter. + +```console +GET /my-index-000001/_search?typed_keys +{ + "aggs": { + "my-agg-name": { + "histogram": { + "field": "my-field", + "interval": 1000 + } + } + } +} +``` + +The response returns the aggregation type as a prefix to the aggregation’s name. + +::::{important} +Some aggregations return a different aggregation type from the type in the request. For example, the terms, [significant terms](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-significantterms-aggregation.html), and [percentiles](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-aggregation.html) aggregations return different aggregations types depending on the data type of the aggregated field. +:::: + + +```console-result +{ + ... + "aggregations": { + "histogram#my-agg-name": { <1> + "buckets": [] + } + } +} +``` + +1. The aggregation type, `histogram`, followed by a `#` separator and the aggregation’s name, `my-agg-name`. + + + +## Use scripts in an aggregation [use-scripts-in-an-agg] + +When a field doesn’t exactly match the aggregation you need, you should aggregate on a [runtime field](../manage-data/data-store/mapping/runtime-fields.md): + +```console +GET /my-index-000001/_search?size=0 +{ + "runtime_mappings": { + "message.length": { + "type": "long", + "script": "emit(doc['message.keyword'].value.length())" + } + }, + "aggs": { + "message_length": { + "histogram": { + "interval": 10, + "field": "message.length" + } + } + } +} +``` + +Scripts calculate field values dynamically, which adds a little overhead to the aggregation. In addition to the time spent calculating, some aggregations like [`terms`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) and [`filters`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filters-aggregation.html) can’t use some of their optimizations with runtime fields. In total, performance costs for using a runtime field varies from aggregation to aggregation. + + +## Aggregation caches [agg-caches] + +For faster responses, {{es}} caches the results of frequently run aggregations in the [shard request cache](https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-request-cache.html). To get cached results, use the same [`preference` string](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-shard-routing.html#shard-and-node-preference) for each search. If you don’t need search hits, [set `size` to `0`](#return-only-agg-results) to avoid filling the cache. + +{{es}} routes searches with the same preference string to the same shards. If the shards' data doesn’t change between searches, the shards return cached aggregation results. + + +## Limits for `long` values [limits-for-long-values] + +When running aggregations, {{es}} uses [`double`](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html) values to hold and represent numeric data. As a result, aggregations on [`long`](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html) numbers greater than `253` are approximate. + diff --git a/explore-analyze/aggregations/tutorial-analyze-ecommerce-data-with-aggregations-using-query-dsl.md b/explore-analyze/aggregations/tutorial-analyze-ecommerce-data-with-aggregations-using-query-dsl.md new file mode 100644 index 000000000..65a31dfee --- /dev/null +++ b/explore-analyze/aggregations/tutorial-analyze-ecommerce-data-with-aggregations-using-query-dsl.md @@ -0,0 +1,2176 @@ +--- +navigation_title: "Basics" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/aggregations-tutorial.html +--- + + + +# Tutorial: Analyze eCommerce data with aggregations using Query DSL [aggregations-tutorial] + + +This hands-on tutorial shows you how to analyze eCommerce data using {{es}} [aggregations](../aggregations.md) with the `_search` API and Query DSL. + +You’ll learn how to: + +* Calculate key business metrics such as average order value +* Analyze sales patterns over time +* Compare performance across product categories +* Track moving averages and cumulative totals + + +## Requirements [aggregations-tutorial-requirements] + +You’ll need: + +1. A running instance of [{{es}}](../../get-started/deployment-options.md), either on {{serverless-full}} or together with {{kib}} on Elastic Cloud Hosted/Self Managed deployments. + + * If you don’t have a deployment, you can run the following command in your terminal to set up a [local dev environment](../../solutions/search/get-started.md): + + ```sh + curl -fsSL https://elastic.co/start-local | sh + ``` + +2. The [sample eCommerce data](../overview/kibana-quickstart.md#gs-get-data-into-kibana) loaded into {{es}}. To load sample data follow these steps in your UI: + + * Open the **Integrations** pages by searching in the global search field. + * Search for `sample data` in the **Integrations** search field. + * Open the **Sample data** page. + * Select the **Other sample data sets** collapsible. + * Add the **Sample eCommerce orders** data set. This will create and populate an index called `kibana_sample_data_ecommerce`. + + + +## Inspect index structure [aggregations-tutorial-inspect-data] + +Before we start analyzing the data, let’s examine the structure of the documents in our sample eCommerce index. Run this command to see the field [mappings](../../manage-data/data-store/index-basics.md#elasticsearch-intro-documents-fields-mappings): + +```console +GET kibana_sample_data_ecommerce/_mapping +``` + +The response shows the field mappings for the `kibana_sample_data_ecommerce` index. + +::::{dropdown} Example response +```console-response +{ + "kibana_sample_data_ecommerce": { + "mappings": { + "properties": { + "category": { + "type": "text", + "fields": { <1> + "keyword": { + "type": "keyword" + } + } + }, + "currency": { + "type": "keyword" + }, + "customer_birth_date": { + "type": "date" + }, + "customer_first_name": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "customer_full_name": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "customer_gender": { + "type": "keyword" + }, + "customer_id": { + "type": "keyword" + }, + "customer_last_name": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "customer_phone": { + "type": "keyword" + }, + "day_of_week": { + "type": "keyword" + }, + "day_of_week_i": { + "type": "integer" + }, + "email": { + "type": "keyword" + }, + "event": { + "properties": { + "dataset": { + "type": "keyword" + } + } + }, + "geoip": { + "properties": { <2> + "city_name": { + "type": "keyword" + }, + "continent_name": { + "type": "keyword" + }, + "country_iso_code": { + "type": "keyword" + }, + "location": { + "type": "geo_point" <3> + }, + "region_name": { + "type": "keyword" + } + } + }, + "manufacturer": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword" + } + } + }, + "order_date": { + "type": "date" + }, + "order_id": { + "type": "keyword" + }, + "products": { + "properties": { <4> + "_id": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword", + "ignore_above": 256 + } + } + }, + "base_price": { + "type": "half_float" + }, + "base_unit_price": { + "type": "half_float" + }, + "category": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword" + } + } + }, + "created_on": { + "type": "date" + }, + "discount_amount": { + "type": "half_float" + }, + "discount_percentage": { + "type": "half_float" + }, + "manufacturer": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword" + } + } + }, + "min_price": { + "type": "half_float" + }, + "price": { + "type": "half_float" + }, + "product_id": { + "type": "long" + }, + "product_name": { + "type": "text", + "fields": { + "keyword": { + "type": "keyword" + } + }, + "analyzer": "english" + }, + "quantity": { + "type": "integer" + }, + "sku": { + "type": "keyword" + }, + "tax_amount": { + "type": "half_float" + }, + "taxful_price": { + "type": "half_float" + }, + "taxless_price": { + "type": "half_float" + }, + "unit_discount_amount": { + "type": "half_float" + } + } + }, + "sku": { + "type": "keyword" + }, + "taxful_total_price": { + "type": "half_float" + }, + "taxless_total_price": { + "type": "half_float" + }, + "total_quantity": { + "type": "integer" + }, + "total_unique_products": { + "type": "integer" + }, + "type": { + "type": "keyword" + }, + "user": { + "type": "keyword" + } + } + } + } +} +``` + +1. `fields`: Multi-field mapping that allows both full text and exact matching +2. `geoip.properties`: Object type field containing location-related properties +3. `geoip.location`: Geographic coordinates stored as geo_point for location-based queries +4. `products.properties`: Nested structure containing details about items in each order + + +:::: + + +The sample data includes the following [field data types](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html): + +* [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) and [`keyword`](https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html) for text fields + + * Most `text` fields have a `.keyword` subfield for exact matching using [multi-fields](https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-fields.html) + +* [`date`](https://www.elastic.co/guide/en/elasticsearch/reference/current/date.html) for date fields +* 3 [numeric](https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html) types: + + * `integer` for whole numbers + * `long` for large whole numbers + * `half_float` for floating-point numbers + +* [`geo_point`](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-point.html) for geographic coordinates +* [`object`](https://www.elastic.co/guide/en/elasticsearch/reference/current/object.html) for nested structures such as `products`, `geoip`, `event` + +Now that we understand the structure of our sample data, let’s start analyzing it. + + +## Get key business metrics [aggregations-tutorial-basic-metrics] + +Let’s start by calculating important metrics about orders and customers. + + +### Get average order size [aggregations-tutorial-order-value] + +Calculate the average order value across all orders in the dataset using the [`avg`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-avg-aggregation.html) aggregation. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, <1> + "aggs": { + "avg_order_value": { <2> + "avg": { <3> + "field": "taxful_total_price" + } + } + } +} +``` + +1. Set `size` to 0 to avoid returning matched documents in the response and return only the aggregation results +2. A meaningful name that describes what this metric represents +3. Configures an `avg` aggregation, which calculates a simple arithmetic mean + + +::::{dropdown} Example response +```console-result +{ + "took": 0, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4675, <1> + "relation": "eq" + }, + "max_score": null, + "hits": [] <2> + }, + "aggregations": { + "avg_order_value": { <3> + "value": 75.05542864304813 <4> + } + } +} +``` + +1. Total number of orders in the dataset +2. `hits` is empty because we set `size` to 0 +3. Results appear under the name we specified in the request +4. The average order value is calculated dynamically from all the orders in the dataset + + +:::: + + + +### Get multiple order statistics at once [aggregations-tutorial-order-stats] + +Calculate multiple statistics about orders in one request using the [`stats`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-stats-aggregation.html) aggregation. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "order_stats": { <1> + "stats": { <2> + "field": "taxful_total_price" + } + } + } +} +``` + +1. A descriptive name for this set of statistics +2. `stats` returns count, min, max, avg, and sum at once + + +::::{dropdown} Example response +```console-result +{ + "aggregations": { + "order_stats": { + "count": 4675, <1> + "min": 6.98828125, <2> + "max": 2250, <3> + "avg": 75.05542864304813, <4> + "sum": 350884.12890625 <5> + } + } +} +``` + +1. `"count"`: Total number of orders in the dataset +2. `"min"`: Lowest individual order value in the dataset +3. `"max"`: Highest individual order value in the dataset +4. `"avg"`: Average value per order across all orders +5. `"sum"`: Total revenue from all orders combined + + +:::: + + +::::{tip} +The [stats aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-stats-aggregation.html) is more efficient than running individual min, max, avg, and sum aggregations. + +:::: + + + +## Analyze sales patterns [aggregations-tutorial-sales-patterns] + +Let’s group orders in different ways to understand sales patterns. + + +### Break down sales by category [aggregations-tutorial-category-breakdown] + +Group orders by category to see which product categories are most popular, using the [`terms`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) aggregation. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "sales_by_category": { <1> + "terms": { <2> + "field": "category.keyword", <3> + "size": 5, <4> + "order": { "_count": "desc" } <5> + } + } + } +} +``` + +1. Name reflecting the business purpose of this breakdown +2. `terms` aggregation groups documents by field values +3. Use [`.keyword`](https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html) field for exact matching on text fields +4. Limit to top 5 categories +5. Order by number of orders (descending) + + +::::{dropdown} Example response +```console-result +{ + "took": 4, + "timed_out": false, + "_shards": { + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4675, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, + "aggregations": { + "sales_by_category": { + "doc_count_error_upper_bound": 0, <1> + "sum_other_doc_count": 572, <2> + "buckets": [ <3> + { + "key": "Men's Clothing", <4> + "doc_count": 2024 <5> + }, + { + "key": "Women's Clothing", + "doc_count": 1903 + }, + { + "key": "Women's Shoes", + "doc_count": 1136 + }, + { + "key": "Men's Shoes", + "doc_count": 944 + }, + { + "key": "Women's Accessories", + "doc_count": 830 + } + ] + } + } +} +``` + +1. Due to Elasticsearch’s distributed architecture, when [terms aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) run across multiple shards, the doc counts may have a small margin of error. This value indicates the maximum possible error in the counts. +2. Count of documents in categories beyond the requested size. +3. Array of category buckets, ordered by count. +4. Category name. +5. Number of orders in this category. + + +:::: + + + +### Track daily sales patterns [aggregations-tutorial-daily-sales] + +Group orders by day to track daily sales patterns using the [`date_histogram`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html) aggregation. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "daily_orders": { <1> + "date_histogram": { <2> + "field": "order_date", + "calendar_interval": "day", <3> + "format": "yyyy-MM-dd", <4> + "min_doc_count": 0 <5> + } + } + } +} +``` + +1. Descriptive name for the time-series aggregation results. +2. The `date_histogram` aggregation groups documents into time-based buckets, similar to terms aggregation but for dates. +3. Uses [calendar and fixed time intervals](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html#calendar_and_fixed_intervals) to handle months with different lengths. `"day"` ensures consistent daily grouping regardless of timezone. +4. Formats dates in response using [date patterns](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html) (e.g. "yyyy-MM-dd"). Refer to [date math expressions](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math) for additional options. +5. When `min_doc_count` is 0, returns buckets for days with no orders, useful for continuous time series visualization. + + +::::{dropdown} Example response +```console-result +{ + "took": 2, + "timed_out": false, + "_shards": { + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4675, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, + "aggregations": { + "daily_orders": { <1> + "buckets": [ <2> + { + "key_as_string": "2024-11-28", <3> + "key": 1732752000000, <4> + "doc_count": 146 <5> + }, + { + "key_as_string": "2024-11-29", + "key": 1732838400000, + "doc_count": 153 + }, + { + "key_as_string": "2024-11-30", + "key": 1732924800000, + "doc_count": 143 + }, + { + "key_as_string": "2024-12-01", + "key": 1733011200000, + "doc_count": 140 + }, + { + "key_as_string": "2024-12-02", + "key": 1733097600000, + "doc_count": 139 + }, + { + "key_as_string": "2024-12-03", + "key": 1733184000000, + "doc_count": 157 + }, + { + "key_as_string": "2024-12-04", + "key": 1733270400000, + "doc_count": 145 + }, + { + "key_as_string": "2024-12-05", + "key": 1733356800000, + "doc_count": 152 + }, + { + "key_as_string": "2024-12-06", + "key": 1733443200000, + "doc_count": 163 + }, + { + "key_as_string": "2024-12-07", + "key": 1733529600000, + "doc_count": 141 + }, + { + "key_as_string": "2024-12-08", + "key": 1733616000000, + "doc_count": 151 + }, + { + "key_as_string": "2024-12-09", + "key": 1733702400000, + "doc_count": 143 + }, + { + "key_as_string": "2024-12-10", + "key": 1733788800000, + "doc_count": 143 + }, + { + "key_as_string": "2024-12-11", + "key": 1733875200000, + "doc_count": 142 + }, + { + "key_as_string": "2024-12-12", + "key": 1733961600000, + "doc_count": 161 + }, + { + "key_as_string": "2024-12-13", + "key": 1734048000000, + "doc_count": 144 + }, + { + "key_as_string": "2024-12-14", + "key": 1734134400000, + "doc_count": 157 + }, + { + "key_as_string": "2024-12-15", + "key": 1734220800000, + "doc_count": 158 + }, + { + "key_as_string": "2024-12-16", + "key": 1734307200000, + "doc_count": 144 + }, + { + "key_as_string": "2024-12-17", + "key": 1734393600000, + "doc_count": 151 + }, + { + "key_as_string": "2024-12-18", + "key": 1734480000000, + "doc_count": 145 + }, + { + "key_as_string": "2024-12-19", + "key": 1734566400000, + "doc_count": 157 + }, + { + "key_as_string": "2024-12-20", + "key": 1734652800000, + "doc_count": 158 + }, + { + "key_as_string": "2024-12-21", + "key": 1734739200000, + "doc_count": 153 + }, + { + "key_as_string": "2024-12-22", + "key": 1734825600000, + "doc_count": 165 + }, + { + "key_as_string": "2024-12-23", + "key": 1734912000000, + "doc_count": 153 + }, + { + "key_as_string": "2024-12-24", + "key": 1734998400000, + "doc_count": 158 + }, + { + "key_as_string": "2024-12-25", + "key": 1735084800000, + "doc_count": 160 + }, + { + "key_as_string": "2024-12-26", + "key": 1735171200000, + "doc_count": 159 + }, + { + "key_as_string": "2024-12-27", + "key": 1735257600000, + "doc_count": 152 + }, + { + "key_as_string": "2024-12-28", + "key": 1735344000000, + "doc_count": 142 + } + ] + } + } +} +``` + +1. Results of our named aggregation "daily_orders" +2. Time-based buckets from date_histogram aggregation +3. `key_as_string` is the human-readable date for this bucket +4. `key` is the same date represented as the Unix timestamp for this bucket +5. `doc_count` counts the number of documents that fall into this time bucket + + +:::: + + + +## Combine metrics with groupings [aggregations-tutorial-combined-analysis] + +Now let’s calculate [metrics](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics.html) within each group to get deeper insights. + + +### Compare category performance [aggregations-tutorial-category-metrics] + +Calculate metrics within each category to compare performance across categories. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "categories": { + "terms": { + "field": "category.keyword", + "size": 5, + "order": { "total_revenue": "desc" } <1> + }, + "aggs": { <2> + "total_revenue": { <3> + "sum": { + "field": "taxful_total_price" + } + }, + "avg_order_value": { <4> + "avg": { + "field": "taxful_total_price" + } + }, + "total_items": { <5> + "sum": { + "field": "total_quantity" + } + } + } + } + } +} +``` + +1. Order categories by their total revenue instead of count +2. Define metrics to calculate within each category +3. Total revenue for the category +4. Average order value in the category +5. Total number of items sold + + +::::{dropdown} Example response +```console-result +{ + "aggregations": { + "categories": { + "buckets": [ + { + "key": "Men's Clothing", <1> + "doc_count": 2179, <2> + "total_revenue": { <3> + "value": 156729.453125 + }, + "avg_order_value": { <4> + "value": 71.92726898715927 + }, + "total_items": { <5> + "value": 8716 + } + }, + { + "key": "Women's Clothing", + "doc_count": 2262, + ... + } + ] + } + } +} +``` + +1. Category name +2. Number of orders +3. Total revenue for this category +4. Average order value for this category +5. Total quantity of items sold + + +:::: + + + +### Analyze daily sales performance [aggregations-tutorial-daily-metrics] + +Let’s combine metrics to track daily trends: daily revenue, unique customers, and average basket size. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "daily_sales": { + "date_histogram": { + "field": "order_date", + "calendar_interval": "day", + "format": "yyyy-MM-dd" + }, + "aggs": { + "revenue": { <1> + "sum": { + "field": "taxful_total_price" + } + }, + "unique_customers": { <2> + "cardinality": { + "field": "customer_id" + } + }, + "avg_basket_size": { <3> + "avg": { + "field": "total_quantity" + } + } + } + } + } +} +``` + +1. Daily revenue +2. Uses the [`cardinality`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-cardinality-aggregation.html) aggregation to count unique customers per day +3. Average number of items per order + + +::::{dropdown} Example response +```console-result +{ + "took": 119, + "timed_out": false, + "_shards": { + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4675, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, + "aggregations": { + "daily_sales": { + "buckets": [ + { + "key_as_string": "2024-11-14", + "key": 1731542400000, + "doc_count": 146, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 10578.53125 + }, + "avg_basket_size": { + "value": 2.1780821917808217 + } + }, + { + "key_as_string": "2024-11-15", + "key": 1731628800000, + "doc_count": 153, + "unique_customers": { + "value": 44 + }, + "revenue": { + "value": 10448 + }, + "avg_basket_size": { + "value": 2.183006535947712 + } + }, + { + "key_as_string": "2024-11-16", + "key": 1731715200000, + "doc_count": 143, + "unique_customers": { + "value": 45 + }, + "revenue": { + "value": 10283.484375 + }, + "avg_basket_size": { + "value": 2.111888111888112 + } + }, + { + "key_as_string": "2024-11-17", + "key": 1731801600000, + "doc_count": 140, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 10145.5234375 + }, + "avg_basket_size": { + "value": 2.142857142857143 + } + }, + { + "key_as_string": "2024-11-18", + "key": 1731888000000, + "doc_count": 139, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 12012.609375 + }, + "avg_basket_size": { + "value": 2.158273381294964 + } + }, + { + "key_as_string": "2024-11-19", + "key": 1731974400000, + "doc_count": 157, + "unique_customers": { + "value": 43 + }, + "revenue": { + "value": 11009.45703125 + }, + "avg_basket_size": { + "value": 2.0955414012738856 + } + }, + { + "key_as_string": "2024-11-20", + "key": 1732060800000, + "doc_count": 145, + "unique_customers": { + "value": 44 + }, + "revenue": { + "value": 10720.59375 + }, + "avg_basket_size": { + "value": 2.179310344827586 + } + }, + { + "key_as_string": "2024-11-21", + "key": 1732147200000, + "doc_count": 152, + "unique_customers": { + "value": 43 + }, + "revenue": { + "value": 11185.3671875 + }, + "avg_basket_size": { + "value": 2.1710526315789473 + } + }, + { + "key_as_string": "2024-11-22", + "key": 1732233600000, + "doc_count": 163, + "unique_customers": { + "value": 44 + }, + "revenue": { + "value": 13560.140625 + }, + "avg_basket_size": { + "value": 2.2576687116564416 + } + }, + { + "key_as_string": "2024-11-23", + "key": 1732320000000, + "doc_count": 141, + "unique_customers": { + "value": 45 + }, + "revenue": { + "value": 9884.78125 + }, + "avg_basket_size": { + "value": 2.099290780141844 + } + }, + { + "key_as_string": "2024-11-24", + "key": 1732406400000, + "doc_count": 151, + "unique_customers": { + "value": 44 + }, + "revenue": { + "value": 11075.65625 + }, + "avg_basket_size": { + "value": 2.0927152317880795 + } + }, + { + "key_as_string": "2024-11-25", + "key": 1732492800000, + "doc_count": 143, + "unique_customers": { + "value": 41 + }, + "revenue": { + "value": 10323.8515625 + }, + "avg_basket_size": { + "value": 2.167832167832168 + } + }, + { + "key_as_string": "2024-11-26", + "key": 1732579200000, + "doc_count": 143, + "unique_customers": { + "value": 44 + }, + "revenue": { + "value": 10369.546875 + }, + "avg_basket_size": { + "value": 2.167832167832168 + } + }, + { + "key_as_string": "2024-11-27", + "key": 1732665600000, + "doc_count": 142, + "unique_customers": { + "value": 46 + }, + "revenue": { + "value": 11711.890625 + }, + "avg_basket_size": { + "value": 2.1971830985915495 + } + }, + { + "key_as_string": "2024-11-28", + "key": 1732752000000, + "doc_count": 161, + "unique_customers": { + "value": 43 + }, + "revenue": { + "value": 12612.6640625 + }, + "avg_basket_size": { + "value": 2.1180124223602483 + } + }, + { + "key_as_string": "2024-11-29", + "key": 1732838400000, + "doc_count": 144, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 10176.87890625 + }, + "avg_basket_size": { + "value": 2.0347222222222223 + } + }, + { + "key_as_string": "2024-11-30", + "key": 1732924800000, + "doc_count": 157, + "unique_customers": { + "value": 43 + }, + "revenue": { + "value": 11480.33203125 + }, + "avg_basket_size": { + "value": 2.159235668789809 + } + }, + { + "key_as_string": "2024-12-01", + "key": 1733011200000, + "doc_count": 158, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 11533.265625 + }, + "avg_basket_size": { + "value": 2.0822784810126582 + } + }, + { + "key_as_string": "2024-12-02", + "key": 1733097600000, + "doc_count": 144, + "unique_customers": { + "value": 43 + }, + "revenue": { + "value": 10499.8125 + }, + "avg_basket_size": { + "value": 2.201388888888889 + } + }, + { + "key_as_string": "2024-12-03", + "key": 1733184000000, + "doc_count": 151, + "unique_customers": { + "value": 40 + }, + "revenue": { + "value": 12111.6875 + }, + "avg_basket_size": { + "value": 2.172185430463576 + } + }, + { + "key_as_string": "2024-12-04", + "key": 1733270400000, + "doc_count": 145, + "unique_customers": { + "value": 40 + }, + "revenue": { + "value": 10530.765625 + }, + "avg_basket_size": { + "value": 2.0965517241379312 + } + }, + { + "key_as_string": "2024-12-05", + "key": 1733356800000, + "doc_count": 157, + "unique_customers": { + "value": 43 + }, + "revenue": { + "value": 11872.5625 + }, + "avg_basket_size": { + "value": 2.1464968152866244 + } + }, + { + "key_as_string": "2024-12-06", + "key": 1733443200000, + "doc_count": 158, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 12109.453125 + }, + "avg_basket_size": { + "value": 2.151898734177215 + } + }, + { + "key_as_string": "2024-12-07", + "key": 1733529600000, + "doc_count": 153, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 11057.40625 + }, + "avg_basket_size": { + "value": 2.111111111111111 + } + }, + { + "key_as_string": "2024-12-08", + "key": 1733616000000, + "doc_count": 165, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 13095.609375 + }, + "avg_basket_size": { + "value": 2.1818181818181817 + } + }, + { + "key_as_string": "2024-12-09", + "key": 1733702400000, + "doc_count": 153, + "unique_customers": { + "value": 41 + }, + "revenue": { + "value": 12574.015625 + }, + "avg_basket_size": { + "value": 2.2287581699346406 + } + }, + { + "key_as_string": "2024-12-10", + "key": 1733788800000, + "doc_count": 158, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 11188.1875 + }, + "avg_basket_size": { + "value": 2.151898734177215 + } + }, + { + "key_as_string": "2024-12-11", + "key": 1733875200000, + "doc_count": 160, + "unique_customers": { + "value": 42 + }, + "revenue": { + "value": 12117.65625 + }, + "avg_basket_size": { + "value": 2.20625 + } + }, + { + "key_as_string": "2024-12-12", + "key": 1733961600000, + "doc_count": 159, + "unique_customers": { + "value": 45 + }, + "revenue": { + "value": 11558.25 + }, + "avg_basket_size": { + "value": 2.1823899371069184 + } + }, + { + "key_as_string": "2024-12-13", + "key": 1734048000000, + "doc_count": 152, + "unique_customers": { + "value": 45 + }, + "revenue": { + "value": 11921.1171875 + }, + "avg_basket_size": { + "value": 2.289473684210526 + } + }, + { + "key_as_string": "2024-12-14", + "key": 1734134400000, + "doc_count": 142, + "unique_customers": { + "value": 45 + }, + "revenue": { + "value": 11135.03125 + }, + "avg_basket_size": { + "value": 2.183098591549296 + } + } + ] + } + } +} +``` + +:::: + + + +## Track trends and patterns [aggregations-tutorial-trends] + +You can use [pipeline aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline.html) on the results of other aggregations. Let’s analyze how metrics change over time. + + +### Smooth out daily fluctuations [aggregations-tutorial-moving-average] + +Moving averages help identify trends by reducing day-to-day noise in the data. Let’s observe sales trends more clearly by smoothing daily revenue variations, using the [Moving Function](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-movfn-aggregation.html) aggregation. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "daily_sales": { + "date_histogram": { + "field": "order_date", + "calendar_interval": "day" + }, + "aggs": { + "daily_revenue": { <1> + "sum": { + "field": "taxful_total_price" + } + }, + "smoothed_revenue": { <2> + "moving_fn": { <3> + "buckets_path": "daily_revenue", <4> + "window": 3, <5> + "script": "MovingFunctions.unweightedAvg(values)" <6> + } + } + } + } + } +} +``` + +1. Calculate daily revenue first. +2. Create a smoothed version of the daily revenue. +3. Use `moving_fn` for moving window calculations. +4. Reference the revenue from our date histogram. +5. Use a 3-day window — use different window sizes to see trends at different time scales. +6. Use the built-in unweighted average function in the `moving_fn` aggregation. + + +::::{dropdown} Example response +```console-result +{ + "took": 13, + "timed_out": false, + "_shards": { + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4675, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, + "aggregations": { + "daily_sales": { + "buckets": [ + { + "key_as_string": "2024-11-14T00:00:00.000Z", <1> + "key": 1731542400000, + "doc_count": 146, <2> + "daily_revenue": { <3> + "value": 10578.53125 + }, + "smoothed_revenue": { <4> + "value": null + } + }, + { + "key_as_string": "2024-11-15T00:00:00.000Z", + "key": 1731628800000, + "doc_count": 153, + "daily_revenue": { + "value": 10448 + }, + "smoothed_revenue": { <5> + "value": 10578.53125 + } + }, + { + "key_as_string": "2024-11-16T00:00:00.000Z", + "key": 1731715200000, + "doc_count": 143, + "daily_revenue": { + "value": 10283.484375 + }, + "smoothed_revenue": { + "value": 10513.265625 + } + }, + { + "key_as_string": "2024-11-17T00:00:00.000Z", + "key": 1731801600000, + "doc_count": 140, + "daily_revenue": { + "value": 10145.5234375 + }, + "smoothed_revenue": { + "value": 10436.671875 + } + }, + { + "key_as_string": "2024-11-18T00:00:00.000Z", + "key": 1731888000000, + "doc_count": 139, + "daily_revenue": { + "value": 12012.609375 + }, + "smoothed_revenue": { + "value": 10292.3359375 + } + }, + { + "key_as_string": "2024-11-19T00:00:00.000Z", + "key": 1731974400000, + "doc_count": 157, + "daily_revenue": { + "value": 11009.45703125 + }, + "smoothed_revenue": { + "value": 10813.872395833334 + } + }, + { + "key_as_string": "2024-11-20T00:00:00.000Z", + "key": 1732060800000, + "doc_count": 145, + "daily_revenue": { + "value": 10720.59375 + }, + "smoothed_revenue": { + "value": 11055.86328125 + } + }, + { + "key_as_string": "2024-11-21T00:00:00.000Z", + "key": 1732147200000, + "doc_count": 152, + "daily_revenue": { + "value": 11185.3671875 + }, + "smoothed_revenue": { + "value": 11247.553385416666 + } + }, + { + "key_as_string": "2024-11-22T00:00:00.000Z", + "key": 1732233600000, + "doc_count": 163, + "daily_revenue": { + "value": 13560.140625 + }, + "smoothed_revenue": { + "value": 10971.805989583334 + } + }, + { + "key_as_string": "2024-11-23T00:00:00.000Z", + "key": 1732320000000, + "doc_count": 141, + "daily_revenue": { + "value": 9884.78125 + }, + "smoothed_revenue": { + "value": 11822.033854166666 + } + }, + { + "key_as_string": "2024-11-24T00:00:00.000Z", + "key": 1732406400000, + "doc_count": 151, + "daily_revenue": { + "value": 11075.65625 + }, + "smoothed_revenue": { + "value": 11543.4296875 + } + }, + { + "key_as_string": "2024-11-25T00:00:00.000Z", + "key": 1732492800000, + "doc_count": 143, + "daily_revenue": { + "value": 10323.8515625 + }, + "smoothed_revenue": { + "value": 11506.859375 + } + }, + { + "key_as_string": "2024-11-26T00:00:00.000Z", + "key": 1732579200000, + "doc_count": 143, + "daily_revenue": { + "value": 10369.546875 + }, + "smoothed_revenue": { + "value": 10428.096354166666 + } + }, + { + "key_as_string": "2024-11-27T00:00:00.000Z", + "key": 1732665600000, + "doc_count": 142, + "daily_revenue": { + "value": 11711.890625 + }, + "smoothed_revenue": { + "value": 10589.684895833334 + } + }, + { + "key_as_string": "2024-11-28T00:00:00.000Z", + "key": 1732752000000, + "doc_count": 161, + "daily_revenue": { + "value": 12612.6640625 + }, + "smoothed_revenue": { + "value": 10801.763020833334 + } + }, + { + "key_as_string": "2024-11-29T00:00:00.000Z", + "key": 1732838400000, + "doc_count": 144, + "daily_revenue": { + "value": 10176.87890625 + }, + "smoothed_revenue": { + "value": 11564.700520833334 + } + }, + { + "key_as_string": "2024-11-30T00:00:00.000Z", + "key": 1732924800000, + "doc_count": 157, + "daily_revenue": { + "value": 11480.33203125 + }, + "smoothed_revenue": { + "value": 11500.477864583334 + } + }, + { + "key_as_string": "2024-12-01T00:00:00.000Z", + "key": 1733011200000, + "doc_count": 158, + "daily_revenue": { + "value": 11533.265625 + }, + "smoothed_revenue": { + "value": 11423.291666666666 + } + }, + { + "key_as_string": "2024-12-02T00:00:00.000Z", + "key": 1733097600000, + "doc_count": 144, + "daily_revenue": { + "value": 10499.8125 + }, + "smoothed_revenue": { + "value": 11063.4921875 + } + }, + { + "key_as_string": "2024-12-03T00:00:00.000Z", + "key": 1733184000000, + "doc_count": 151, + "daily_revenue": { + "value": 12111.6875 + }, + "smoothed_revenue": { + "value": 11171.13671875 + } + }, + { + "key_as_string": "2024-12-04T00:00:00.000Z", + "key": 1733270400000, + "doc_count": 145, + "daily_revenue": { + "value": 10530.765625 + }, + "smoothed_revenue": { + "value": 11381.588541666666 + } + }, + { + "key_as_string": "2024-12-05T00:00:00.000Z", + "key": 1733356800000, + "doc_count": 157, + "daily_revenue": { + "value": 11872.5625 + }, + "smoothed_revenue": { + "value": 11047.421875 + } + }, + { + "key_as_string": "2024-12-06T00:00:00.000Z", + "key": 1733443200000, + "doc_count": 158, + "daily_revenue": { + "value": 12109.453125 + }, + "smoothed_revenue": { + "value": 11505.005208333334 + } + }, + { + "key_as_string": "2024-12-07T00:00:00.000Z", + "key": 1733529600000, + "doc_count": 153, + "daily_revenue": { + "value": 11057.40625 + }, + "smoothed_revenue": { + "value": 11504.260416666666 + } + }, + { + "key_as_string": "2024-12-08T00:00:00.000Z", + "key": 1733616000000, + "doc_count": 165, + "daily_revenue": { + "value": 13095.609375 + }, + "smoothed_revenue": { + "value": 11679.807291666666 + } + }, + { + "key_as_string": "2024-12-09T00:00:00.000Z", + "key": 1733702400000, + "doc_count": 153, + "daily_revenue": { + "value": 12574.015625 + }, + "smoothed_revenue": { + "value": 12087.489583333334 + } + }, + { + "key_as_string": "2024-12-10T00:00:00.000Z", + "key": 1733788800000, + "doc_count": 158, + "daily_revenue": { + "value": 11188.1875 + }, + "smoothed_revenue": { + "value": 12242.34375 + } + }, + { + "key_as_string": "2024-12-11T00:00:00.000Z", + "key": 1733875200000, + "doc_count": 160, + "daily_revenue": { + "value": 12117.65625 + }, + "smoothed_revenue": { + "value": 12285.9375 + } + }, + { + "key_as_string": "2024-12-12T00:00:00.000Z", + "key": 1733961600000, + "doc_count": 159, + "daily_revenue": { + "value": 11558.25 + }, + "smoothed_revenue": { + "value": 11959.953125 + } + }, + { + "key_as_string": "2024-12-13T00:00:00.000Z", + "key": 1734048000000, + "doc_count": 152, + "daily_revenue": { + "value": 11921.1171875 + }, + "smoothed_revenue": { + "value": 11621.364583333334 + } + }, + { + "key_as_string": "2024-12-14T00:00:00.000Z", + "key": 1734134400000, + "doc_count": 142, + "daily_revenue": { + "value": 11135.03125 + }, + "smoothed_revenue": { + "value": 11865.674479166666 + } + } + ] + } + } +} +``` + +1. Date of the bucket is in default ISO format because we didn’t specify a format +2. Number of orders for this day +3. Raw daily revenue before smoothing +4. First day has no smoothed value as it needs previous days for the calculation +5. Moving average starts from second day, using a 3-day window + + +:::: + + +::::{tip} +Notice how the smoothed values lag behind the actual values - this is because they need previous days' data to calculate. The first day will always be null when using moving averages. + +:::: + + + +### Track running totals [aggregations-tutorial-cumulative] + +Track running totals over time using the [`cumulative_sum`](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-cumulative-sum-aggregation.html) aggregation. + +```console +GET kibana_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "daily_sales": { + "date_histogram": { + "field": "order_date", + "calendar_interval": "day" + }, + "aggs": { + "revenue": { + "sum": { + "field": "taxful_total_price" + } + }, + "cumulative_revenue": { <1> + "cumulative_sum": { <2> + "buckets_path": "revenue" <3> + } + } + } + } + } +} +``` + +1. Name for our running total +2. `cumulative_sum` adds up values across buckets +3. Reference the revenue we want to accumulate + + +::::{dropdown} Example response +```console-result +{ + "took": 4, + "timed_out": false, + "_shards": { + "total": 5, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4675, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, + "aggregations": { + "daily_sales": { <1> + "buckets": [ <2> + { + "key_as_string": "2024-11-14T00:00:00.000Z", <3> + "key": 1731542400000, + "doc_count": 146, + "revenue": { <4> + "value": 10578.53125 + }, + "cumulative_revenue": { <5> + "value": 10578.53125 + } + }, + { + "key_as_string": "2024-11-15T00:00:00.000Z", + "key": 1731628800000, + "doc_count": 153, + "revenue": { + "value": 10448 + }, + "cumulative_revenue": { + "value": 21026.53125 + } + }, + { + "key_as_string": "2024-11-16T00:00:00.000Z", + "key": 1731715200000, + "doc_count": 143, + "revenue": { + "value": 10283.484375 + }, + "cumulative_revenue": { + "value": 31310.015625 + } + }, + { + "key_as_string": "2024-11-17T00:00:00.000Z", + "key": 1731801600000, + "doc_count": 140, + "revenue": { + "value": 10145.5234375 + }, + "cumulative_revenue": { + "value": 41455.5390625 + } + }, + { + "key_as_string": "2024-11-18T00:00:00.000Z", + "key": 1731888000000, + "doc_count": 139, + "revenue": { + "value": 12012.609375 + }, + "cumulative_revenue": { + "value": 53468.1484375 + } + }, + { + "key_as_string": "2024-11-19T00:00:00.000Z", + "key": 1731974400000, + "doc_count": 157, + "revenue": { + "value": 11009.45703125 + }, + "cumulative_revenue": { + "value": 64477.60546875 + } + }, + { + "key_as_string": "2024-11-20T00:00:00.000Z", + "key": 1732060800000, + "doc_count": 145, + "revenue": { + "value": 10720.59375 + }, + "cumulative_revenue": { + "value": 75198.19921875 + } + }, + { + "key_as_string": "2024-11-21T00:00:00.000Z", + "key": 1732147200000, + "doc_count": 152, + "revenue": { + "value": 11185.3671875 + }, + "cumulative_revenue": { + "value": 86383.56640625 + } + }, + { + "key_as_string": "2024-11-22T00:00:00.000Z", + "key": 1732233600000, + "doc_count": 163, + "revenue": { + "value": 13560.140625 + }, + "cumulative_revenue": { + "value": 99943.70703125 + } + }, + { + "key_as_string": "2024-11-23T00:00:00.000Z", + "key": 1732320000000, + "doc_count": 141, + "revenue": { + "value": 9884.78125 + }, + "cumulative_revenue": { + "value": 109828.48828125 + } + }, + { + "key_as_string": "2024-11-24T00:00:00.000Z", + "key": 1732406400000, + "doc_count": 151, + "revenue": { + "value": 11075.65625 + }, + "cumulative_revenue": { + "value": 120904.14453125 + } + }, + { + "key_as_string": "2024-11-25T00:00:00.000Z", + "key": 1732492800000, + "doc_count": 143, + "revenue": { + "value": 10323.8515625 + }, + "cumulative_revenue": { + "value": 131227.99609375 + } + }, + { + "key_as_string": "2024-11-26T00:00:00.000Z", + "key": 1732579200000, + "doc_count": 143, + "revenue": { + "value": 10369.546875 + }, + "cumulative_revenue": { + "value": 141597.54296875 + } + }, + { + "key_as_string": "2024-11-27T00:00:00.000Z", + "key": 1732665600000, + "doc_count": 142, + "revenue": { + "value": 11711.890625 + }, + "cumulative_revenue": { + "value": 153309.43359375 + } + }, + { + "key_as_string": "2024-11-28T00:00:00.000Z", + "key": 1732752000000, + "doc_count": 161, + "revenue": { + "value": 12612.6640625 + }, + "cumulative_revenue": { + "value": 165922.09765625 + } + }, + { + "key_as_string": "2024-11-29T00:00:00.000Z", + "key": 1732838400000, + "doc_count": 144, + "revenue": { + "value": 10176.87890625 + }, + "cumulative_revenue": { + "value": 176098.9765625 + } + }, + { + "key_as_string": "2024-11-30T00:00:00.000Z", + "key": 1732924800000, + "doc_count": 157, + "revenue": { + "value": 11480.33203125 + }, + "cumulative_revenue": { + "value": 187579.30859375 + } + }, + { + "key_as_string": "2024-12-01T00:00:00.000Z", + "key": 1733011200000, + "doc_count": 158, + "revenue": { + "value": 11533.265625 + }, + "cumulative_revenue": { + "value": 199112.57421875 + } + }, + { + "key_as_string": "2024-12-02T00:00:00.000Z", + "key": 1733097600000, + "doc_count": 144, + "revenue": { + "value": 10499.8125 + }, + "cumulative_revenue": { + "value": 209612.38671875 + } + }, + { + "key_as_string": "2024-12-03T00:00:00.000Z", + "key": 1733184000000, + "doc_count": 151, + "revenue": { + "value": 12111.6875 + }, + "cumulative_revenue": { + "value": 221724.07421875 + } + }, + { + "key_as_string": "2024-12-04T00:00:00.000Z", + "key": 1733270400000, + "doc_count": 145, + "revenue": { + "value": 10530.765625 + }, + "cumulative_revenue": { + "value": 232254.83984375 + } + }, + { + "key_as_string": "2024-12-05T00:00:00.000Z", + "key": 1733356800000, + "doc_count": 157, + "revenue": { + "value": 11872.5625 + }, + "cumulative_revenue": { + "value": 244127.40234375 + } + }, + { + "key_as_string": "2024-12-06T00:00:00.000Z", + "key": 1733443200000, + "doc_count": 158, + "revenue": { + "value": 12109.453125 + }, + "cumulative_revenue": { + "value": 256236.85546875 + } + }, + { + "key_as_string": "2024-12-07T00:00:00.000Z", + "key": 1733529600000, + "doc_count": 153, + "revenue": { + "value": 11057.40625 + }, + "cumulative_revenue": { + "value": 267294.26171875 + } + }, + { + "key_as_string": "2024-12-08T00:00:00.000Z", + "key": 1733616000000, + "doc_count": 165, + "revenue": { + "value": 13095.609375 + }, + "cumulative_revenue": { + "value": 280389.87109375 + } + }, + { + "key_as_string": "2024-12-09T00:00:00.000Z", + "key": 1733702400000, + "doc_count": 153, + "revenue": { + "value": 12574.015625 + }, + "cumulative_revenue": { + "value": 292963.88671875 + } + }, + { + "key_as_string": "2024-12-10T00:00:00.000Z", + "key": 1733788800000, + "doc_count": 158, + "revenue": { + "value": 11188.1875 + }, + "cumulative_revenue": { + "value": 304152.07421875 + } + }, + { + "key_as_string": "2024-12-11T00:00:00.000Z", + "key": 1733875200000, + "doc_count": 160, + "revenue": { + "value": 12117.65625 + }, + "cumulative_revenue": { + "value": 316269.73046875 + } + }, + { + "key_as_string": "2024-12-12T00:00:00.000Z", + "key": 1733961600000, + "doc_count": 159, + "revenue": { + "value": 11558.25 + }, + "cumulative_revenue": { + "value": 327827.98046875 + } + }, + { + "key_as_string": "2024-12-13T00:00:00.000Z", + "key": 1734048000000, + "doc_count": 152, + "revenue": { + "value": 11921.1171875 + }, + "cumulative_revenue": { + "value": 339749.09765625 + } + }, + { + "key_as_string": "2024-12-14T00:00:00.000Z", + "key": 1734134400000, + "doc_count": 142, + "revenue": { + "value": 11135.03125 + }, + "cumulative_revenue": { + "value": 350884.12890625 + } + } + ] + } + } +} +``` + +1. `daily_sales`: Results from our daily sales date histogram +2. `buckets`: Array of time-based buckets +3. `key_as_string`: Date for this bucket (in ISO format since no format specified) +4. `revenue`: Daily revenue for this date +5. `cumulative_revenue`: Running total of revenue up to this date + + +:::: + + + +## Next steps [aggregations-tutorial-next-steps] + +Refer to the [aggregations reference](../aggregations.md) for more details on all available aggregation types. diff --git a/explore-analyze/ai-assistant.md b/explore-analyze/ai-assistant.md new file mode 100644 index 000000000..402639cd7 --- /dev/null +++ b/explore-analyze/ai-assistant.md @@ -0,0 +1,26 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/search-ai-assistant.html + - https://www.elastic.co/guide/en/observability/current/obs-ai-assistant.html + - https://www.elastic.co/guide/en/serverless/current/security-ai-for-security.html + - https://www.elastic.co/guide/en/serverless/current/observability-ai-assistant.html + - https://www.elastic.co/guide/en/serverless/current/security-ai-assistant.html + - https://www.elastic.co/guide/en/serverless/current/ai-assistant-knowledge-base.html +--- + +# AI assistant + +% What needs to be done: Write from scratch + +% Scope notes: explain concept and link out to specific docs & config + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/search-ai-assistant.md +% - [ ] ./raw-migrated-files/observability-docs/observability/obs-ai-assistant.md +% - [ ] ./raw-migrated-files/docs-content/serverless/security-ai-for-security.md +% - [ ] ./raw-migrated-files/docs-content/serverless/observability-ai-assistant.md +% - [ ] ./raw-migrated-files/docs-content/serverless/security-ai-assistant.md +% - [ ] ./raw-migrated-files/docs-content/serverless/ai-assistant-knowledge-base.md + +$$$token-limits$$$ \ No newline at end of file diff --git a/explore-analyze/alerts.md b/explore-analyze/alerts.md new file mode 100644 index 000000000..1ea124ca8 --- /dev/null +++ b/explore-analyze/alerts.md @@ -0,0 +1,18 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html#alerting-concepts-differences + - https://www.elastic.co/guide/en/serverless/current/project-settings-alerts.html +--- + +# Alerts and cases + +% What needs to be done: Write from scratch + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/alerting-getting-started.md +% - [ ] ./raw-migrated-files/docs-content/serverless/project-settings-alerts.md + +$$$alerting-concepts-actions$$$ + +$$$alerting-concepts-conditions$$$ \ No newline at end of file diff --git a/explore-analyze/alerts/cases.md b/explore-analyze/alerts/cases.md new file mode 100644 index 000000000..e3f95e624 --- /dev/null +++ b/explore-analyze/alerts/cases.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/cases.html +--- + +# Cases [cases] + +Cases are used to open and track issues directly in {{kib}}. You can add assignees and tags to your cases, set their severity and status, and add alerts, comments, and visualizations. You can create cases automatically when alerts occur or send cases to external incident management systems by configuring connectors. + +You can also optionally add custom fields and case templates. [preview] + +:::{image} ../../images/kibana-cases-list.png +:alt: Cases page +:class: screenshot +::: + +::::{note} +If you create cases in the {{observability}} or {{security-app}}, they are not visible in **{{stack-manage-app}}**. Likewise, the cases you create in **{{stack-manage-app}}** are not visible in the {{observability}} or {{security-app}}. You also cannot attach alerts from the {{observability}} or {{security-app}} to cases in **{{stack-manage-app}}**. +:::: + + +* [Configure access to cases](cases/setup-cases.md) +* [Open and manage cases](cases/manage-cases.md) +* [Configure case settings](cases/manage-cases-settings.md) + + + + diff --git a/explore-analyze/alerts/cases/manage-cases-settings.md b/explore-analyze/alerts/cases/manage-cases-settings.md new file mode 100644 index 000000000..975643e58 --- /dev/null +++ b/explore-analyze/alerts/cases/manage-cases-settings.md @@ -0,0 +1,99 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/manage-cases-settings.html +--- + +# Configure case settings [manage-cases-settings] + +To change case closure options and add custom fields, templates, and connectors for external incident management systems, go to **{{stack-manage-app}} > Cases** and click **Settings**. + +To perform these tasks, you must have [full access](setup-cases.md) to the appropriate case and connector features in {{kib}}. + +:::{image} ../../../images/kibana-cases-settings.png +:alt: View case settings +:class: screenshot +::: + +## Case closures [case-closures] + +If you close cases in your external incident management system, they will remain open in **Cases** until you close them manually. + +To change whether cases are automatically closed after they are sent to an external system, update the case closure options. + + +## External incident management systems [case-connectors] + +You can add connectors to cases to push information to these external incident management systems: + +* {ibm-r} +* {jira} +* {sn-itsm} +* {sn-sir} +* {swimlane} +* {hive} +* {webhook-cm} + +::::{note} +To create connectors and send cases to external systems, you must have the appropriate {{kib}} feature privileges. Refer to [Configure access to cases](setup-cases.md). +:::: + + +You can create connectors in **{{stack-manage-app}} > {{connectors-ui}}**, as described in [*Connectors*](../../../deploy-manage/manage-connectors.md). Alternatively, you can create them in **{{stack-manage-app}} > Cases > Settings**: + +1. From the **Incident management system** list, select **Add new connector**. +2. Select an external incident management system. +3. Enter your required settings. Refer to [{{ibm-r}}](https://www.elastic.co/guide/en/kibana/current/resilient-action-type.html), [Jira](https://www.elastic.co/guide/en/kibana/current/jira-action-type.html), [{{sn-itsm}}](https://www.elastic.co/guide/en/kibana/current/servicenow-action-type.html), [{{sn-sir}}](https://www.elastic.co/guide/en/kibana/current/servicenow-sir-action-type.html), [Swimlane](https://www.elastic.co/guide/en/kibana/current/swimlane-action-type.html), [{{hive}}](https://www.elastic.co/guide/en/kibana/current/thehive-action-type.html), or [{{webhook-cm}}](https://www.elastic.co/guide/en/kibana/current/cases-webhook-action-type.html) for connector configuration details. + +You can subsequently choose the connector when you create cases and use it in case templates. To change the default connector for new cases, select the connector from the **Incident management system** list. + +To update a connector, click **Update ** and edit the connector fields as required. + + +## Custom fields [case-custom-fields] + +You can add optional and required fields for customized case collaboration. [8.15.0] + +To create a custom field: + +1. In the **Custom fields** section, click **Add field**. + + :::{image} ../../../images/kibana-cases-custom-fields-add.png + :alt: Add a custom field in case settings + :class: screenshot + ::: + +2. You must provide a field label and type (text or toggle). You can optionally designate it as a required field and provide a default value. + +When you create a custom field, it’s added to all new and existing cases. Existing cases have null values for new text fields until you set them in each case. + +You can subsequently remove or edit custom fields on the **Settings** page. + + +## Templates [case-templates] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +You can make the case creation process faster and more consistent by adding templates. A template defines values for one or all of the case fields (such as severity, tags, description, and title) as well as any custom fields. + +To create a template: + +1. In the **Templates** section, click **Add template**. + + :::{image} ../../../images/kibana-cases-templates-add.png + :alt: Add a template in case settings + :class: screenshot + ::: + +2. You must provide a template name and case severity. You can optionally add template tags and a description, values for each case field, and a case connector. + +When users create cases, they can optionally select a template and use its values or override them. + +::::{note} +If you update or delete templates, existing cases are unaffected. +:::: + + + diff --git a/explore-analyze/alerts/cases/manage-cases.md b/explore-analyze/alerts/cases/manage-cases.md new file mode 100644 index 000000000..9e0aa4655 --- /dev/null +++ b/explore-analyze/alerts/cases/manage-cases.md @@ -0,0 +1,145 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/manage-cases.html +--- + +# Open and manage cases [manage-cases] + +To perform these tasks, you must have [full access](setup-cases.md) to the appropriate case features in {{kib}}. + +## Open a new case [open-case] + +Open a new case to keep track of issues and share their details with colleagues. + +1. Go to **Management > {{stack-manage-app}} > Cases**, then click **Create case**. + + :::{image} ../../../images/kibana-cases-create.png + :alt: Create a case in {stack-manage-app} + :class: screenshot + ::: + +2. If you defined [templates](manage-cases-settings.md#case-templates), you can optionally select one to use its default field values. [preview] +3. Give the case a name, severity, and description. + + ::::{tip} + In the `Description` area, you can use [Markdown](https://www.markdownguide.org/cheat-sheet) syntax to create formatted text. + :::: + +4. Optionally, add a category, assignees, and tags. You can add users only if they meet the necessary [prerequisites](setup-cases.md). +5. If you defined any [custom fields](manage-cases-settings.md#case-custom-fields), they appear in the **Additional fields** section. [8.15.0] +6. For the **External incident management system**, select a connector. For more information, refer to [External incident management systems](manage-cases-settings.md#case-connectors). +7. After you’ve completed all of the required fields, click **Create case**. + +[preview] Alternatively, you can configure your rules to automatically create cases by using [case actions](https://www.elastic.co/guide/en/kibana/current/cases-action-type.html). By default, the rule adds all of the alerts within a specified time window to a single case. You can optionally choose a field to group the alerts and create separate cases for each group. You can also choose whether you want the rule to reopen cases or open new ones when the time window elapses. + + +## Add email notifications [add-case-notifications] + +You can configure email notifications that occur when users are assigned to cases. + +For hosted {{kib}} on {{ess}}: + +1. Add the email domains to the [notifications domain allowlist](../kibana.md). + + You do not need to take any more steps to configure an email connector or update {{kib}} user settings, since the preconfigured Elastic-Cloud-SMTP connector is used by default. + + +For self-managed {{kib}}: + +1. Create a preconfigured email connector. + + ::::{note} + At this time, email notifications support only preconfigured connectors, which are defined in the `kibana.yml` file. For examples, refer to [Email connectors](https://www.elastic.co/guide/en/kibana/current/pre-configured-connectors.html#preconfigured-email-configuration) and [Configure email accounts for well-known services](https://www.elastic.co/guide/en/kibana/current/email-action-type.html#configuring-email). + :::: + +2. Set the `notifications.connectors.default.email` {{kib}} setting in kibana.yml to the name of your email connector. + +```js +notifications.connectors.default.email: ‘mail-dev’ + +xpack.actions.preconfigured: + mail-dev: + name: preconfigured-email-notification-maildev + actionTypeId: .email + config: + service: other + from: from address + host: host name + port: port number + secure: true/false + hasAuth: true/false +``` + +1. If you want the email notifications to contain links back to the case, you must configure the [server.publicBaseUrl](../../../deploy-manage/deploy/self-managed/configure.md#server-publicBaseUrl) setting. + +When you subsequently add assignees to cases, they receive an email. + + +## Add files [add-case-files] + +After you create a case, you can upload and manage files on the **Files** tab: + +:::{image} ../../../images/kibana-cases-files.png +:alt: A list of files attached to a case +:class: screenshot +::: + +The acceptable file types and sizes are affected by your [case settings](../../../deploy-manage/deploy/self-managed/configure.md). + +To download or delete the file or copy the file hash to your clipboard, open the action menu (…). The available hash functions are MD5, SHA-1, and SHA-256. + +When you upload a file, a comment is added to the case activity log. To view images, click their name in the activity or file list. + +::::{note} +Uploaded files are also accessible in **{{stack-manage-app}} > Files**. When you export cases as [saved objects](../../find-and-organize/saved-objects.md), the case files are not exported. + +:::: + + + +## Add visualizations [add-case-visualization] + +You can also optionally add visualizations. For example, you can portray event and alert data through charts and graphs. + +:::{image} ../../../images/kibana-cases-visualization.png +:alt: Adding a visualization as a comment within a case +:class: screenshot +::: + +To add a visualization to a comment within your case: + +1. Click the **Visualization** button. The **Add visualization** dialog appears. +2. Select an existing visualization from your Visualize Library or create a new visualization. + + ::::{important} + Set an absolute time range for your visualization. This ensures your visualization doesn’t change over time after you save it to your case and provides important context for viewers. + :::: + +3. After you’ve finished creating your visualization, click **Save and return** to go back to your case. +4. Click **Preview** to see how the visualization will appear in the case comment. +5. Click **Add Comment** to add the visualization to your case. + +Alternatively, while viewing a [dashboard](../../dashboards.md) you can open a panel’s menu then click **More > Add to existing case** or **More > Add to new case**. + +After a visualization has been added to a case, you can modify or interact with it by clicking the **Open Visualization** option in the case’s comment menu. + + +## Manage cases [manage-case] + +In **Management > {{stack-manage-app}} > Cases**, you can search cases and filter them by attributes such as assignees, categories, severity, status, and tags. You can also select multiple cases and use bulk actions to delete cases or change their attributes. + +To view a case, click on its name. You can then: + +* Add a new comment. +* Edit existing comments and the description. +* Add or remove assignees. +* Add a connector. +* Send updates to external systems (if external connections are configured). +* Edit the category and tags. +* Refresh the case to retrieve the latest updates. +* Change the status. +* Change the severity. +* Close or delete the case. +* Reopen a closed case. + + diff --git a/explore-analyze/alerts/cases/setup-cases.md b/explore-analyze/alerts/cases/setup-cases.md new file mode 100644 index 000000000..2380ea30a --- /dev/null +++ b/explore-analyze/alerts/cases/setup-cases.md @@ -0,0 +1,67 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/setup-cases.html +--- + +# Configure access to cases [setup-cases] + +To access cases in **{{stack-manage-app}}**, you must have the appropriate {{kib}} privileges: + + +## Give full access to manage cases and settings [_give_full_access_to_manage_cases_and_settings] + +**{{kib}} privileges** + +* `All` for the **Cases** feature under **Management**. +* `All` for the **{{connectors-feature}}** feature under **Management**. + +::::{note} +The **{{connectors-feature}}** feature privilege is required to create, add, delete, and modify case connectors and to send updates to external systems. + +By default, `All` for the **Cases** feature includes authority to delete cases and comments, edit case settings, add case comments and attachments, and re-open cases unless you customize the sub-feature privileges. + +:::: + + + +## Give assignee access to cases [_give_assignee_access_to_cases] + +**{{kib}} privileges** + +* `All` for the **Cases** feature under **Management**. + +::::{note} +Before a user can be assigned to a case, they must log into {{kib}} at least once, which creates a user profile. + +This privilege is also required to add [case actions](https://www.elastic.co/guide/en/kibana/current/cases-action-type.html) to rules. + +:::: + + + +## Give view-only access to cases [_give_view_only_access_to_cases] + +**{{kib}} privileges** + +* `Read` for the **Cases** feature under **Management**. + +::::{note} +You can customize sub-feature privileges for deleting cases and comments, editing case settings, adding case comments and attachments, and re-opening cases. +:::: + + + +## Revoke all access to cases [_revoke_all_access_to_cases] + +**{{kib}} privileges** + +`None` for the **Cases** feature under **Management**. + + +## More details [_more_details_2] + +For more details, refer to [{{kib}} privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). + +::::{note} +If you are using an on-premises {{kib}} deployment and you want the email notifications and the external incident management systems to contain links back to {{kib}}, you must configure the [`server.publicBaseUrl`](../../../deploy-manage/deploy/self-managed/configure.md#server-publicBaseUrl) setting. +:::: diff --git a/explore-analyze/alerts/kibana.md b/explore-analyze/alerts/kibana.md new file mode 100644 index 000000000..4f9691b29 --- /dev/null +++ b/explore-analyze/alerts/kibana.md @@ -0,0 +1,30 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html + - https://www.elastic.co/guide/en/serverless/current/rules.html + - https://www.elastic.co/guide/en/cloud/current/ec-organizations-notifications-domain-allowlist.html +--- + +# Kibana alerts + +% What needs to be done: Align serverless/stateful + +% Scope notes: connection to kibana connectors reference prod considerations + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/alerting-getting-started.md +% - [ ] ./raw-migrated-files/docs-content/serverless/rules.md +% - [ ] ./raw-migrated-files/cloud/cloud/ec-organizations-notifications-domain-allowlist.md + +% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): + +$$$alerting-getting-started$$$ + +$$$rules-alerts$$$ + +$$$alerting-concepts-conditions$$$ + +$$$alerting-concepts-scheduling$$$ + +$$$alerting-concepts-actions$$$ diff --git a/explore-analyze/alerts/kibana/alerting-common-issues.md b/explore-analyze/alerts/kibana/alerting-common-issues.md new file mode 100644 index 000000000..c492eabb9 --- /dev/null +++ b/explore-analyze/alerts/kibana/alerting-common-issues.md @@ -0,0 +1,268 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/alerting-common-issues.html +--- + +# Common Issues [alerting-common-issues] + +This page describes how to resolve common problems you might encounter with Alerting. + + +## Rules with small check intervals run late [rules-small-check-interval-run-late] + +**Problem** + +Rules with a small check interval, such as every two seconds, run later than scheduled. + +**Solution** + +Rules run as background tasks at a cadence defined by their **check interval**. When a Rule **check interval** is smaller than the Task Manager [`poll_interval`](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings), the rule will run late. + +Either tweak the [{{kib}} Task Manager settings](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html#task-manager-settings) or increase the **check interval** of the rules in question. + +For more details, see [Tasks with small schedule intervals run late](../../../troubleshoot/kibana/task-manager.md#task-manager-health-scheduled-tasks-small-schedule-interval-run-late). + + +## Rules with the inconsistent cadence [scheduled-rules-run-late] + +**Problem** + +Scheduled rules run at an inconsistent cadence, often running late. + +Actions run long after the status of a rule changes, sending a notification of the change too late. + +**Solution** + +Rules and actions run as background tasks by each {{kib}} instance at a default rate of ten tasks every three seconds. When diagnosing issues related to alerting, focus on the tasks that begin with `alerting:` and `actions:`. + +Alerting tasks always begin with `alerting:`. For example, the `alerting:.index-threshold` tasks back the [index threshold stack rule](rule-type-index-threshold.md). Action tasks always begin with `actions:`. For example, the `actions:.index` tasks back the [index action](https://www.elastic.co/guide/en/kibana/current/index-action-type.html). + +For more details on monitoring and diagnosing tasks in Task Manager, refer to [Health monitoring](../../../deploy-manage/monitor/kibana-task-manager-health-monitoring.md). + + +## Connectors have TLS errors when running actions [connector-tls-settings] + +**Problem** + +A connector gets a TLS socket error when connecting to the server to run an action. + +**Solution** + +Configuration options are available to specialize connections to TLS servers, including ignoring server certificate validation and providing certificate authority data to verify servers using custom certificates. For more details, see [Action settings](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#action-settings). + + +## Rules take a long time to run [rules-long-run-time] + +**Problem** + +Rules are taking a long time to run and are impacting the overall health of your deployment. + +::::{important} +By default, only users with a `superuser` role can query the [preview] {{kib}} event log because it is a system index. To enable additional users to run this query, assign `read` privileges to the `.kibana-event-log*` index. + +:::: + + +**Solution** + +By default, rules have a `5m` timeout. Rules that run longer than this timeout are automatically canceled to prevent them from consuming too much of {{kib}}'s resources. Alerts and actions that may have been scheduled before the rule timed out are discarded. When a rule times out, you will see this error in the {{kib}} logs: + +```sh +[2022-03-28T13:14:04.062-04:00][WARN ][plugins.taskManager] Cancelling task alerting:.index-threshold "a6ea0070-aec0-11ec-9985-dd576a3fe205" as it expired at 2022-03-28T17:14:03.980Z after running for 05m 10s (with timeout set at 5m). +``` + +and in the [details page](create-manage-rules.md#rule-details): + +:::{image} ../../../images/kibana-rule-details-timeout-error.png +:alt: Rule details page with timeout error +:class: screenshot +::: + +If you want your rules to run longer, update the `xpack.alerting.rules.run.timeout` configuration in your [Alerting settings](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#alert-settings). You can also target a specific rule type by using `xpack.alerting.rules.run.ruleTypeOverrides`. + +Rules that consistently run longer than their [check interval](create-manage-rules.md#create-edit-rules) may produce unexpected results. If the average run duration, visible on the [details page](create-manage-rules.md#rule-details), is greater than the check interval, consider increasing the check interval. + +To get all long-running rules, you can query for a list of rule ids, bucketed by their run times: + +```console +GET /.kibana-event-log*/_search +{ + "size": 0, + "query": { + "bool": { + "filter": [ + { + "range": { + "@timestamp": { + "gte": "now-1d", <1> + "lte": "now" + } + } + }, + { + "term": { + "event.action": { + "value": "execute" + } + } + }, + { + "term": { + "event.provider": { + "value": "alerting" <2> + } + } + } + ] + } + }, + "runtime_mappings": { <3> + "event.duration_in_seconds": { + "type": "double", + "script": { + "source": "emit(doc['event.duration'].value / 1E9)" + } + } + }, + "aggs": { + "ruleIdsByExecutionDuration": { + "histogram": { + "field": "event.duration_in_seconds", + "min_doc_count": 1, + "interval": 1 <4> + }, + "aggs": { + "ruleId": { + "nested": { + "path": "kibana.saved_objects" + }, + "aggs": { + "ruleId": { + "terms": { + "field": "kibana.saved_objects.id", + "size": 10 <5> + } + } + } + } + } + } + } +} +``` + +1. This queries for rules run in the last day. Update the values of `lte` and `gte` to query over a different time range. +2. Use `event.provider: actions` to query for long-running actions. +3. Run durations are stored as nanoseconds. This adds a runtime field to convert that duration into seconds. +4. This interval buckets the `event.duration_in_seconds` runtime field into 1 second intervals. Update this value to change the granularity of the buckets. If you are unable to use runtime fields, make sure this aggregation targets `event.duration` and use nanoseconds for the interval. +5. This retrieves the top 10 rule ids for this duration interval. Update this value to retrieve more rule ids. + + +This query returns the following: + +```json +{ + "took" : 322, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 326, + "relation" : "eq" + }, + "max_score" : null, + "hits" : [ ] + }, + "aggregations" : { + "ruleIdsByExecutionDuration" : { + "buckets" : [ + { + "key" : 0.0, <1> + "doc_count" : 320, + "ruleId" : { + "doc_count" : 320, + "ruleId" : { + "doc_count_error_upper_bound" : 0, + "sum_other_doc_count" : 0, + "buckets" : [ + { + "key" : "1923ada0-a8f3-11eb-a04b-13d723cdfdc5", + "doc_count" : 140 + }, + { + "key" : "15415ecf-cdb0-4fef-950a-f824bd277fe4", + "doc_count" : 130 + }, + { + "key" : "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2", + "doc_count" : 50 + } + ] + } + } + }, + { + "key" : 30.0, <2> + "doc_count" : 6, + "ruleId" : { + "doc_count" : 6, + "ruleId" : { + "doc_count_error_upper_bound" : 0, + "sum_other_doc_count" : 0, + "buckets" : [ + { + "key" : "41893910-6bca-11eb-9e0d-85d233e3ee35", + "doc_count" : 6 + } + ] + } + } + } + ] + } + } +} +``` + +1. Most run durations fall within the first bucket (0 - 1 seconds). +2. A single rule with id `41893910-6bca-11eb-9e0d-85d233e3ee35` took between 30 and 31 seconds to run. + + +Use the get rule API to retrieve additional information about rules that take a long time to run. + + +## Rule cannot decrypt API key [rule-cannot-decrypt-api-key] + +**Problem**: + +The rule fails to run and has an `Unable to decrypt attribute "apiKey"` error. + +**Solution**: + +This error happens when the `xpack.encryptedSavedObjects.encryptionKey` value used to create the rule does not match the value used when the rule runs. Depending on the scenario, there are different ways to solve this problem: + +| | | +| --- | --- | +| If the value in `xpack.encryptedSavedObjects.encryptionKey` was manually changed, and the previous encryption key is still known. | Ensure any previous encryption key is included in the keys used for [decryption only](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys). | +| If another {{kib}} instance with a different encryption key connects to the cluster. | The other {{kib}} instance might be trying to run the rule using a different encryption key than what the rule was created with. Ensure the encryption keys among all the {{kib}} instances are the same, and setting [decryption only keys](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys) for previously used encryption keys. | +| If other scenarios don’t apply. | Generate a new API key for the rule. For example, in **{{stack-manage-app}} > {{rules-ui}}**, select **Update API key** from the action menu. | + + +## Rules stop running after upgrade [known-issue-upgrade-rule] + +**Problem**: + +Alerting rules that were created or edited in 8.2 stop running after you upgrade to 8.3.0 or 8.3.1. The following error occurs: + +```text +:: execution failed - security_exception: [security_exception] Reason: missing authentication credentials for REST request [/_security/user/_has_privileges], caused by: "" +``` + +**Solution**: + +Upgrade to 8.3.2 or later releases to avoid the problem. To fix failing rules, go to **{{stack-manage-app}} > {{rules-ui}}** and multi-select the rules. Choose **Manage rules > Update API Keys** to generate new API keys. For more details about API key authorization, refer to [API keys](alerting-setup.md#alerting-authorization). diff --git a/explore-analyze/alerts/kibana/alerting-setup.md b/explore-analyze/alerts/kibana/alerting-setup.md new file mode 100644 index 000000000..a248a9f03 --- /dev/null +++ b/explore-analyze/alerts/kibana/alerting-setup.md @@ -0,0 +1,130 @@ +--- +navigation_title: "Set up" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/alerting-setup.html +--- + + + +# Set up [alerting-setup] + + +{{kib}} {alert-features} are automatically enabled, but might require some additional configuration. + + +## Prerequisites [alerting-prerequisites] + +If you are using an **on-premises** {{stack}} deployment: + +* In the `kibana.yml` configuration file, add the [`xpack.encryptedSavedObjects.encryptionKey`](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#general-alert-action-settings) setting. +* For emails to have a footer with a link back to {{kib}}, set the [`server.publicBaseUrl`](../../../deploy-manage/deploy/self-managed/configure.md#server-publicBaseUrl) configuration setting. + +If you are using an **on-premises** {{stack}} deployment with [**security**](../../../deploy-manage/security.md): + +* If you are unable to access {{kib}} {alert-features}, ensure that you have not [explicitly disabled API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#api-key-service-settings). + +The alerting framework uses queries that require the `search.allow_expensive_queries` setting to be `true`. See the scripts [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-script-query.html#_allow_expensive_queries_4). + + +## Production considerations and scaling guidance [alerting-setup-production] + +When relying on alerting and actions as mission critical services, make sure you follow the [alerting production considerations](../../../deploy-manage/production-guidance/kibana-alerting-production-considerations.md). + +For more information on the scalability of {{alert-features}}, go to [Scaling guidance](../../../deploy-manage/production-guidance/kibana-alerting-production-considerations.md#alerting-scaling-guidance). + + +## Security [alerting-security] + +To use {{alert-features}} in a {{kib}} app, you must have the appropriate feature privileges: + + +### Give full access to manage alerts, connectors, and rules in **{{stack-manage-app}}** [_give_full_access_to_manage_alerts_connectors_and_rules_in_stack_manage_app] + +**{{kib}} privileges** + +* `All` for the **Management > {{stack-rules-feature}}** feature. +* `All` for the **Management > Rules Settings** feature. +* `All` for the **Management > {{connectors-feature}}** feature. + +::::{note} +The **{{connectors-feature}}** feature privilege is required to manage connectors. To add rule actions and test connectors, you require only `Read` privileges. By default, `All` privileges include authority to run {{endpoint-sec}} connectors (such as SentinelOne and CrowdStrike) unless you customize the sub-feature privileges. + +Likewise, you can customize the **Rules Settings** sub-feature privileges related to flapping detection settings. + +To create a rule that uses the [Cases connector](https://www.elastic.co/guide/en/kibana/current/cases-action-type.html), you must also have `All` privileges for the **Cases** feature. + +The rule type also affects the privileges that are required. For example, to create or edit {{ml}} rules, you must have `all` privileges for the **Analytics > {{ml-app}}** feature. For {{stack-monitor-app}} rules, you must have the `monitoring_user` role. For {{observability}} rules, you must have `all` privileges for the appropriate {{observability}} features. For Security rules, refer to [Detections prerequisites and requirements](../../../solutions/security/detect-and-alert/detections-requirements.md). + +:::: + + + +### Give view-only access to alerts, connectors, and rules in **{{stack-manage-app}}** [_give_view_only_access_to_alerts_connectors_and_rules_in_stack_manage_app] + +**{{kib}} privileges** + +* `Read` for the **Management > {{stack-rules-feature}}** feature. +* `Read` for the **Management > Rules Settings** feature. +* `Read` for the **Management > {{connectors-feature}}** feature. + +::::{note} +The rule type also affects the privileges that are required. For example, to view {{ml}} rules, you must have `read` privileges for the **Analytics > {{ml-app}}** feature. For {{stack-monitor-app}} rules, you must have the `monitoring_user` role. For {{observability}} rules, you must have `read` privileges for the appropriate {{observability}} features. For Security rules, refer to [Detections prerequisites and requirements](../../../solutions/security/detect-and-alert/detections-requirements.md). + +:::: + + + +### Give view-only access to alerts in **Discover** or **Dashboards** [_give_view_only_access_to_alerts_in_discover_or_dashboards] + +**{{kib}} privileges** + +* `Read` index privileges for the `.alerts-*` system indices. + + +### Revoke all access to alerts, connectors, and rules in **{{stack-manage-app}}**, **Discover**, or **Dashboards** [_revoke_all_access_to_alerts_connectors_and_rules_in_stack_manage_app_discover_or_dashboards] + +**{{kib}} privileges** + +* `None` for the **Management > {{stack-rules-feature}}** feature. +* `None` for the **Management > Rules Settings** feature. +* `None` for the **Management > {{connectors-feature}}** feature. +* No index privileges for the `.alerts-*` system indices. + + +### More details [_more_details] + +For more information on configuring roles that provide access to features, go to [Feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges). + + +### API keys [alerting-authorization] + +Rules are authorized using an API key. Its credentials are used to run all background tasks associated with the rule, including condition checks like {{es}} queries and triggered actions. + +When you create a rule in {{kib}}, an API key is created that captures a snapshot of your privileges. Likewise when you update a rule, the API key is updated with a snapshot of your privileges at the time of the edit. + +When you disable a rule, it retains the associated API key which is reused when the rule is enabled. If the API key is missing when you enable the rule, a new key is generated that has your current security privileges. When you import a rule, you must enable it before you can use it and a new API key is generated at that time. + +You can generate a new API key at any time in **{{stack-manage-app}} > {{rules-ui}}*** or in the rule details page by selecting ***Update API key** in the actions menu. + +If you manage your rules by using {{kib}} APIs, they support support both key- and token-based authentication as described in [Authentication](https://www.elastic.co/guide/en/kibana/current/api.html#api-authentication). To use key-based authentication, create API keys and use them in the header of your API calls as described in [API Keys](../../../deploy-manage/api-keys/elasticsearch-api-keys.md). To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently associated with the rule and used when it runs. + +::::{important} +If a rule requires certain privileges, such as index privileges, to run and a user without those privileges updates the rule, the rule will no longer function. Conversely, if a user with greater or administrator privileges modifies the rule, it will begin running with increased privileges. The same behavior occurs when you change the API key in the header of your API calls. + +:::: + + + +### Restrict actions [alerting-restricting-actions] + +For security reasons you may wish to limit the extent to which {{kib}} can connect to external services. You can use [Action settings](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#action-settings) to disable certain [*Connectors*](../../../deploy-manage/manage-connectors.md) and allowlist the hostnames that {{kib}} can connect with. + + +## Space isolation [alerting-spaces] + +Rules and connectors are isolated to the {{kib}} space in which they were created. A rule or connector created in one space will not be visible in another. + + +## {{ccs-cap}} [alerting-ccs-setup] + +If you want to use alerting rules with {{ccs}}, you must configure privileges for {{ccs-init}} and {{kib}}. Refer to [Remote clusters](../../../deploy-manage/remote-clusters.md). diff --git a/explore-analyze/alerts/kibana/alerting-troubleshooting.md b/explore-analyze/alerts/kibana/alerting-troubleshooting.md new file mode 100644 index 000000000..0908d2480 --- /dev/null +++ b/explore-analyze/alerts/kibana/alerting-troubleshooting.md @@ -0,0 +1,207 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/alerting-troubleshooting.html +--- + +# Troubleshooting and limitations [alerting-troubleshooting] + +Alerting provides many options for diagnosing problems with rules and connectors. + + +## Check the {{kib}} log [alerting-kibana-log] + +Rules and connectors log to the Kibana logger with tags of [alerting] and [actions], respectively. Generally, the messages are warnings and errors. In some cases, the error might be a false positive, for example, when a connector is deleted and a rule is running. + +```txt +server log [11:39:40.389] [error][alerting][alerting][plugins][plugins] Executing Rule "5b6237b0-c6f6-11eb-b0ff-a1a0cbcf29b6" has resulted in Error: Saved object [action/fdbc8610-c6f5-11eb-b0ff-a1a0cbcf29b6] not found +``` + +Some of the resources, such as saved objects and API keys, may no longer be available or valid, yielding error messages about those missing resources. + + +## Use the debugging tools [alerting-kibana-version] + +The following debugging tools are available: + +* {{kib}} versions 7.10 and above have a [Test connector](testing-connectors.md) UI. +* {{kib}} versions 7.11 and above include improved Webhook error messages, better overall debug logging for actions and connectors, and Task Manager [diagnostics endpoints](../../../troubleshoot/kibana/task-manager.md#task-manager-diagnosing-root-cause). + + +## Using rules and connectors list for the current state and finding issues [alerting-managment-detail] + +**{{rules-ui}}** in **{{stack-manage-app}}** lists the rules available in the space you’re currently in. When you click a rule name, you are navigated to the [details page](create-manage-rules.md#rule-details) for the rule, where you can see currently active alerts. The start date on this page indicates when a rule is triggered, and for what alerts. In addition, the duration of the condition indicates how long the instance is active. + +:::{image} ../../../images/kibana-rule-details-alerts-inactive.png +:alt: Alerting management details +:class: screenshot +::: + + +## Preview the index threshold rule chart [alerting-index-threshold-chart] + +When creating or editing an index threshold rule, you see a graph of the data the rule will operate against, from some date in the past until now, updated every 5 seconds. + +:::{image} ../../../images/kibana-index-threshold-chart.png +:alt: Index Threshold chart +:class: screenshot +::: + +The end date is related to the check interval for the rule. You can use this view to see if the rule is getting the data you expect, and visually compare to the threshold value (a horizontal line in the graph). If the graph does not contain any lines except for the threshold line, then the rule has an issue, for example, no data is available given the specified index and fields or there is a permission error. Diagnosing these may be difficult - but there may be log messages for error conditions. + + +## Use the REST APIs [alerting-rest-api] + +There is a rich set of HTTP endpoints to introspect and manage rules and connectors. One of the HTTP endpoints available for actions is the run connector API. You can use this to “test” an action. For instance, if you have a server log action created, you can run it via curling the endpoint: + +```txt +curl -X POST -k \ + -H 'kbn-xsrf: foo' \ + -H 'content-type: application/json' \ + api/actions/connector/a692dc89-15b9-4a3c-9e47-9fb6872e49ce/_execute \ + -d '{"params":{"subject":"hallo","message":"hallo!","to":["me@example.com"]}}' +``` + +[preview] In addition, there is a command-line client that uses legacy rule APIs, which can be easier to use, but must be updated for the new APIs. CLI tools to list, create, edit, and delete alerts (rules) and actions (connectors) are available in [kbn-action](https://github.com/pmuellr/kbn-action), which you can install as follows: + +```txt +npm install -g pmuellr/kbn-action +``` + +The same REST POST _execute API command will be: + +```txt +kbn-action execute a692dc89-15b9-4a3c-9e47-9fb6872e49ce ‘{"params":{"subject":"hallo","message":"hallo!","to":["me@example.com"]}}’ +``` + +The result of this HTTP request (and printed to stdout by [kbn-action](https://github.com/pmuellr/kbn-action)) will be data returned by the action, along with error messages if errors were encountered. + + +## Look for error banners [alerting-error-banners] + +The **{{stack-manage-app}}** > **{{rules-ui}}** page contains an error banner that helps to identify the errors for the rules: + +:::{image} ../../../images/kibana-rules-management-health.png +:alt: Rule management page with the errors banner +:class: screenshot +::: + + +## Task Manager diagnostics [task-manager-diagnostics] + +Under the hood, the {{alert-features}} use a plugin called Task Manager, which handles the scheduling, running, and error handling of the tasks. This means that failure cases in {{alert-features}} will, at times, be revealed by the Task Manager mechanism, rather than the Rules mechanism. + +Task Manager provides a visible status which can be used to diagnose issues and is very well documented [health monitoring](../../../deploy-manage/monitor/kibana-task-manager-health-monitoring.md) and [troubleshooting](../../../troubleshoot/kibana/task-manager.md). Task Manager uses the `.kibana_task_manager` index, an internal index that contains all the saved objects that represent the tasks in the system. + + +### Getting from a rule to its task [_getting_from_a_rule_to_its_task] + +When a rule is created, a task is created, scheduled to run at the interval specified. For example, when a rule is created and configured to check every 5 minutes, then the underlying task will be expected to run every 5 minutes. In practice, after each time the rule runs, the task is scheduled to run again in 5 minutes, rather than being scheduled to run every 5 minutes indefinitely. + +If you use the [alerting APIs](https://www.elastic.co/guide/en/kibana/current/alerting-apis.html), such as the get rule API or find rules API, you’ll get an object that contains rule details: + +```txt +{ + "id":"ed30d1b0-7c9e-11ed-ba24-0b137d501cb7", + "name":"cluster_health_rule", + "consumer":"alerts", + "enabled":true, + ... + "scheduled_task_id":"ed30d1b0-7c9e-11ed-ba24-0b137d501cb7", + ... + "next_run":"2022-12-15T17:56:55.713Z" +} +``` + +The field you’re looking for is the one called `scheduled_task_id` which includes the identifier for the Task Manager task. You can then go to the Console and find more information about that task in system indices: + +```txt +GET .kibana_task_manager/_doc/task:ed30d1b0-7c9e-11ed-ba24-0b137d501cb7 +``` + +For example: + +```txt +{ + "_index": ".kibana_task_manager_8.7.0_001", + "_id": "task:ed30d1b0-7c9e-11ed-ba24-0b137d501cb7", + "_version": 85, + "_seq_no": 13009, + "_primary_term": 3, + "found": true, + "_source": { + "migrationVersion": { + "task": "8.5.0" + }, + "task": { + "retryAt": null, + "runAt": "2022-12-15T18:05:19.804Z", + "startedAt": null, + "params": """{"alertId":"ed30d1b0-7c9e-11ed-ba24-0b137d501cb7","spaceId":"default","consumer":"alerts"}""", + "ownerId": null, + "enabled": true, + "schedule": { + "interval": "1m" + }, + "taskType": "alerting:monitoring_alert_cluster_health", + "scope": [ + "alerting" + ], + "traceparent": "", + "state": """{"alertTypeState":{"lastChecked":1671127459923},"alertInstances":{},"alertRecoveredInstances":{},"previousStartedAt":"2022-12-15T18:04:19.804Z"}""", + "scheduledAt": "2022-12-15T18:04:16.824Z", + "attempts": 0, + "status": "idle" + }, + "references": [], + "updated_at": "2022-12-15T18:04:19.998Z", + "coreMigrationVersion": "8.7.0", + "created_at": "2022-12-15T17:35:55.204Z", + "type": "task" + } +} +``` + +For the rule to work, this task must be in a healthy state. Its health information is available in the [Task Manager health API](https://www.elastic.co/guide/en/kibana/current/task-manager-api-health.html) or in verbose logs if debug logging is enabled. When diagnosing the health state of the task, you will most likely be interested in the following fields: + +`status` +: This is the current status of the task. Is Task Manager currently running? Is Task Manager idle, and you’re waiting for it to run? Or has Task Manager has tried to run and failed? + +`runAt` +: This is when the task is scheduled to run next. If this is in the past and the status is idle, Task Manager has fallen behind or isn’t running. If it’s in the past, but the status is running, then Task Manager has picked it up and is working on it, which is considered healthy. + +`retryAt` +: Another time field, like `runAt`. If this field is populated, then Task Manager is currently running the task. If the task doesn’t complete (and isn’t marked as failed), then Task Manager will give it another attempt at the time specified under `retryAt`. + +Investigating the underlying task can help you gauge whether the problem you’re seeing is rooted in the rule not running at all, whether it’s running and failing, or whether it’s running but exhibiting behavior that is different than what was expected (at which point you should focus on the rule itself, rather than the task). + +In addition to the above methods, refer to the following approaches and common issues: + +* [Alerting common issues](alerting-common-issues.md) +* [Querying event log index](event-log-index.md) +* [Testing connectors using {{connectors-ui}} UI and the `kbn-action` tool](testing-connectors.md) + + +### Temporarily throttle all tasks [alerting-kibana-throttle] + +If cluster performance becomes degraded from excessive or expensive rules and {{kib}} is sluggish or unresponsive, you can temporarily reduce load to the Task Manager by updating its [settings](https://www.elastic.co/guide/en/kibana/current/task-manager-settings-kb.html): + +```txt +xpack.task_manager.capacity: 5 +xpack.task_manager.poll_interval: 1h +``` + +::::{warning} +This approach should be used only temporarily as a last resort to restore function to {{kib}} when it is unresponsive and attempts to identify and [snooze or disable](create-manage-rules.md#controlling-rules) slow-running rules have not fixed the situation. It severely throttles all background tasks, not just those relating to {{alert-features}}. The task manager will run only one task at a time and will look for more work each hour. + +:::: + + + +## Limitations [alerting-limitations] + +The following limitations and known problems apply to the 9.0.0-beta1 release of the {{kib}} {alert-features}: + + +### Alert visibility [_alert_visibility] + +If you create a rule in the {{observability}} or {{security-app}}, its alerts are not visible in **{{stack-manage-app}} > {{rules-ui}}**. You can view them only in the {{kib}} app where you created the rule. If you use the create rule API, the visibility of the alerts is related to the `consumer` property. diff --git a/explore-analyze/alerts/kibana/create-manage-rules.md b/explore-analyze/alerts/kibana/create-manage-rules.md new file mode 100644 index 000000000..ede39ff49 --- /dev/null +++ b/explore-analyze/alerts/kibana/create-manage-rules.md @@ -0,0 +1,187 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/create-and-manage-rules.html +--- + +# Create and manage rules [create-and-manage-rules] + +The **{{stack-manage-app}}** > **{{rules-ui}}** UI provides a cross-app view of alerting. Different {{kib}} apps like [**{{observability}}**](../../../solutions/observability/incident-management/alerting.md), [**Security**](https://www.elastic.co/guide/en/security/current/prebuilt-rules.html), [**Maps**](geo-alerting.md) and [**{{ml-app}}**](../../machine-learning/machine-learning-in-kibana.md) can offer their own rules. + +You can find **Rules** in **Stack Management** > **Alerts and insights** > **Rules** in {{kib}} or by using the [global search field](../../../get-started/the-stack.md#kibana-navigation-search). + +![Rules page navigation](../../../images/kibana-stack-management-rules.png "") + +**{{rules-ui}}** provides a central place to: + +* [Create and edit](#create-edit-rules) rules +* [Manage rules](#controlling-rules) including enabling/disabling, muting/unmuting, and deleting +* Drill down to [rule details](#rule-details) +* Configure rule settings + +For more information on alerting concepts and the types of rules and connectors available, go to [Alerting](../kibana.md). + + +## Required permissions [_required_permissions] + +Access to rules is granted based on your {{alert-features}} privileges. For more information, go to [Security](alerting-setup.md#alerting-security). + + +## Create and edit rules [create-edit-rules] + +Some rules must be created within the context of a {{kib}} app like [Metrics](https://www.elastic.co/guide/en/kibana/current/observability.html#metrics-app), [**APM**](https://www.elastic.co/guide/en/kibana/current/observability.html#apm-app), or [Uptime](https://www.elastic.co/guide/en/kibana/current/observability.html#uptime-app), but others are generic. Generic rule types can be created in **{{rules-ui}}** by clicking the **Create rule** button. This will launch a flyout that guides you through selecting a rule type and configuring its conditions and actions. + +After a rule is created, you can open the action menu (…) and select **Edit rule** to re-open the flyout and change the rule properties. + +::::{tip} +You can also manage rules as resources with the [Elasticstack provider](https://registry.terraform.io/providers/elastic/elasticstack/latest) for Terraform. For more details, refer to the [elasticstack_kibana_alerting_rule](https://registry.terraform.io/providers/elastic/elasticstack/latest/docs/resources/kibana_alerting_rule) resource. +:::: + + + +### Rule type and conditions [defining-rules-type-conditions] + +Depending on the {{kib}} app and context, you might be prompted to choose the type of rule to create. Some apps will preselect the type of rule for you. + +Each rule type provides its own way of defining the conditions to detect, but an expression formed by a series of clauses is a common pattern. For example, in an {{es}} query rule, you specify an index, a query, and a threshold, which uses a metric aggregation operation (`count`, `average`, `max`, `min`, or `sum`): + +:::{image} ../../../images/kibana-rule-types-es-query-conditions.png +:alt: UI for defining rule conditions in an {{es}} query rule +:class: screenshot +::: + +All rules must have a check interval, which defines how often to evaluate the rule conditions. Checks are queued; they run as close to the defined value as capacity allows. + +For details on what types of rules are available and how to configure them, refer to [*Rule types*](rule-types.md). + + +### Actions [defining-rules-actions-details] + +You can add one or more actions to your rule to generate notifications when its conditions are met and when they are no longer met. + +Each action uses a connector, which provides connection information for a {{kib}} service or third party integration, depending on where you want to send the notifications. + +[preview] Some connectors that perform actions within {{kib}}, such as the [Cases connector](https://www.elastic.co/guide/en/kibana/current/cases-action-type.html), require less configuration. For example, you do not need to set the action frequency or variables. + +After you select a connector, set the action frequency. You can choose to create a summary of alerts on each check interval or on a custom interval. Alternatively, you an choose to run actions for each alert (at each check interval, only when the alert status changes, or at a custom interval). + +::::{note} +If you choose a custom action interval, it cannot be shorter than the rule’s check interval. +:::: + + +For example, if you create an {{es}} query rule, you can send notifications that summarize the new, ongoing, and recovered alerts on a custom interval: + +:::{image} ../../../images/kibana-es-query-rule-action-summary.png +:alt: UI for defining alert summary action in an {{es}} query rule +:class: screenshot +::: + +When you choose to run actions for each alert, you must specify an action group. Each rule type has a set of valid action groups, which affect when an action runs. For example, you can set **Run when** to `Query matched` or `Recovered` for the {{es}} query rule: + +:::{image} ../../../images/kibana-es-query-rule-recovery-action.png +:alt: UI for defining a recovery action +:class: screenshot +::: + +Connectors have unique behavior for each action group. For example, you can have actions that create an {{opsgenie}} alert when rule conditions are met and recovery actions that close the {{opsgenie}} alert. For more information about connectors, refer to [*Connectors*](../../../deploy-manage/manage-connectors.md). + +::::{tip} +:name: alerting-concepts-suppressing-duplicate-notifications + +If you are not using alert summaries, actions are generated per alert and a rule can end up generating a large number of actions. Take the following example where a rule is monitoring three servers every minute for CPU usage > 0.9, and the action frequency is `On check intervals`: + +* Minute 1: server X123 > 0.9. *One email* is sent for server X123. +* Minute 2: X123 and Y456 > 0.9. *Two emails* are sent, one for X123 and one for Y456. +* Minute 3: X123, Y456, Z789 > 0.9. *Three emails* are sent, one for each of X123, Y456, Z789. + +In this example, three emails are sent for server X123 in the span of 3 minutes for the same rule. Often, it’s desirable to suppress these re-notifications. If you set the action frequency to `On custom action intervals` with an interval of 5 minutes, you reduce noise by getting emails only every 5 minutes for servers that continue to exceed the threshold: + +* Minute 1: server X123 > 0.9. *One email* will be sent for server X123. +* Minute 2: X123 and Y456 > 0.9. *One email* will be sent for Y456. +* Minute 3: X123, Y456, Z789 > 0.9. *One email* will be sent for Z789. + +To get notified only once when a server exceeds the threshold, you can set the action frequency to `On status changes`. Alternatively, consider using alert summaries to reduce the volume of notifications. + +:::: + + + +### Action variables [defining-rules-actions-variables] + +You can pass rule values to an action at the time a condition is detected. To view the list of variables available for your rule, click the "add rule variable" button: + +:::{image} ../../../images/kibana-es-query-rule-action-variables.png +:alt: Passing rule values to an action +:class: screenshot +::: + +For more information about common action variables, refer to [*Rule action variables*](rule-action-variables.md). + + +## Snooze and disable rules [controlling-rules] + +The rule listing enables you to quickly snooze, disable, enable, or delete individual rules. For example, you can change the state of a rule: + +![Use the rule status dropdown to enable or disable an individual rule](../../../images/kibana-individual-enable-disable.png "") + +If there are rules that are not currently needed, disable them to stop running checks and reduce the load on your cluster. + +When you snooze a rule, the rule checks continue to run on a schedule but alerts will not generate actions. You can snooze for a specified period of time, indefinitely, or schedule single or recurring downtimes: + +![Snooze notifications for a rule](../../../images/kibana-snooze-panel.png "") + +When a rule is in a snoozed state, you can cancel or change the duration of this state. + +[preview] To temporarily suppress notifications for rules, you can also create a [maintenance window](maintenance-windows.md). + + +## View rule details [rule-details] + +You can determine the health of a rule by looking at the **Last response** in **{{stack-manage-app}}** > **{{rules-ui}}**. A rule can have one of the following responses: + +`failed` +: The rule ran with errors. + +`succeeded` +: The rule ran without errors. + +`warning` +: The rule ran with some non-critical errors. + +Click the rule name to access a rule details page: + +:::{image} ../../../images/kibana-rule-details-alerts-active.png +:alt: Rule details page with multiple alerts +:class: screenshot +::: + +In this example, the rule detects when a site serves more than a threshold number of bytes in a 24 hour period. Four sites are above the threshold. These are called alerts - occurrences of the condition being detected - and the alert name, status, time of detection, and duration of the condition are shown in this view. Alerts come and go from the list depending on whether the rule conditions are met. For more information about alerts, go to [*View alerts*](view-alerts.md). + +If there are rule actions that failed to run successfully, you can see the details on the **History** tab. In the **Message** column, click the warning or expand icon ![double arrow icon to open a flyout with the document details](../../../images/kibana-expand-icon-2.png "") or click the number in the **Errored actions** column to open the **Errored Actions** panel. In this example, the action failed because the [`xpack.actions.email.domain_allowlist`](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#action-config-email-domain-allowlist) setting was updated and the action’s email recipient is no longer included in the allowlist: + +:::{image} ../../../images/kibana-rule-details-errored-actions.png +:alt: Rule histor page with alerts that have errored actions +:class: screenshot +::: + + +## Import and export rules [importing-and-exporting-rules] + +To import and export rules, use [saved objects](../../find-and-organize/saved-objects.md). + +::::{note} +Some rule types cannot be exported through this interface: + +**Security rules** can be imported and exported using the [Security UI](../../../solutions/security/detect-and-alert/manage-detection-rules.md#import-export-rules-ui). + +**Stack monitoring rules** are [automatically created](../../../deploy-manage/monitor/monitoring-data/kibana-alerts.md) for you and therefore cannot be managed in **Saved Objects**. + +:::: + + +Rules are disabled on export. You are prompted to re-enable the rule on successful import. + +:::{image} ../../../images/kibana-rules-imported-banner.png +:alt: Rules import banner +:class: screenshot +::: diff --git a/explore-analyze/alerts/kibana/event-log-index.md b/explore-analyze/alerts/kibana/event-log-index.md new file mode 100644 index 000000000..d0ef9bed6 --- /dev/null +++ b/explore-analyze/alerts/kibana/event-log-index.md @@ -0,0 +1,208 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/event-log-index.html +--- + +# Event log index [event-log-index] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +Use the event log index to determine: + +* Whether a rule ran successfully but its associated actions did not +* Whether a rule was ever activated +* Additional information about errors when the rule ran +* Run durations for the rules and actions + + +## Example event log queries [_example_event_log_queries] + +The following event log query looks at all events related to a specific rule id: + +```txt +GET /.kibana-event-log*/_search +{ + "sort": [ + { + "@timestamp": { + "order": "desc" + } + } + ], + "query": { + "bool": { + "filter": [ + { + "term": { + "event.provider": { + "value": "alerting" + } + } + }, + // optionally filter by specific action event + { + "term": { + "event.action": "active-instance" + | "execute-action" + | "new-instance" + | "recovered-instance" + | "execute" + } + }, + // filter by specific rule id + { + "nested": { + "path": "kibana.saved_objects", + "query": { + "bool": { + "filter": [ + { + "term": { + "kibana.saved_objects.id": { + "value": "b541b690-bfc4-11eb-bf08-05a30cefd1fc" + } + } + }, + { + "term": { + "kibana.saved_objects.type": "alert" + } + } + + ] + } + } + } + } + ] + } + } +} +``` + +The following event log query looks at all events related to running a rule or action. These events include duration: + +```txt +GET /.kibana-event-log*/_search +{ + "sort": [ + { + "@timestamp": { + "order": "desc" + } + } + ], + "query": { + "bool": { + "filter": [ + { + "term": { + "event.action": { + "value": "execute" + } + } + }, + // optionally filter by specific rule or action id + { + "nested": { + "path": "kibana.saved_objects", + "query": { + "bool": { + "filter": [ + { + "term": { + "kibana.saved_objects.id": { + "value": "b541b690-bfc4-11eb-bf08-05a30cefd1fc" + } + } + } + ] + } + } + } + } + ] + } + } +} +``` + +The following event log query looks at the errors. You should see an `error.message` property in that event, with a message that might provide more details about why the action encountered an error: + +```txt +{ + "event": { + "provider": "actions", + "action": "execute", + "start": "2020-03-31T04:27:30.392Z", + "end": "2020-03-31T04:27:30.393Z", + "duration": 1000000 + }, + "kibana": { + "namespace": "default", + "saved_objects": [ + { + "type": "action", + "id": "7a6fd3c6-72b9-44a0-8767-0432b3c70910" + } + ], + }, + "message": "action executed: .server-log:7a6fd3c6-72b9-44a0-8767-0432b3c70910: server-log", + "@timestamp": "2020-03-31T04:27:30.393Z", +} +``` + +You might also see the errors for the rules, which can use in the next search query. For example: + +```txt +{ + "event": { + "provider": "alerting", + "start": "2020-03-31T04:27:30.392Z", + "end": "2020-03-31T04:27:30.393Z", + "duration": 1000000 + }, + "kibana": { + "namespace": "default", + "saved_objects": [ + { + "rel" : "primary", + "type" : "alert", + "id" : "30d856c0-b14b-11eb-9a7c-9df284da9f99" + } + ], + }, + "message": "rule executed: .index-threshold:30d856c0-b14b-11eb-9a7c-9df284da9f99: 'test'", + "error" : { + "message" : "Saved object [action/ef0e2530-b14a-11eb-9a7c-9df284da9f99] not found" + }, +} +``` + +You can also query the event log for failures, which should return more specific details about rules which failed by targeting the event.outcome: + +```txt +GET .kibana-event-log-*/_search +{ + "query": { + "bool": { + "must": [ + { "match": { "event.outcome": "failure" }} + ] + } + } +} +``` + +Here’s an example of what failed credentials from Google SMTP might look like from the response: + +```txt +"error" : { + "message" : """error sending email: Invalid login: 535-5.7.8 Username and Password not accepted. Learn more at +535 5.7.8 https://support.google.com/mail/?p=BadCredentials e207sm3359731pfh.171 - gsmtp""" +}, +``` + diff --git a/explore-analyze/alerts/kibana/geo-alerting.md b/explore-analyze/alerts/kibana/geo-alerting.md new file mode 100644 index 000000000..7d8357907 --- /dev/null +++ b/explore-analyze/alerts/kibana/geo-alerting.md @@ -0,0 +1,85 @@ +--- +navigation_title: "Tracking containment" +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/geo-alerting.html +--- + + + +# Tracking containment [geo-alerting] + + +The tracking containment rule alerts when an entity is contained or no longer contained within a boundary. + +In **{{stack-manage-app}}** > **{{rules-ui}}**, click **Create rule**. Select the **Tracking containment** rule type then fill in the name and optional tags. + + +## Define the conditions [_define_the_conditions_3] + +When you create a tracking containment rule, you must define the conditions that it detects. For example: + +:::{image} ../../../images/kibana-alert-types-tracking-containment-conditions.png +:alt: Creating a tracking containment rule in Kibana +:class: screenshot +::: + +1. Define the entities index, which must contain a `geo_point` or `geo_shape` field, `date` field, and entity identifier. An entity identifier is a `keyword`, `number`, or `ip` field that identifies the entity. Entity data is expected to be updating so that there are entity movements to alert upon. +2. Define the boundaries index, which contains `geo_shape` data. Boundaries data is expected to be static (not updating). Boundaries are collected once when the rule is created and anytime after when boundary configuration is modified. +3. Set the check interval, which defines how often to evaluate the rule conditions. +4. In the advanced options, you can change the number of consecutive runs that must meet the rule conditions before an alert occurs. The default value is `1`. + +Entity locations are queried to determine whether they are contained within any monitored boundaries. Entity data should be somewhat "real time", meaning the dates of new documents aren’t older than the current time minus the amount of the interval. If data older than `now - ` is ingested, it won’t trigger a rule. + + +## Add actions [_add_actions_2] + +You can optionally send notifications when the rule conditions are met. In particular, this rule type supports: + +* alert summaries +* actions that run when the containment condition is met +* actions that run when an entity is no longer contained + +For each action, you must choose a connector, which provides connection information for a {{kib}} service or third party integration. For more information about all the supported connectors, go to [*Connectors*](../../../deploy-manage/manage-connectors.md). + +After you select a connector, you must set the action frequency. You can choose to create a summary of alerts on each check interval or on a custom interval. Alternatively, you can set the action frequency such that actions run for each alert. Choose how often the action runs (at each check interval, only when the alert status changes, or at a custom action interval). You must also choose an action group, which indicates whether the action runs when the containment condition is met or when an entity is no longer contained. Each connector supports a specific set of actions for each action group. For example: + +:::{image} ../../../images/kibana-alert-types-tracking-containment-action-options.png +:alt: Action frequency options for an action +:class: screenshot +::: + +You can further refine the conditions under which actions run by specifying that actions only run when they match a KQL query or when an alert occurs within a specific time frame. + + +## Add action variables [_add_action_variables_2] + +You can pass rule values to an action to provide contextual details. To view the list of variables available for each action, click the "add rule variable" button. For example: + +:::{image} ../../../images/kibana-alert-types-tracking-containment-rule-action-variables.png +:alt: Passing rule values to an action +:class: screenshot +::: + +The following action variables are specific to the tracking containment rule. You can also specify [variables common to all rules](rule-action-variables.md). + +`context.containingBoundaryId` +: The identifier for the boundary containing the entity. This value is not set for recovered alerts. + +`context.containingBoundaryName` +: The name of the boundary containing the entity. This value is not set for recovered alerts. + +`context.detectionDateTime` +: The end of the check interval when the alert occurred. + +`context.entityDateTime` +: The date the entity was recorded in the boundary. + +`context.entityDocumentId` +: The identifier for the contained entity document. + +`context.entityId` +: The entity identifier for the document that generated the alert. + +`context.entityLocation` +: The location of the entity. + diff --git a/explore-analyze/alerts/kibana/maintenance-windows.md b/explore-analyze/alerts/kibana/maintenance-windows.md new file mode 100644 index 000000000..073b7d7ef --- /dev/null +++ b/explore-analyze/alerts/kibana/maintenance-windows.md @@ -0,0 +1,16 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/maintenance-windows.html + - https://www.elastic.co/guide/en/serverless/current/maintenance-windows.html +--- + +# Maintenance windows + +% What needs to be done: Align serverless/stateful + +% Scope notes: Merge these two pages + +% Use migrated content from existing pages that map to this page: + +% - [ ] ./raw-migrated-files/kibana/kibana/maintenance-windows.md +% - [ ] ./raw-migrated-files/docs-content/serverless/maintenance-windows.md \ No newline at end of file diff --git a/explore-analyze/alerts/kibana/rule-action-variables.md b/explore-analyze/alerts/kibana/rule-action-variables.md new file mode 100644 index 000000000..8e5505e2e --- /dev/null +++ b/explore-analyze/alerts/kibana/rule-action-variables.md @@ -0,0 +1,455 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/kibana/current/rule-action-variables.html +--- + +# Rule action variables [rule-action-variables] + +Alerting rules can use the [Mustache](https://mustache.github.io/mustache.5.md) template syntax (`{{variable name}}`) to pass values when the actions run. + + +## Common variables [common-rule-action-variables] + +The available variables differ by rule type, however there are some common variables: + +* [General](#general-rule-action-variables) +* [Action frequency: Summary of alerts](#alert-summary-action-variables) +* [Action frequency: For each alert](#alert-action-variables) + +Some cases exist where the variable values will be "escaped" when used in a context where escaping is needed. For example: + +* For the [email connector](https://www.elastic.co/guide/en/kibana/current/email-action-type.html), the `message` action configuration property escapes any characters that would be interpreted as Markdown. +* For the [Slack connector](https://www.elastic.co/guide/en/kibana/current/slack-action-type.html), the `message` action configuration property escapes any characters that would be interpreted as Slack Markdown. +* For the [Webhook connector](https://www.elastic.co/guide/en/kibana/current/webhook-action-type.html), the `body` action configuration property escapes any characters that are invalid in JSON string values. + +Mustache also supports "triple braces" of the form `{{{variable name}}}`, which indicates no escaping should be done at all. Use this form with caution, since it could end up rendering the variable content such that the resulting parameter is invalid or formatted incorrectly. + + +### General [general-rule-action-variables] + +All rule types pass the following variables: + +`date` +: The date the rule scheduled the action, in ISO format. + +`kibanaBaseUrl` +: The configured [`server.publicBaseUrl`](../../../deploy-manage/deploy/self-managed/configure.md#server-publicBaseUrl). If not configured, this will be empty. + +`rule.id` +: The rule identifier. + +`rule.name` +: The rule name. + +`rule.params` +: The rule parameters, which vary by rule type. + +`rule.spaceId` +: The space identifier for the rule. + +`rule.tags` +: The list of tags applied to the rule. + +`rule.url` +: The URL for the rule that generated the alert. This will be an empty string if the `server.publicBaseUrl` setting is not configured. + + +### Action frequency: Summary of alerts [alert-summary-action-variables] + +If the rule’s action frequency is a summary of alerts, it passes the following variables: + +`alerts.all.count` +: The count of all alerts. + +`alerts.all.data` +: An array of objects for all alerts. The following object properties are examples; it is not a comprehensive list. + + ::::{dropdown} Properties of the alerts.all.data objects + `kibana.alert.end` + : Datetime stamp of alert end. [preview] + + `kibana.alert.flapping` + : A flag on the alert that indicates whether the alert status is changing repeatedly. [preview] + + `kibana.alert.instance.id` + : ID of the source that generates the alert. [preview] + + `kibana.alert.reason` + : The reason of the alert (generated with the rule conditions). [preview] + + `kibana.alert.start` + : Datetime stamp of alert start. [preview] + + `kibana.alert.status` + : Alert status (for example, active or OK). [preview] + + :::: + + +`alerts.new.count` +: The count of new alerts. + +`alerts.new.data` +: An array of objects for new alerts. The following object properties are examples; it is not a comprehensive list. + + ::::{dropdown} Properties of the alerts.new.data objects + `kibana.alert.end` + : Datetime stamp of alert end. [preview] + + `kibana.alert.flapping` + : A flag on the alert that indicates whether the alert status is changing repeatedly. [preview] + + `kibana.alert.instance.id` + : ID of the source that generates the alert. [preview] + + `kibana.alert.reason` + : The reason of the alert (generated with the rule conditions). [preview] + + `kibana.alert.start` + : Datetime stamp of alert start. [preview] + + `kibana.alert.status` + : Alert status (for example, active or OK). [preview] + + :::: + + +`alerts.ongoing.count` +: The count of ongoing alerts. + +`alerts.ongoing.data` +: An array of objects for ongoing alerts. The following object properties are examples; it is not a comprehensive list. + + ::::{dropdown} Properties of the alerts.ongoing.data objects + `kibana.alert.end` + : Datetime stamp of alert end. [preview] + + `kibana.alert.flapping` + : A flag on the alert that indicates whether the alert status is changing repeatedly. [preview] + + `kibana.alert.instance.id` + : ID of the source that generates the alert. [preview] + + `kibana.alert.reason` + : The reason of the alert (generated with the rule conditions). [preview] + + `kibana.alert.start` + : Datetime stamp of alert start. [preview] + + `kibana.alert.status` + : Alert status (for example, active or OK). [preview] + + :::: + + +`alerts.recovered.count` +: The count of recovered alerts. + +`alerts.recovered.data` +: An array of objects for recovered alerts. The following object properties are examples; it is not a comprehensive list. + + ::::{dropdown} Properties of the alerts.recovered.data objects + `kibana.alert.end` + : Datetime stamp of alert end. [preview] + + `kibana.alert.flapping` + : A flag on the alert that indicates whether the alert status is changing repeatedly. [preview] + + `kibana.alert.instance.id` + : ID of the source that generates the alert. [preview] + + `kibana.alert.reason` + : The reason of the alert (generated with the rule conditions). [preview] + + `kibana.alert.start` + : Datetime stamp of alert start. [preview] + + `kibana.alert.status` + : Alert status (for example, active or OK). [preview] + + :::: + + + +### Action frequency: For each alert [alert-action-variables] + +If the rule’s action frequency is not a summary of alerts, it passes the following variables: + +`alert.actionGroup` +: The ID of the action group of the alert that scheduled the action. + +`alert.actionGroupName` +: The name of the action group of the alert that scheduled the action. + +`alert.actionSubgroup` +: The action subgroup of the alert that scheduled the action. + +`alert.consecutiveMatches` +: The number of consecutive runs that meet the rule conditions. + +`alert.flapping` +: A flag on the alert that indicates whether the alert status is changing repeatedly. + +`alert.id` +: The ID of the alert that scheduled the action. + +`alert.uuid` +: A universally unique identifier for the alert. While the alert is active, the UUID value remains unchanged each time the rule runs. [preview] + + +#### Context [defining-rules-actions-variable-context] + +If the rule’s action frequency is not a summary of alerts, the rule defines additional variables as properties of the variable `context`. For example, if a rule type defines a variable `value`, it can be used in an action parameter as `{{context.value}}`. + +For diagnostic or exploratory purposes, action variables whose values are objects, such as `context`, can be referenced directly as variables. The resulting value will be a JSON representation of the object. For example, if an action parameter includes `{{context}}`, it will expand to the JSON representation of all the variables and values provided by the rule type. To see all alert-specific variables, use `{{.}}`. + +For situations where your rule response returns arrays of data, you can loop through the `context`: + +```sh +{{#context}}{{.}}{{/context}} +``` + +For example, looping through search result hits: + +```sh +triggering data was: +{{#context.hits}} - {{_source.message}} +{{/context.hits}} +``` + + +## Enhancing Mustache variables [enhance-mustache-variables] + +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + + +You can enhance the values contained in Mustache variables when the Mustache template is rendered by rendering objects as JSON or by using Mustache lambdas. + + +### Rendering objects as JSON [_rendering_objects_as_json] + +Some connectors (such as the [Webhook connector](https://www.elastic.co/guide/en/kibana/current/webhook-action-type.html)) expect JSON values to be passed as parameters when the connector is invoked. The following capabilities are available: + +* Array values referenced in braces have a predefined rendering by Mustache as string versions of the array elements, joined with a comma (`,`). To render array values as JSON, access the `asJSON` property of the array, instead of the array directly. For example, given a Mustache variable `context.values` that has the value `[1, 4, 9]` the Mustache template `{{context.values}}` will render as `1,4,9`, and the Mustache template `{{context.values.asJSON}}` will render as `[1,4,9]`. +* The [ParseHjson lambda](#parse-hjson-lambda) Mustache lambda makes it easier to create JSON in your templates by using [Hjson](https://hjson.github.io/), a syntax extension to JSON, rather than strict JSON. + + +### Using Mustache lambdas [_using_mustache_lambdas] + +Mustache lambdas provide additional rendering capabilities for Mustache templates. A Mustache lambda is formatted like a Mustache section. For example: + +```sh +{{#EvalMath}} round(context.value, 1) {{/EvalMath}} +``` + +In that example, the lambda `EvalMath` is passed the text `round(context.value, 1)` and renders a rounded value of the `context.value` variable. This pattern is used by all the provided Mustache lambdas described in the subsequent sections. + + +#### EvalMath [_evalmath] + +The EvalMath lambda will evaluate the text passed to it as [TinyMath functions](../../visualize/canvas/canvas-tinymath-functions.md). + +For example, when the Mustache variable `context.value` is `3.1234`, the following template will render as `3.1`: + +```sh +{{#EvalMath}} round(context.value, 1) {{/EvalMath}} +``` + +This lambda can access Mustache variables without having to wrap them in `{{}}`. However, if the value is in a string form (for example, an Elasticsearch numeric field whose source was indexed as a string), or could be escaped, escaping the value with triple quotes should allow this to work. For example, if the Mustache variable `context.value` is `"3.1234"`, the following template will render as `3.1`: + +```sh +{{#EvalMath}} round( {{{context.value}}} , 1) {{/EvalMath}} +``` + + +#### ParseHjson [parse-hjson-lambda] + +The ParseHjson lambda provides ease-of-use capabilities when constructing JSON objects. [Hjson](https://hjson.github.io/) is a syntax extension to JSON. It has the following features: + +* Missing and extra trailing commas are allowed in arrays and objects. +* Comments are supported. +* Property names can be specified without quotes. +* Property values can be specified without quotes (one per line and no commas). +* Multi-line strings have dedent support to remove the leading whitespace. +* Legal JSON documents are supported. + +To use it, surround your Hjson content with `{{#ParseHjson}}...{{/ParseHjson}}`. For example: + +```sh +{{#ParseHjson}} +{ + # add the rule id and name to the JSON document + ruleId: "{{rule.id}}" + ruleName: "{{rule.name}}" +} +{{/ParseHjson}} +``` + +When rendered, this template will generate: + +```json + { + "ruleId": "", + "ruleName": "" + } +``` + + +#### FormatDate [_formatdate] + +The FormatDate lambda provides date formatting capabilities. Dates can be formatted in an arbitrary time zone and with an arbitrary format string. + +To use it, surround the date and formatting parameters with `{{#FormatDate}}...{{/FormatDate}}`. + +The format of the text passed to the lambda is: `;