[AV-87721] GSI release documentation for Terraform V1.4.0 #244

a-atri · 2024-11-21T09:49:31Z

Jira

AV-87721

Description

Release documentation of GSI for terraform version V1.4.0

Type of Change

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR.
This change requires a documentation update
Documentation fix/enhancement

Manual Testing Approach

How was this change tested and do you have evidence? (REQUIRED: Select at least 1)

Manually tested
Unit tested
Acceptance tested
Unable to test / will not test (Please provide comments in section below)

Testing

Required Checklist:

I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if required)
I have run make fmt and formatted my code
I have made sure that no schema field is marked with both requiresReplace and computed

Further comments

simon-dew

A few comments

docs/guides/1.4.0-upgrade-guide.md

docs/index.md

simon-dew · 2024-11-21T15:23:19Z

examples/gsi/deferred/README.md

+
+This example shows how to create secondary indexes on a Capella cluster.
+
+This creates 5 deferred indexes in test.test.test.  Deferred indexes are best suited for large indexes, or when creating many indexes.


Maybe spell it out?

Suggested change

This creates 5 deferred indexes in test.test.test. Deferred indexes are best suited for large indexes, or when creating many indexes.

This creates 5 deferred indexes in a collection called `test`, which is located in a scope called `test` within a bucket also called `test`. Deferred indexes are best suited for large indexes, or when creating many indexes.

In addition to what Simon indicated - which is providing the clarify - I though we had discussed this previously and we we were going to use more meaningful names and not just test, test, test - at very laest "mybucket", "myscope" and "mycollection"

Also many indexes to multiple indexes. (Essentially, since we can't give a number, we can leave it as plural)

I updated the examples yesterday so this is outdated. Please see:
https://github.com/couchbasecloud/terraform-provider-couchbase-capella/blob/7147d366f6fffee59b4772e16bf910e33dc9e680/examples/gsi/deferred/README.md

The intro now says:

This example shows how to create secondary indexes on a Capella cluster. This creates 5 deferred indexes in api.metrics.memory Deferred indexes are best suited for large indexes (like partitioned indexes), or when creating many indexes. When in doubt, use deferred indexes :) If creating indexes in bulk, it is strongly recommended to build indexes in batches of 100 or less. To run configure your Couchbase Capella provider as described in README in the root of this project.

examples/gsi/deferred/README.md

simon-dew · 2024-11-21T15:32:06Z

examples/gsi/non_deferred/README.md

+
+This example shows how to create secondary indexes on a Capella cluster.
+
+This creates 5 non-deferred indexes in test.test.test.  Non-deferred indexes are best suited when creating small indexes.


Again, maybe spell it out?

Suggested change

This creates 5 non-deferred indexes in test.test.test. Non-deferred indexes are best suited when creating small indexes.

This creates 5 non-deferred indexes in a collection called `test`, which is located in a scope called `test` within a bucket also called `test`. Non-deferred indexes are best suited when creating small indexes.

This is outdated. Please see:
https://github.com/couchbasecloud/terraform-provider-couchbase-capella/tree/7147d366f6fffee59b4772e16bf910e33dc9e680/examples/gsi/non_deferred

The intro now says:

This example shows how to create secondary indexes on a Capella cluster. This creates 1 non-deferred indexes in api.metrics.memory. Non-deferred indexes are best suited when creating 1 small index. To run configure your Couchbase Capella provider as described in README in the root of this project.

examples/gsi/non_deferred/README.md

simon-dew · 2024-11-21T15:36:31Z

examples/gsi/non_deferred/README.md

+### Ensure you create indexes.json which is a file with indexes
+### Place this file in the same directory as the terraform script.


As before, I don't like misusing the heading semantics just for emphasis.

Suggested change

### Ensure you create indexes.json which is a file with indexes

### Place this file in the same directory as the terraform script.

**Ensure you create `indexes.json`, which is a file with indexes.**

**Place this file in the same directory as the terraform script.**

rajagp · 2024-11-21T23:42:14Z

docs/index.md

