WMS #11649: New lab for nosql - Use Terraform to Create and Modify Ta…

…bles in Oracle NoSQL Database Cloud Service (#722)

* adding new workshop for nosql

* fix review comments

* fix review comments

* add note

* Updates to Learn more

* lintchecker fixes

* minor edits

* updated links

create-nosqltables-terraform/create-api-signing-keys/create-api-signing-keys.md

@@ -0,0 +1,128 @@
+# Create an API Sign-In Key (Optional)
+
+## Introduction
+
+This lab walks you through the steps to create a API signing key for an Oracle Cloud user account.
+
+Complete this lab if you want to use API Keys for authentication. You can skip this lab (and proceed to [Lab 2](?lab=create-singleton-tables)) if you plan to use any other form of authentication like Instance Principal Authentication, Resource Principal Authentication or Security Token Authentication.
+
+Estimated Lab Time: 10 minutes
+
+### Objectives
+
+Any software client you use to connect to Oracle Cloud Infrastructure must be configured with the following information:
+* An API Signing Key
+* The fingerprint of the public key
+* Your tenancy's Oracle Cloud Identifier (OCID)
+* The OCID of your user account
+
+### Prerequisites
+
+*  An Oracle Free Tier, Always Free, Paid or LiveLabs Cloud Account
+* [Git Bash Shell](https://gitforwindows.org/) (Windows)
+* Download an Oracle NoSQL Database SDK
+
+## Task 1: Record your tenancy and user OCID
+
+1. Create a note file on your local system to record the following information:
+
+    - Tenancy OCID
+    - User OCID
+    - API Key Fingerprint
+    - API Key Passphrase
+
+2. Click the **Navigation Menu** in the upper left, navigate to **Governance & Administration**, and select **Tenancy Details**.
+
+	![Tenancy Details](https://oracle-livelabs.github.io/common/images/console/admin-details.png " ")
+
+3. The Tenancy Details page shows information about your cloud account. Copy the Tenancy OCID by clicking on the **Copy** link next to it. Save the value in your note file.
+
+  ![Copy Tenancy OCID](images/copy-tenancy-ocid.png)
+
+4. In the top-right corner of the Console, open the Profile menu (User menu icon) and then click **User Settings** to view the details.
+
+  ![User Settings](images/user-settings.png)
+
+5. Click Copy beside the (User) OCID save it to your note file.
+
+  ![Copy OCID](images/copy-user-ocid.png)
+
+## Task 2: Generate an API Sign-In Key
+
+To create a user API key, you will use `openssl` on your local system. If you are using Windows, we recommend the Git Bash Shell.
+
+  *Note: To paste in Git Bash Shell right click in the window and click paste(Ctrl + V does not work in the shell).*
+
+1. Create a `~/.oci` directory:
+
+    *Note: if you already have a .oci directory, you can skip this step.*
+
+    ```
+    <copy>mkdir ~/.oci</copy>
+    ```
+
+    ![Create Directory](images/mkdir-oci.png)
+
+2. Generate a private key with the following command. On Windows, you will not see a prompt for a passphrase, but you should use one that you can remember. Be sure to make a note of the passphrase you enter, as you will need it later.
+
+    ```
+    <copy>openssl genrsa -out ~/.oci/oci_api_key_private.pem -aes128 -passout stdin 2048</copy>
+    ```
+
+    ![Generate a private key](images/create-pem-key.png)
+
+3. Confirm that the private key file has been created in the directory you specified using the following command.
+
+    ```
+    <copy>ls -l ~/.oci</copy>
+    ```
+
+    ![Check private key](images/check-pem-key.png)
+
+4. Change permissions on the file to ensure that only you can read it.
+
+    ```
+    <copy>chmod go-rwx ~/.oci/oci_api_key_private.pem</copy>
+    ```
+
+    ![Change file permission](images/change-permissions.png)
+
+5. Generate a public key in the same location as the private key file using the following command. Enter the same passphrase you previously used to encrypt the private key file. *Note: there is no prompt on Windows.*
+
+    ```
+    <copy>openssl rsa -pubout -in ~/.oci/oci_api_key_private.pem -out ~/.oci/oci_api_key_public.pem -passin stdin</copy>
+    ```
+
+    ![Generate public key](images/generate-public-key.png)
+
+6. Confirm that the public key file has been created in the directory you specified.
+
+    ```
+    <copy>ls -l ~/.oci</copy>
+    ```
+
+7. Having created the API key pair, upload the public key value to Oracle Cloud Infrastructure. In the top-right corner of the Console, open the Profile menu again and then click **User Settings** to view the details.
+
+  ![View User Settings](images/user-settings.png)
+
+8. On the API Keys page, click **Add Public Key**.
+
+  ![Add Public key](images/add-public-key.png)
+
+9. Click **select one** and navigate to your `~/.oci` directory, and select the `oci_api_key_public.pem` file. Click **Add**.
+
+  ![Add API Key](images/upload-public-key.png)
+
+10. Save the fingerprint value to your note file, as you will use the fingerprint later.
+
+  ![Save fingerprint value](images/copy-fingerprint.png)
+
+You may proceed to the next lab.
+
+## Learn More
+
+* [Authentication to connect to Oracle NoSQL Database](https://docs.oracle.com/en/cloud/paas/nosql-cloud/dtddt/index.html#DTDDT-GUID-B09F1A47-98E4-4F02-AB23-5D4284F481F4)
+
+## Acknowledgements
+* **Author** - Dave Rubin, Senior Director, NoSQL and Embedded Database Development and Michael Brey, Director, NoSQL Product Development
+* **Last Updated By/Date** - Vandana Rajamani, Database User Assistance, November 2024

create-nosqltables-terraform/create-gat-tables/create-gat-tables.md

@@ -0,0 +1,147 @@
+# Create Global Active tables using Terraform
+
+## Introduction
+
+This lab walks you through the steps to create a Global Active table (GAT) using Terraform.
+
+Estimated Lab Time: 15 Minutes
+
+### About Global Active tables
+
+Oracle NoSQL Database Cloud Service supports a global active table architecture in which you can create tables, replicate them across multiple regions, and maintain synchronized data across the regional replicas. Today's businesses need to provide faster and better services to their customers. Network latency is a crucial parameter for assessing the performance of any application. Users expect to complete their online activities smoothly and quickly from anywhere. To meet such expectations, enterprises need to host applications and data in distributed regions closest to their users. Oracle NoSQL Database Cloud Service provides a solution to these requirements through Global Active tables. This feature enables application data written in a region to be replicated transparently across multiple regions.
+
+### Prerequisites
+
+*  An Oracle Free Tier, Always Free, Paid or LiveLabs Cloud Account
+*  Successful completion of [Lab 1 : Create an API Sign-In Key ](?lab=create-api-signing-keys)
+* Successful completion of [Lab 2 : Create singleton tables using Terraform](?lab=create-singleton-tables)
+
+It is easy to deploy a Global Active table on OCI using Terraform. In [Lab 2 : Create singleton tables using Terraform](?lab=create-singleton-tables), you have created a singleton table called **nosql_demo**. In this lab, you will create a regional replica of this table and make it a Global Active table.
+
+## Task 1:  Create NoSQL Terraform configuration file
+Resources are the most important element in the Terraform language. Terraform creates a NoSQL table and a table replica as a resource. The NoSQL Terraform configuration file will define the resources to be created. In this lab the resources created are a NoSQL table and a table replica.
+
+When you create a Global Active table:
+* The table should contain at least one JSON column.
+* The table DDL definition must include **with schema frozen** clause.
+
+When you add a regional table replica, you can either specify the name of the table or the OCID of the table. If you specify the name of the table, then you need to specify the OCID of your compartment and the **depends\_on** clause while defining the regional replica as shown below. If you are specifying the OCID of the table, then **depends_on** clause, and compartment OCID is optional.
+
+You create a new file named **nosql.tf** that contains the NoSQL terraform configuration resources for creating NoSQL Database Cloud Service tables.
+In the example below, you are creating a table **nosql_demo** with a json column and schema frozen. You then add a regional replica to the table and make it a Global Active table.
+
+```
+<copy>
+variable "compartment_ocid" {
+}
+
+variable "table_ddl_statement" {
+  default = "CREATE TABLE IF NOT EXISTS nosql_dem0(id INTEGER,
+                            name STRING, info JSON,PRIMARY KEY(id))
+                            using TTL 10 days with schema frozen"
+}
+
+resource "oci_nosql_table" "nosql_demo" {
+  #Required
+  compartment_id = var.compartment_ocid
+  ddl_statement  = var.table_ddl_statement
+  name           = "nosql_demo"
+
+  table_limits {
+    #Required
+    max_read_units = 51
+    max_write_units = 51
+    max_storage_in_gbs = 2     
+  }
+}
+#add a regional replica
+resource "oci_nosql_table_replica" "replica_montreal" {
+  table_name_or_id = oci_nosql_table.nosql_demo.id
+  region = "ca-montreal-1"
+  #Optional
+  max_read_units     = "60"
+  max_write_units    = "60"
+}
+</copy>
+```
+*Note: The definition of the singleton table (CREATE TABLE IF NOT EXISTS nosql\_demo...) must always be included in the terraform script even if the table (nosql\_demo) already exists. If the table already exists, Terraform compares the existing definition of the table to the new definition in the script. If there are no changes, the CREATE TABLE definition is ignored. If there are any changes to the definition, the terraform script overwrites the existing definition of the table with the new script (This is equivalent to an ALTER TABLE statement).If you do not include the CREATE TABLE definition in the script and terraform sees the table existing, then terraform drops the table from the  existing region.*
+
+## Task 2:  Use terraform to run the scripts
+
+Save the config file created above in the same folder where Terraform is installed.
+Invoke terraform and initialize the setup.
+```
+<copy>
+terraform init
+</copy>
+```
+Run the following command to invoke the terraform script.
+```
+<copy>
+terraform apply
+</copy>
+```
+Terraform shows the plan to be applied and prompts for confirmation as shown below.
+```
+<copy>
+An execution plan has been generated and is shown below.
+Resource actions are indicated with the following symbols: + create
+
+Terraform will perform the following actions:
+# oci_nosql_table.nosql_demo will be created
+
+ + resource "oci_nosql_table" "nosql_demo" {
+     + compartment_id                          = "<COMPARTMENT_ID>"
+     + ddl_statement                           = "CREATE TABLE IF NOT EXISTS nosql_demo(id INTEGER, name STRING, info JSON, PRIMARY KEY(id)) with schema frozen"
+     + defined_tags                            = (known after apply)
+     + freeform_tags                           = (known after apply)
+     + id                                      = (known after apply)
+     + is_auto_reclaimable                     = (known after apply)
+     + is_multi_region                         = (known after apply)
+     + lifecycle_details                       = (known after apply)
+     + local_replica_initialization_in_percent = (known after apply)
+     + name                                    = "nosql_demo"
+     + replicas                                = (known after apply)
+     + schema                                  = (known after apply)
+     + schema_state                            = (known after apply)
+     + state                                   = (known after apply)
+     + system_tags                             = (known after apply)
+     + time_created                            = (known after apply)
+     + time_of_expiration                      = (known after apply)
+     + time_updated                            = (known after apply)
+
+     + table_limits {
+         + capacity_mode      = (known after apply)
+         + max_read_units     = 60
+         + max_storage_in_gbs = 1
+         + max_write_units    = 60
+      }
+   }
+
+ # oci_nosql_table_replica.replica_yul will be created
+ + resource "oci_nosql_table_replica" "replica_yul" {
+     + compartment_id   = (known after apply)
+     + id               = (known after apply)
+     + max_read_units   = (known after apply)
+     + max_write_units  = (known after apply)
+     + region           = "ca-montreal-1"
+     + table_name_or_id = (known after apply)
+   }
+
+Do you want to perform these actions?
+Terraform will perform the actions described above.
+Only 'yes' will be accepted to approve.
+<copy>
+```
+On confirmation, a regional replica of the *nosql_demo* table is created, converting the singleton table to a GAT.
+
+You may proceed to the next lab.
+
+## Learn More
+
+* [Global Active Tables in NDCS](https://docs.oracle.com/en/cloud/paas/nosql-cloud/gasnd/)
+* [Table Replica Resource in Terraform](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/nosql_table_replica)
+
+## Acknowledgements
+* **Author** - Vandana Rajamani, Consulting UA Developer, DB Cloud Technical Svcs & User Assistance
+* **Last Updated By/Date** - Vandana Rajamani, Consulting UA Developer, DB Cloud Technical Svcs & User Assistance, November 2024