From 5a6741db98a5f45fbdaf76de8269bc9dc95dfc5a Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 12:47:34 +0200 Subject: [PATCH 1/8] added a stack & cloud provider guide --- docs/guides/elasticstack-and-cloud.md | 116 ++++++++++++++++++ examples/cloud/deployment.tf | 72 +++++++++++ examples/cloud/provider.tf | 23 ++++ .../guides/elasticstack-and-cloud.md.tmpl | 19 +++ 4 files changed, 230 insertions(+) create mode 100644 docs/guides/elasticstack-and-cloud.md create mode 100644 examples/cloud/deployment.tf create mode 100644 examples/cloud/provider.tf create mode 100644 templates/guides/elasticstack-and-cloud.md.tmpl diff --git a/docs/guides/elasticstack-and-cloud.md b/docs/guides/elasticstack-and-cloud.md new file mode 100644 index 000000000..c13f65051 --- /dev/null +++ b/docs/guides/elasticstack-and-cloud.md @@ -0,0 +1,116 @@ +--- +subcategory: "" +page_title: "Using the Elastic Stack provider with Elastic Cloud" +description: |- + An example of how to spin up a deployment and configure it in a single plan. +--- + +# + +A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deploymemnts. +in order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. +Start off by configuring the two providers 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.1.0" + } + } +} +provider "ec" { + # You can fill in your API key here, or use an environment variable instead + apikey = "" +} + +provider "elasticstack" { + # In this example, connectivity to Elasticsearch is defined per resource, + # so it can be used together with the Elastic Cloud terraform provider. +} +``` + +Notice that the elasticstack provider is not configured, since we'll be using an `elasticsearch_connection` block +for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. + +```terraform +# Creating a deployment on Elastic Cloud GCP region, +# with elasticsearch and kibana components. +resource "ec_deployment" "cluster" { + region = "gcp-us-central1" + name = "mydeployment" + version = data.ec_stack.latest.version + deployment_template_id = "gcp-storage-optimized" + + elasticsearch {} + + kibana {} +} + +data "ec_stack" "latest" { + version_regex = "latest" + region = "gcp-us-central1" +} + +# 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 + }) + + # Use our Elastic Cloud deployemnt outputs for connection details. + # This also allows the provider to create the proper relationships between the two resources. + elasticsearch_connection { + endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"] + username = "${ec_deployment.cluster.elasticsearch_username}" + password = "${ec_deployment.cluster.elasticsearch_password}" + } +} + +# 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 { + aliases { + name = "my_template_test" + } + + settings = jsonencode({ + number_of_shards = "3" + }) + + mappings = jsonencode({ + properties: { + "@timestamp": { "type": "date" }, + "username": {"type": "keyword" } + } + }) + } + + elasticsearch_connection { + endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"] + username = "${ec_deployment.cluster.elasticsearch_username}" + password = "${ec_deployment.cluster.elasticsearch_password}" + } +} +``` diff --git a/examples/cloud/deployment.tf b/examples/cloud/deployment.tf new file mode 100644 index 000000000..0a4a722cb --- /dev/null +++ b/examples/cloud/deployment.tf @@ -0,0 +1,72 @@ +# Creating a deployment on Elastic Cloud GCP region, +# with elasticsearch and kibana components. +resource "ec_deployment" "cluster" { + region = "gcp-us-central1" + name = "mydeployment" + version = data.ec_stack.latest.version + deployment_template_id = "gcp-storage-optimized" + + elasticsearch {} + + kibana {} +} + +data "ec_stack" "latest" { + version_regex = "latest" + region = "gcp-us-central1" +} + +# 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 + }) + + # Use our Elastic Cloud deployemnt outputs for connection details. + # This also allows the provider to create the proper relationships between the two resources. + elasticsearch_connection { + endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"] + username = ec_deployment.cluster.elasticsearch_username + password = ec_deployment.cluster.elasticsearch_password + } +} + +# 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 { + aliases { + name = "my_template_test" + } + + settings = jsonencode({ + number_of_shards = "3" + }) + + mappings = jsonencode({ + properties : { + "@timestamp" : { "type" : "date" }, + "username" : { "type" : "keyword" } + } + }) + } + + elasticsearch_connection { + endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"] + username = ec_deployment.cluster.elasticsearch_username + password = ec_deployment.cluster.elasticsearch_password + } +} diff --git a/examples/cloud/provider.tf b/examples/cloud/provider.tf new file mode 100644 index 000000000..ec03f6bff --- /dev/null +++ b/examples/cloud/provider.tf @@ -0,0 +1,23 @@ +terraform { + required_version = ">= 1.0.0" + + required_providers { + ec = { + source = "elastic/ec" + version = "~>0.3.0" + } + elasticstack = { + source = "elastic/elasticstack" + version = "~>0.1.0" + } + } +} +provider "ec" { + # You can fill in your API key here, or use an environment variable instead + apikey = "" +} + +provider "elasticstack" { + # In this example, connectivity to Elasticsearch is defined per resource, + # so it can be used together with the Elastic Cloud terraform provider. +} diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl new file mode 100644 index 000000000..84a63448a --- /dev/null +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -0,0 +1,19 @@ +--- +subcategory: "" +page_title: "Using the Elastic Stack provider with Elastic Cloud" +description: |- + An example of how to spin up a deployment and configure it in a single plan. +--- + +# + +A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deploymemnts. +in order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. +Start off by configuring the two providers in a `provider.tf` file for example: + +{{ tffile "examples/cloud/provider.tf" }} + +Notice that the elasticstack provider is not configured, since we'll be using an `elasticsearch_connection` block +for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. + +{{ tffile "examples/cloud/deployment.tf" }} From b6aa54ff9db18f755093112db8a361a653bbbb3b Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 13:45:01 +0200 Subject: [PATCH 2/8] some more details to guide --- docs/guides/elasticstack-and-cloud.md | 39 ++++++++++--------- .../guides/elasticstack-and-cloud.md.tmpl | 3 ++ 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/docs/guides/elasticstack-and-cloud.md b/docs/guides/elasticstack-and-cloud.md index c13f65051..9c00f4acf 100644 --- a/docs/guides/elasticstack-and-cloud.md +++ b/docs/guides/elasticstack-and-cloud.md @@ -17,11 +17,11 @@ terraform { required_providers { ec = { - source = "elastic/ec" - version = "~>0.3.0" + source = "elastic/ec" + version = "~>0.3.0" } elasticstack = { - source = "elastic/elasticstack" + source = "elastic/elasticstack" version = "~>0.1.0" } } @@ -40,12 +40,15 @@ provider "elasticstack" { Notice that the elasticstack provider is not configured, since we'll be using an `elasticsearch_connection` block for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. +Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic stack deployment on Elastic Cloud. +We shall configure the deployment using the credentials that it outputs once created + ```terraform # Creating a deployment on Elastic Cloud GCP region, # with elasticsearch and kibana components. resource "ec_deployment" "cluster" { region = "gcp-us-central1" - name = "mydeployment" + name = "mydeployment" version = data.ec_stack.latest.version deployment_template_id = "gcp-storage-optimized" @@ -78,8 +81,8 @@ resource "elasticstack_elasticsearch_security_user" "user" { # This also allows the provider to create the proper relationships between the two resources. elasticsearch_connection { endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"] - username = "${ec_deployment.cluster.elasticsearch_username}" - password = "${ec_deployment.cluster.elasticsearch_password}" + username = ec_deployment.cluster.elasticsearch_username + password = ec_deployment.cluster.elasticsearch_password } } @@ -87,7 +90,7 @@ resource "elasticstack_elasticsearch_security_user" "user" { resource "elasticstack_elasticsearch_index_template" "my_template" { name = "my_ingest_1" - priority = 42 + priority = 42 index_patterns = ["server-logs*"] template { @@ -95,22 +98,22 @@ resource "elasticstack_elasticsearch_index_template" "my_template" { name = "my_template_test" } - settings = jsonencode({ - number_of_shards = "3" - }) + settings = jsonencode({ + number_of_shards = "3" + }) - mappings = jsonencode({ - properties: { - "@timestamp": { "type": "date" }, - "username": {"type": "keyword" } - } - }) + mappings = jsonencode({ + properties : { + "@timestamp" : { "type" : "date" }, + "username" : { "type" : "keyword" } + } + }) } elasticsearch_connection { endpoints = ["${ec_deployment.cluster.elasticsearch[0].https_endpoint}"] - username = "${ec_deployment.cluster.elasticsearch_username}" - password = "${ec_deployment.cluster.elasticsearch_password}" + username = ec_deployment.cluster.elasticsearch_username + password = ec_deployment.cluster.elasticsearch_password } } ``` diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl index 84a63448a..5137f8ba2 100644 --- a/templates/guides/elasticstack-and-cloud.md.tmpl +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -16,4 +16,7 @@ Start off by configuring the two providers in a `provider.tf` file for example: Notice that the elasticstack provider is not configured, since we'll be using an `elasticsearch_connection` block for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. +Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic stack deployment on Elastic Cloud. +We shall configure the deployment using the credentials that it outputs once created + {{ tffile "examples/cloud/deployment.tf" }} From 4e2eff6328af01dc0b4cf4ef25653d3dcc042672 Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 14:22:01 +0200 Subject: [PATCH 3/8] Update templates/guides/elasticstack-and-cloud.md.tmpl Co-authored-by: Oleksandr --- templates/guides/elasticstack-and-cloud.md.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl index 5137f8ba2..0c888b8d7 100644 --- a/templates/guides/elasticstack-and-cloud.md.tmpl +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -13,7 +13,7 @@ Start off by configuring the two providers in a `provider.tf` file for example: {{ tffile "examples/cloud/provider.tf" }} -Notice that the elasticstack provider is not configured, since we'll be using an `elasticsearch_connection` block +Notice that the Elastic Stack provider is not configured, since we'll be using an `elasticsearch_connection` block for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic stack deployment on Elastic Cloud. From 82fd8f99d9a81426cec40fceca2a2062a18469de Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 14:22:15 +0200 Subject: [PATCH 4/8] Update templates/guides/elasticstack-and-cloud.md.tmpl Co-authored-by: Oleksandr --- templates/guides/elasticstack-and-cloud.md.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl index 0c888b8d7..a1a09ac1f 100644 --- a/templates/guides/elasticstack-and-cloud.md.tmpl +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -14,7 +14,7 @@ Start off by configuring the two providers in a `provider.tf` file for example: {{ tffile "examples/cloud/provider.tf" }} Notice that the Elastic Stack provider is not configured, since we'll be using an `elasticsearch_connection` block -for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. +for each of our resources, to point to the Elastic Cloud deployment. This is because `terraform` can not configure providers that are dependent on one another. Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic stack deployment on Elastic Cloud. We shall configure the deployment using the credentials that it outputs once created From 07bfd6ca5f2efbcca1ee6639596098a022a40569 Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 14:22:28 +0200 Subject: [PATCH 5/8] Update templates/guides/elasticstack-and-cloud.md.tmpl Co-authored-by: Oleksandr --- templates/guides/elasticstack-and-cloud.md.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl index a1a09ac1f..7d469d578 100644 --- a/templates/guides/elasticstack-and-cloud.md.tmpl +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -7,7 +7,7 @@ description: |- # -A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deploymemnts. +A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deployments. in order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. Start off by configuring the two providers in a `provider.tf` file for example: From 818dcb2637ca7ae6f708427049d11682c66a75c6 Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 14:22:40 +0200 Subject: [PATCH 6/8] Update templates/guides/elasticstack-and-cloud.md.tmpl Co-authored-by: Oleksandr --- templates/guides/elasticstack-and-cloud.md.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl index 7d469d578..66ca648cb 100644 --- a/templates/guides/elasticstack-and-cloud.md.tmpl +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -8,7 +8,7 @@ description: |- # A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deployments. -in order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. +In order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. Start off by configuring the two providers in a `provider.tf` file for example: {{ tffile "examples/cloud/provider.tf" }} From 47b190ab48cfc9fbc34d5f4459e8b00b46f02484 Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 14:33:24 +0200 Subject: [PATCH 7/8] Update templates/guides/elasticstack-and-cloud.md.tmpl Co-authored-by: Oleksandr --- templates/guides/elasticstack-and-cloud.md.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/guides/elasticstack-and-cloud.md.tmpl b/templates/guides/elasticstack-and-cloud.md.tmpl index 66ca648cb..c3dbb6457 100644 --- a/templates/guides/elasticstack-and-cloud.md.tmpl +++ b/templates/guides/elasticstack-and-cloud.md.tmpl @@ -16,7 +16,7 @@ Start off by configuring the two providers in a `provider.tf` file for example: Notice that the Elastic Stack provider is not configured, since we'll be using an `elasticsearch_connection` block for each of our resources, to point to the Elastic Cloud deployment. This is because `terraform` can not configure providers that are dependent on one another. -Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic stack deployment on Elastic Cloud. +Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic Stack deployment on Elastic Cloud. We shall configure the deployment using the credentials that it outputs once created {{ tffile "examples/cloud/deployment.tf" }} From 25129def31628887348d8c36766c5ddafd9d43e6 Mon Sep 17 00:00:00 2001 From: Omer Kushmaro Date: Thu, 18 Nov 2021 15:06:11 +0200 Subject: [PATCH 8/8] regenerated docs after modifications --- docs/guides/elasticstack-and-cloud.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/elasticstack-and-cloud.md b/docs/guides/elasticstack-and-cloud.md index 9c00f4acf..2dacd3c01 100644 --- a/docs/guides/elasticstack-and-cloud.md +++ b/docs/guides/elasticstack-and-cloud.md @@ -7,8 +7,8 @@ description: |- # -A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deploymemnts. -in order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. +A common scenario for using the Elastic Stack provider, is to manage & configure Elastic Cloud deployments. +In order to do that, we'll use both the Elastic Cloud provider, as well as the Elastic Stack provider. Start off by configuring the two providers in a `provider.tf` file for example: ```terraform @@ -37,10 +37,10 @@ provider "elasticstack" { } ``` -Notice that the elasticstack provider is not configured, since we'll be using an `elasticsearch_connection` block -for each of our resources, to point to the elastic cloud deployment. This is because `terraform` can not configure providers that are dependent on one anoher. +Notice that the Elastic Stack provider is not configured, since we'll be using an `elasticsearch_connection` block +for each of our resources, to point to the Elastic Cloud deployment. This is because `terraform` can not configure providers that are dependent on one another. -Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic stack deployment on Elastic Cloud. +Next, we'll set up an Elastic Cloud `ec_deployment` resource, which represents an Elastic Stack deployment on Elastic Cloud. We shall configure the deployment using the credentials that it outputs once created ```terraform