@@ -306,3 +306,7 @@ To get started, see the [Provider Example Configs](https://github.com/couchbasec

  Manage Flush Bucket

+* [Manage GSI](https://github.com/couchbasecloud/terraform-provider-couchbase-capella/tree/main/examples/gsi)
+
+  Manage GSI


@l0n3star Tagging in reference to discussion on slack thread. Tagging here so we don't miss

@a-atri @simon-dew

please note I made significant updates (yesterday) to the non-deferred and deferred examples for several reasons. first, had to include output showing index status. this is priority for priya and request came in 2 days ago. second, updated the examples to give better guidance to users. in particular, we should encourages users to create 1 non-deferred index. third, priya wanted to use different bucket/scope/collection names to make it more user friendly.

please reference updated examples below:
https://github.com/couchbasecloud/terraform-provider-couchbase-capella/tree/7147d366f6fffee59b4772e16bf910e33dc9e680/examples/gsi

rajagp · 2024-11-21T23:43:09Z

examples/getting_started/README.md

@@ -19,6 +19,7 @@ In this demo, we will perform the following operations:
 15. Create a new audit log settings.
 16. Enable private endpoint service on the cluster.
 17. Create a new network peer.
+18. Create an index.


What kind of index? GSI and deferred or non-deferred?

It's partitioned index (non-deferred).

Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com>

l0n3star · 2024-12-04T16:40:54Z

docs/guides/1.4.0-upgrade-guide.md

+locals {
+  index_template = templatefile("${path.module}/indexes.json", {
+    organization_id = var.organization_id
+    project_id      = var.project_id
+    cluster_id      = var.cluster_id
+  })
+}
+```
+```
+resource "couchbase-capella_query_indexes" "new_indexes" {
+  for_each        = jsondecode(local.index_template).resource["couchbase-capella_indexes"]
+  organization_id = each.value.organization_id
+  project_id      = each.value.project_id
+  cluster_id      = each.value.cluster_id
+  bucket_name     = each.value.bucket_name
+  scope_name      = each.value.scope_name
+  collection_name = each.value.collection_name
+  index_name      = each.value.index_name
+  index_keys      = each.value.index_keys
+}
+```


We should encourage customers to only create 1 non-deferred index. Testing shows creating multiple non-deferred indexes is problematic. So please change to :

resource "couchbase-capella_query_indexes" "idx" { organization_id = var.organization_id project_id = var.project_id cluster_id = var.cluster_id bucket_name = var.bucket_name scope_name = var.scope_name collection_name = var.collection_name index_name = var.index_name index_keys = var.index_keys } output "idx" { value = couchbase-capella_query_indexes.idx }

l0n3star · 2024-12-04T16:48:13Z

examples/gsi/deferred/create_indexes.tf

This sample config is updated. Please see:
https://github.com/couchbasecloud/terraform-provider-couchbase-capella/blob/7147d366f6fffee59b4772e16bf910e33dc9e680/examples/gsi/deferred/create_indexes.tf

l0n3star · 2024-12-04T16:50:44Z

examples/gsi/non_deferred/indexes.json

This file no longer needed for non-deferred example.

Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com>

… team Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com>

We have updated this description

nishant-tripathy

LGTM

l0n3star added 30 commits September 11, 2024 21:06

api structs

1357aae

terraform structs

ff757ad

query index resource

5b9b6ad

implement ResourceWithValidateConfig

dd7fddd

refactor query index resource

7748ae0

query index datasource

1e32130

query index monitor datasource

3874e44

cleanup

db5f07e

fix list indexes

7b54667

fix import

b5239ff

documentation

5f43574

documentation

7d7a78a

add . to end of comments

6b32b38

handle build in progress

9589750

update example

b6ca35d

type assertion must be checked

582b6cc

update terraform.template.tfvars in example

ba0cd42

update variables in example

d9d93ec

use ValueString() for Where field

408546e

set state once

1292df8

remove resource from state file if externally deleted

26d86fa

imports

70a5e6d

poll index

e26e82e

refactor query_index_monitor

cff6e19

fix typo

605985c

fix index build validation

83f5524

watch indexes

158b509

remove listStringValues

a2673d0

do not poll on build in progress error

eb801d4

mark resource with buid in progress error as tainted

6a7597f

Release documetation for GSI

52af5fe

a-atri requested review from a team as code owners November 21, 2024 09:49

a-atri requested review from rajagp and simon-dew November 21, 2024 14:07

simon-dew previously requested changes Nov 21, 2024

View reviewed changes

rajagp reviewed Nov 21, 2024

View reviewed changes

Updating docs based on the changes requested by the docs team

0375a68

Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com>

l0n3star reviewed Dec 4, 2024

View reviewed changes

examples/gsi/non_deferred/indexes.json Outdated

Copy link

Contributor

l0n3star Dec 4, 2024 •

edited

Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file no longer needed for non-deferred example.

l0n3star and others added 16 commits December 5, 2024 14:03

fix panic on read

89e6ce7

change schema defaults

2f2142b

set num_replica in state file

0ff4723

manually refresh state on concurrent index creation requests

9746681

adding acceptance tests

7847f35

update comment

d157a88

update README

83afb62

return warning for concurrent index creation

58e61ac

index status

9eedb3d

comment out undefined function in acc test

9a13a63

update non deferred example

37d5e2b

update deferred example

adeda6d

make tffmt

337148a

merged updated gsi branch into documentation branch

7bfc147

Updating docs based on the changes requested by the docs team

7847c0c

Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com>

Updating the description based on the feedback received from the docs…

31ebb9c

… team Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com>

nishant-tripathy approved these changes Dec 5, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[AV-87721] GSI release documentation for Terraform V1.4.0 #244

[AV-87721] GSI release documentation for Terraform V1.4.0 #244

a-atri commented Nov 21, 2024 •

edited

Loading

simon-dew left a comment •

edited

Loading

simon-dew Nov 21, 2024

rajagp Nov 21, 2024 •

edited

Loading

rajagp Nov 21, 2024

l0n3star Dec 4, 2024

simon-dew Nov 21, 2024

l0n3star Dec 4, 2024

simon-dew Nov 21, 2024

rajagp Nov 21, 2024

l0n3star Dec 4, 2024 •

edited

Loading

rajagp Nov 21, 2024

l0n3star Dec 4, 2024

l0n3star Dec 4, 2024

l0n3star Dec 4, 2024

l0n3star Dec 4, 2024 •

edited

Loading

nishant-tripathy left a comment


		This example shows how to create secondary indexes on a Capella cluster.

		This creates 5 deferred indexes in test.test.test. Deferred indexes are best suited for large indexes, or when creating many indexes.

	This creates 5 deferred indexes in test.test.test. Deferred indexes are best suited for large indexes, or when creating many indexes.
	This creates 5 deferred indexes in a collection called `test`, which is located in a scope called `test` within a bucket also called `test`. Deferred indexes are best suited for large indexes, or when creating many indexes.


		This example shows how to create secondary indexes on a Capella cluster.

		This creates 5 non-deferred indexes in test.test.test. Non-deferred indexes are best suited when creating small indexes.

	This creates 5 non-deferred indexes in test.test.test. Non-deferred indexes are best suited when creating small indexes.
	This creates 5 non-deferred indexes in a collection called `test`, which is located in a scope called `test` within a bucket also called `test`. Non-deferred indexes are best suited when creating small indexes.

		### Ensure you create indexes.json which is a file with indexes
		### Place this file in the same directory as the terraform script.

[AV-87721] GSI release documentation for Terraform V1.4.0 #244

Are you sure you want to change the base?

[AV-87721] GSI release documentation for Terraform V1.4.0 #244

Conversation

a-atri commented Nov 21, 2024 • edited Loading

Jira

Description

Type of Change

Manual Testing Approach

How was this change tested and do you have evidence? (REQUIRED: Select at least 1)

Testing

Required Checklist:

Further comments

simon-dew left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rajagp Nov 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

l0n3star Dec 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

l0n3star Dec 4, 2024 • edited Loading

Choose a reason for hiding this comment

nishant-tripathy left a comment

Choose a reason for hiding this comment

a-atri commented Nov 21, 2024 •

edited

Loading

simon-dew left a comment •

edited

Loading

rajagp Nov 21, 2024 •

edited

Loading

l0n3star Dec 4, 2024 •

edited

Loading

l0n3star Dec 4, 2024 •

edited

Loading