elastic · tobio · Dec 14, 2022 · Dec 6, 2022 · Dec 6, 2022 · Dec 6, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@
 - Add `elasticstack_elasticsearch_security_system_user` resource to manage built-in user ([#188](https://github.com/elastic/terraform-provider-elasticstack/pull/188))
 - Add `unassigned_node_left_delayed_timeout` to index resource ([#196](https://github.com/elastic/terraform-provider-elasticstack/pull/196))
 - Add support for Client certificate based authentication ([#191](https://github.com/elastic/terraform-provider-elasticstack/pull/191))
+- Deprecate `elasticsearch_connection` blocks on individual resources/data sources. Connection configuration should be configured directly on the provider with multiple provider instances used to connect to different clusters. ([#218](https://github.com/elastic/terraform-provider-elasticstack/pull/218))
 
 ### Fixed
 - Remove unnecessary unsetting id on delete ([#174](https://github.com/elastic/terraform-provider-elasticstack/pull/174))

diff --git a/docs/data-sources/elasticsearch_security_role.md b/docs/data-sources/elasticsearch_security_role.md
@@ -35,7 +35,7 @@ output "role" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `run_as` (Set of String) A list of users that the owners of this role can impersonate.
 
 ### Read-Only

diff --git a/docs/data-sources/elasticsearch_security_role_mapping.md b/docs/data-sources/elasticsearch_security_role_mapping.md
@@ -35,7 +35,7 @@ output "user" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 
 ### Read-Only
 

diff --git a/docs/data-sources/elasticsearch_security_user.md b/docs/data-sources/elasticsearch_security_user.md
@@ -35,7 +35,7 @@ output "user" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 
 ### Read-Only
 

diff --git a/docs/data-sources/elasticsearch_snapshot_repository.md b/docs/data-sources/elasticsearch_snapshot_repository.md
@@ -61,7 +61,7 @@ output "repo_url" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 
 ### Read-Only
 

diff --git a/docs/guides/elasticstack-cloud-with-monitoring.md b/docs/guides/elasticstack-cloud-with-monitoring.md
@@ -0,0 +1,160 @@
+---
+subcategory: ""
+page_title: "Using the Elastic Stack provider with multiple Elastic Cloud deployments"
+description: |-
+    An example of how to spin up multiple Elastic Cloud deployments and configure them using multiple Elastic Stack provider instances.
+---
+
+# Using the Elastic Stack provider with multiple Elastic Cloud deployments
+
+Using aliased Elastic Stack providers allows managing multiple Elastic Cloud deployments (or self hosted Elasticsearch clusters).
+In this example, we use both the Elastic Cloud provider, as well as the Elastic Stack provider.
+We start off by configuring just the Elastic Cloud provider in a `provider.tf` file, for example:
+
+```terraform
+terraform {
+  required_version = ">= 1.0.0"
+
+  required_providers {
+    ec = {
+      source  = "elastic/ec"
+      version = "~>0.3.0"
+    }
+    elasticstack = {
+      source  = "elastic/elasticstack"
+      version = "~>0.4.0"
+    }
+  }
+}
+provider "ec" {
+  # You can fill in your API key here, or use an environment variable instead
+  apikey = "<api key>"
+}
+```
+
+Next, we'll set up two Elastic Cloud `ec_deployment` resources, which represent Elastic Stack deployments on Elastic Cloud.
+The `monitoring` deployment is configured as a dedicated monitoring deployment, with the `cluster` deployment configured to ship
+monitoring data to the `monitoring` deployment.
+
+We also configure two instances of the Elastic Stack provider, including an alias for the instance connected to the `monitoring` deployment.
+
+Finally, we configure the Elastic Stack resources. When provisioning monitoring resources, we include an `provider = elasticstack.monitoring`
+attribute to target the intended deployment. Aliased providers can be configured on a per-resource or per-module basis.
+For more information consult the [documentation](https://developer.hashicorp.com/terraform/language/providers/configuration#alias-multiple-provider-configurations)
+
+```terraform
+# Creating a deployment on Elastic Cloud GCP region,
+# with elasticsearch and kibana components.
+
+resource "ec_deployment" "monitoring" {
+  region                 = "gcp-us-central1"
+  name                   = "my-monitoring-deployment"
+  version                = data.ec_stack.latest.version
+  deployment_template_id = "gcp-storage-optimized"
+
+  elasticsearch {}
+  kibana {}
+}
+
+resource "ec_deployment" "cluster" {
+  region                 = "gcp-us-central1"
+  name                   = "mydeployment"
+  version                = data.ec_stack.latest.version
+  deployment_template_id = "gcp-storage-optimized"
+
+  observability {
+    deployment_id = ec_deployment.monitoring.id
+    ref_id        = ec_deployment.monitoring.elasticsearch[0].ref_id
+  }
+
+  elasticsearch {}
+
+  kibana {}
+}
+
+data "ec_stack" "latest" {
+  version_regex = "latest"
+  region        = "gcp-us-central1"
+}
+
+provider "elasticstack" {
+  # Use our Elastic Cloud deployment outputs for connection details.
+  # This also allows the provider to create the proper relationships between the two resources.
+  elasticsearch {
+    endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"]
+    username  = ec_deployment.cluster.elasticsearch_username
+    password  = ec_deployment.cluster.elasticsearch_password
+  }
+}
+
+provider "elasticstack" {
+  # Use our Elastic Cloud deployment outputs for connection details.
+  # This also allows the provider to create the proper relationships between the two resources.
+  elasticsearch {
+    endpoints = ["${ec_deployment.monitoring.elasticsearch[0].https_endpoint}"]
+    username  = ec_deployment.monitoring.elasticsearch_username
+    password  = ec_deployment.monitoring.elasticsearch_password
+  }
+  alias = "monitoring"
+}
+
+# Defining a user for ingesting
+resource "elasticstack_elasticsearch_security_user" "user" {
+  username = "ingest_user"
+
+  # Password is cleartext here for comfort, but there's also a hashed password option
+  password = "mysecretpassword"
+  roles    = ["editor"]
+
+  # Set the custom metadata for this user
+  metadata = jsonencode({
+    "env"    = "testing"
+    "open"   = false
+    "number" = 49
+  })
+}
+
+# Configuring my cluster with an index template as well.
+resource "elasticstack_elasticsearch_index_template" "my_template" {
+  name = "my_ingest_1"
+
+  priority       = 42
+  index_patterns = ["server-logs*"]
+
+  template {
+    alias {
+      name = "my_template_test"
+    }
+
+    settings = jsonencode({
+      number_of_shards = "3"
+    })
+
+    mappings = jsonencode({
+      properties : {
+        "@timestamp" : { "type" : "date" },
+        "username" : { "type" : "keyword" }
+      }
+    })
+  }
+}
+
+# Defining a user for viewing monitoring
+resource "elasticstack_elasticsearch_security_user" "monitoring_user" {
+  # Explicitly select the monitoring provider here
+  provider = elasticstack.monitoring
+
+  username = "monitoring_viewer"
+
+  # Password is cleartext here for comfort, but there's also a hashed password option
+  password = "mysecretpassword"
+  roles    = ["reader"]
+
+  # Set the custom metadata for this user
+  metadata = jsonencode({
+    "env"    = "testing"
+    "open"   = false
+    "number" = 49
+  })
+}
+```
diff --git a/docs/resources/elasticsearch_cluster_settings.md b/docs/resources/elasticsearch_cluster_settings.md
@@ -51,7 +51,7 @@ resource "elasticstack_elasticsearch_cluster_settings" "my_cluster_settings" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `persistent` (Block List, Max: 1) Settings will apply across restarts. (see [below for nested schema](#nestedblock--persistent))
 - `transient` (Block List, Max: 1) Settings do not survive a full cluster restart. (see [below for nested schema](#nestedblock--transient))
 

diff --git a/docs/resources/elasticsearch_component_template.md b/docs/resources/elasticsearch_component_template.md
@@ -49,7 +49,7 @@ resource "elasticstack_elasticsearch_index_template" "my_template" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `metadata` (String) Optional user metadata about the component template.
 - `version` (Number) Version number used to manage component templates externally.
 

diff --git a/docs/resources/elasticsearch_data_stream.md b/docs/resources/elasticsearch_data_stream.md
@@ -74,7 +74,7 @@ resource "elasticstack_elasticsearch_data_stream" "my_data_stream" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 
 ### Read-Only
 

diff --git a/docs/resources/elasticsearch_index.md b/docs/resources/elasticsearch_index.md
@@ -75,7 +75,7 @@ resource "elasticstack_elasticsearch_index" "my_index" {
 - `blocks_write` (Boolean) Set to `true` to disable data write operations against the index. This setting does not affect metadata.
 - `codec` (String) The `default` value compresses stored data with LZ4 compression, but this can be set to `best_compression` which uses DEFLATE for a higher compression ratio. This can be set only on creation.
 - `default_pipeline` (String) The default ingest node pipeline for this index. Index requests will fail if the default pipeline is set and the pipeline does not exist.
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `final_pipeline` (String) Final ingest pipeline for the index. Indexing requests will fail if the final pipeline is set and the pipeline does not exist. The final pipeline always runs after the request pipeline (if specified) and the default pipeline (if it exists). The special pipeline name _none indicates no ingest pipeline will run.
 - `gc_deletes` (String) The length of time that a deleted document's version number remains available for further versioned operations.
 - `highlight_max_analyzed_offset` (Number) The maximum number of characters that will be analyzed for a highlight request.

diff --git a/docs/resources/elasticsearch_index_lifecycle.md b/docs/resources/elasticsearch_index_lifecycle.md
@@ -64,7 +64,7 @@ resource "elasticstack_elasticsearch_index_lifecycle" "my_ilm" {
 
 - `cold` (Block List, Max: 1) The index is no longer being updated and is queried infrequently. The information still needs to be searchable, but it’s okay if those queries are slower. (see [below for nested schema](#nestedblock--cold))
 - `delete` (Block List, Max: 1) The index is no longer needed and can safely be removed. (see [below for nested schema](#nestedblock--delete))
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `frozen` (Block List, Max: 1) The index is no longer being updated and is queried rarely. The information still needs to be searchable, but it’s okay if those queries are extremely slow. (see [below for nested schema](#nestedblock--frozen))
 - `hot` (Block List, Max: 1) The index is actively being updated and queried. (see [below for nested schema](#nestedblock--hot))
 - `metadata` (String) Optional user metadata about the ilm policy. Must be valid JSON document.

diff --git a/docs/resources/elasticsearch_index_template.md b/docs/resources/elasticsearch_index_template.md
@@ -57,7 +57,7 @@ resource "elasticstack_elasticsearch_index_template" "my_data_stream" {
 
 - `composed_of` (List of String) An ordered list of component template names.
 - `data_stream` (Block List, Max: 1) If this object is included, the template is used to create data streams and their backing indices. Supports an empty object. (see [below for nested schema](#nestedblock--data_stream))
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `metadata` (String) Optional user metadata about the index template.
 - `priority` (Number) Priority to determine index template precedence when a new data stream or index is created.
 - `template` (Block List, Max: 1) Template to be applied. It may optionally include an aliases, mappings, or settings configuration. (see [below for nested schema](#nestedblock--template))

diff --git a/docs/resources/elasticsearch_ingest_pipeline.md b/docs/resources/elasticsearch_ingest_pipeline.md
@@ -81,7 +81,7 @@ resource "elasticstack_elasticsearch_ingest_pipeline" "ingest" {
 ### Optional
 
 - `description` (String) Description of the ingest pipeline.
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `metadata` (String) Optional user metadata about the index template.
 - `on_failure` (List of String) Processors to run immediately after a processor failure. Each processor supports a processor-level `on_failure` value. If a processor without an `on_failure` value fails, Elasticsearch uses this pipeline-level parameter as a fallback. The processors in this parameter run sequentially in the order specified. Elasticsearch will not attempt to run the pipeline’s remaining processors. See: https://www.elastic.co/guide/en/elasticsearch/reference/current/processors.html. Each record must be a valid JSON document
 

diff --git a/docs/resources/elasticsearch_logstash_pipeline.md b/docs/resources/elasticsearch_logstash_pipeline.md
@@ -66,7 +66,7 @@ output "pipeline" {
 ### Optional
 
 - `description` (String) Description of the pipeline.
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `pipeline_batch_delay` (Number) Time in milliseconds to wait for each event before sending an undersized batch to pipeline workers.
 - `pipeline_batch_size` (Number) The maximum number of events an individual worker thread collects before executing filters and outputs.
 - `pipeline_ecs_compatibility` (String) Sets the pipeline default value for ecs_compatibility, a setting that is available to plugins that implement an ECS compatibility mode for use with the Elastic Common Schema.

diff --git a/docs/resources/elasticsearch_script.md b/docs/resources/elasticsearch_script.md
@@ -54,7 +54,7 @@ resource "elasticstack_elasticsearch_script" "my_search_template" {
 ### Optional
 
 - `context` (String) Context in which the script or search template should run.
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `params` (String) Parameters for the script or search template.
 
 ### Read-Only

diff --git a/docs/resources/elasticsearch_security_api_key.md b/docs/resources/elasticsearch_security_api_key.md
@@ -56,7 +56,7 @@ output "api_key" {
 
 ### Optional
 
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `expiration` (String) Expiration time for the API key. By default, API keys never expire.
 - `metadata` (String) Arbitrary metadata that you want to associate with the API key.
 - `role_descriptors` (String) Role descriptors for this API key.

diff --git a/docs/resources/elasticsearch_security_role.md b/docs/resources/elasticsearch_security_role.md
@@ -55,7 +55,7 @@ output "role" {
 
 - `applications` (Block Set) A list of application privilege entries. (see [below for nested schema](#nestedblock--applications))
 - `cluster` (Set of String) A list of cluster privileges. These privileges define the cluster level actions that users with this role are able to execute.
-- `elasticsearch_connection` (Block List, Max: 1) Elasticsearch connection configuration block. (see [below for nested schema](#nestedblock--elasticsearch_connection))
+- `elasticsearch_connection` (Block List, Max: 1, Deprecated) Elasticsearch connection configuration block. This property will be removed in a future provider version. Configure the Elasticsearch connection via the provider configuration instead. (see [below for nested schema](#nestedblock--elasticsearch_connection))
 - `global` (String) An object defining global privileges.
 - `indices` (Block Set) A list of indices permissions entries. (see [below for nested schema](#nestedblock--indices))
 - `metadata` (String) Optional meta-data.