chore(doc): move docs to guide folder (#50)

Signed-off-by: Yellow Shine <[email protected]>
zilliztech · Jan 7, 2025 · a1d403d · a1d403d
1 parent 5c621cf
commit a1d403d
Show file tree

Hide file tree

Showing 19 changed files with 628 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ For general information about Terraform, visit the [official website](https://ww
 
 ## User Guide
 
-See [Zilliz Cloud Terraform Integration Overview](./docs/README.md) for more information.
+See [Zilliz Cloud Terraform Integration Overview](./docs/guides/README.md) for more information.
 
 ## API Documentation
 

diff --git a/docs/README.md → docs/guides/README.md b/docs/README.md → docs/guides/README.md
diff --git a/docs/create-a-free-cluster.md → docs/guides/create-a-free-cluster.md b/docs/create-a-free-cluster.md → docs/guides/create-a-free-cluster.md
diff --git a/docs/create-a-serverless-cluster.md → docs/guides/create-a-serverless-cluster.md b/docs/create-a-serverless-cluster.md → docs/guides/create-a-serverless-cluster.md
diff --git a/docs/create-a-standard-cluster.md → docs/guides/create-a-standard-cluster.md b/docs/create-a-standard-cluster.md → docs/guides/create-a-standard-cluster.md
diff --git a/docs/get-start.md → docs/guides/get-start.md b/docs/get-start.md → docs/guides/get-start.md
diff --git a/docs/import-cluster.md → docs/guides/import-cluster.md b/docs/import-cluster.md → docs/guides/import-cluster.md
diff --git a/docs/list-project.md → docs/guides/list-project.md b/docs/list-project.md → docs/guides/list-project.md
diff --git a/docs/list-regions.md → docs/guides/list-regions.md b/docs/list-regions.md → docs/guides/list-regions.md
diff --git a/docs/scale-cluster.md → docs/guides/scale-cluster.md b/docs/scale-cluster.md → docs/guides/scale-cluster.md
diff --git a/templates/guides/README.md b/templates/guides/README.md
@@ -0,0 +1,22 @@
+## Terraform Integration Overview with Zilliz Cloud
+
+Terraform, an open-source infrastructure as code (IaC) tool by HashiCorp, empowers you to automate the provisioning and management of your cloud resources. 
+
+The Terraform provider for Zilliz Cloud acts as a bridge between Terraform and the Zilliz Cloud platform. This plugin seamlessly integrates Zilliz Cloud resources into your Terraform workflow, allowing you to manage them alongside your existing infrastructure using Terraform configurations.
+
+
+### Getting Started with Terraform and Zilliz Cloud
+
+This guide provides a comprehensive overview of using Terraform with Zilliz Cloud. Here are the resources to get you started:
+
+* **Installation**: Learn how to install the Zilliz Cloud Terraform provider and configure it within your Terraform project. Refer to the tutorial: [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md)
+* **Creating Cluster:** Discover how to define, provision, and manage Zilliz Cloud clusters using Terraform configurations. 
+    * Create Free Plan Clusters for learning, experimenting, and prototype: [Creating a Free Plan Cluster](./create-a-free-cluster.md)
+    * Create Serverless Plan Clusters designed for serverless applications with variable or infrequent traffic: [Creating a Serverless Plan Cluster](./create-a-serverless-cluster.md)
+    * Create Standard Plan Clusters with more resources for production workloads: [Creating a Standard Plan Cluster](./create-a-standard-cluster.md)
+* **Scaling Clusters**: Learn how to leverage Terraform to upgrade the compute unit size of your Zilliz Cloud clusters to meet changing workload demands: [Upgrading Zilliz Cloud Cluster Compute Unit Size with Terraform](./scale-cluster.md)
+* **Importing Existing Clusters**: Utilize Terraform to import existing Zilliz Cloud clusters into your Terraform state, enabling them to be managed alongside other infrastructure using Terraform configurations: [Import Existing Zilliz Cloud Cluster With Terraform](./import-cluster.md)
+* **Retrieving Cloud Region**: Retrieve region IDs for Zilliz Cloud clusters across various cloud providers using the `zillizcloud_regions` data source. This tutorial demonstrates how to list regions for AWS, GCP, and Azure: [Acquiring Region IDs for Zilliz Cloud Clusters](./list-regions.md)
+
+By leveraging Terraform and the Zilliz Cloud Terraform provider, you can streamline your Zilliz Cloud infrastructure management, promoting efficiency and consistency within your cloud deployments.
+
diff --git a/templates/guides/create-a-free-cluster.md b/templates/guides/create-a-free-cluster.md
@@ -0,0 +1,83 @@
+## Tutorial: Creating a Free Plan Cluster with Terraform
+
+This tutorial guides you through creating a basic **Free Plan** cluster in Zilliz Cloud using the `zillizcloud_cluster` resource within Terraform. Free Plan cluster is suitable for for learning experimenting, and prototype purposes.
+
+Check out the [Select the Right Cluster Plan](https://docs.zilliz.com/docs/select-zilliz-cloud-service-plans) for more information on the available plans.
+
+**You'll learn how to:**
+
+- Define a Free Plan cluster in Terraform configuration.
+- Review and apply changes to provision the cluster in Zilliz Cloud.
+- Verify the creation of your Zilliz Cloud cluster.
+
+### Prerequisites
+
+Before you begin, make sure you have completed the initial setup steps outlined in the [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md) guide. Additionally, ensure that you have the necessary permissions and access credentials to interact with the Zilliz Cloud API.
+
+### Creating a Cluster
+
+Append the following code to your `main.tf` file mentioned in the [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md) guide.
+
+
+```hcl
+
+data "zillizcloud_project" "default" {
+  # Fetching the default project information to be used in cluster provisioning
+}
+
+resource "zillizcloud_cluster" "free_plan_cluster" {
+  # Name for your cluster
+  cluster_name = "Cluster-01"
+  # ID of the default project retrieved from data source
+  project_id   = data.zillizcloud_project.default.id 
+}
+
+output "cluster_connect_address" {
+  value = zillizcloud_cluster.free_plan_cluster.connect_address
+}
+output "cluster_username" {
+  value = zillizcloud_cluster.free_plan_cluster.username
+}
+output "cluster_password" {
+  sensitive = true
+  value = zillizcloud_cluster.free_plan_cluster.password
+}
+```
+
+
+**Explanation:**
+
+- This configuration defines a `zillizcloud_cluster` resource named `free_plan_cluster`.
+- * `cluster_name`: Sets the name of your cluster (here, "Cluster-01").
+  * `project_id`: Retrieves the ID of the default project using the `data.zillizcloud_project.default.id` attribute.
+
+### Planning and Applying Changes
+
+Once you've defined the cluster resources, it's time to apply the changes to provision the Zilliz Cloud clusters. Navigate to your Terraform project directory and execute the following commands:
+
+```bash
+terraform apply -auto-approve
+
+Outputs:
+
+cluster_connect_address = "https://in03-559dde3b4b6de3a.api.gcp-us-west1.zillizcloud.com"
+cluster_username = "db_559dde3b4b6de3a"
+cluster_password = <sensitive>
+```
+
+**Note**: The `-auto-approve` flag avoids prompting for confirmation before applying the changes. Use caution, especially in production environments. It's recommended to thoroughly review the plan before applying.
+
+Terraform will orchestrate the creation of the specified clusters based on your configuration. Once the process is complete, Terraform will display the output values for the cluster's connection address, username, and password.
+
+### Verifying Provisioned Clusters
+
+After applying the changes, you can verify the provisioned Zilliz Cloud clusters either through the Zilliz Cloud dashboard. Ensure that the clusters are created with the desired configurations and are functioning as expected.
+
+## Destroying the Cluster(Optional)
+If you want to destroy the cluster, you can run the following command:
+```
+$ terraform destroy
+```
+
+## Next Steps
+- Explore creating a **Standard Plan** Cluster: [Creating a Standard Plan Cluster](./create-a-standard-cluster.md)
diff --git a/templates/guides/create-a-serverless-cluster.md b/templates/guides/create-a-serverless-cluster.md
@@ -0,0 +1,85 @@
+## Tutorial: Creating a Serverless Plan Cluster with Terraform
+
+This tutorial guides you through creating a **Serverless Plan** cluster in Zilliz Cloud using the `zillizcloud_cluster` resource within Terraform. Serverless Plan cluster is designed for serverless applications with variable or infrequent traffic.
+
+Check out the [Select the Right Cluster Plan](https://docs.zilliz.com/docs/select-zilliz-cloud-service-plans) for more information on the available plans.
+
+**You'll learn how to:**
+
+- Define a Serverless Plan cluster in Terraform configuration.
+- Review and apply changes to provision the cluster in Zilliz Cloud.
+- Verify the creation of your Zilliz Cloud cluster.
+
+### Prerequisites
+
+Before you begin, make sure you have completed the initial setup steps outlined in the [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md) guide. Additionally, ensure that you have the necessary permissions and access credentials to interact with the Zilliz Cloud API.
+
+### Creating a Cluster
+
+Append the following code to your `main.tf` file mentioned in the [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md) guide.
+
+
+```hcl
+
+data "zillizcloud_project" "default" {
+  # Fetching the default project information to be used in cluster provisioning
+}
+
+resource "zillizcloud_cluster" "serverless_plan_cluster" {
+  # Name for your cluster
+  cluster_name = "Cluster-02"
+  # The service plan for the cluster
+  plan         = "Serverless"
+  # ID of the default project retrieved from data source
+  project_id   = data.zillizcloud_project.default.id 
+}
+
+output "cluster_connect_address" {
+  value = zillizcloud_cluster.serverless_plan_cluster.connect_address
+}
+output "cluster_username" {
+  value = zillizcloud_cluster.serverless_plan_cluster.username
+}
+output "cluster_password" {
+  sensitive = true
+  value = zillizcloud_cluster.serverless_plan_cluster.password
+}
+```
+
+
+**Explanation:**
+
+- This configuration defines a `zillizcloud_cluster` resource named `serverless_plan_cluster`.
+- * `cluster_name`: Sets the name of your cluster (here, "Cluster-02").
+  * `project_id`: Retrieves the ID of the default project using the `data.zillizcloud_project.default.id` attribute.
+
+### Planning and Applying Changes
+
+Once you've defined the cluster resources, it's time to apply the changes to provision the Zilliz Cloud clusters. Navigate to your Terraform project directory and execute the following commands:
+
+```bash
+terraform apply -auto-approve
+
+Outputs:
+
+cluster_connect_address = "https://in05-fb24b4124d4fc98.api.gcp-us-west1.zillizcloud.com"
+cluster_username = "db_fb24b4124d4fc98"
+cluster_password = <sensitive>
+```
+
+**Note**: The `-auto-approve` flag avoids prompting for confirmation before applying the changes. Use caution, especially in production environments. It's recommended to thoroughly review the plan before applying.
+
+Terraform will orchestrate the creation of the specified clusters based on your configuration. Once the process is complete, Terraform will display the output values for the cluster's connection address, username, and password.
+
+### Verifying Provisioned Clusters
+
+After applying the changes, you can verify the provisioned Zilliz Cloud clusters either through the Zilliz Cloud dashboard. Ensure that the clusters are created with the desired configurations and are functioning as expected.
+
+## Destroying the Cluster(Optional)
+If you want to destroy the cluster, you can run the following command:
+```
+$ terraform destroy
+```
+
+## Next Steps
+- Explore creating a **Standard Plan** Cluster: [Creating a Standard Plan Cluster](./create-a-standard-cluster.md)
diff --git a/templates/guides/create-a-standard-cluster.md b/templates/guides/create-a-standard-cluster.md
@@ -0,0 +1,87 @@
+## Tutorial: Creating a Standard Plan Cluster with Terraform
+
+This tutorial guides you through managing a **Standard Plan** Cluster using the `zillizcloud_cluster` resource within Terraform.  Standard Plan Cluster have more resources, compared to Free Plan Cluster and are suitable for production workloads.
+
+Check out the [Select the Right Cluster Plan](https://docs.zilliz.com/docs/select-zilliz-cloud-service-plans) for more information on the available plans.
+
+**You'll learn how to:**
+- Retrieve project and region IDs for cluster creation.
+- Define clusters with various configurations in Terraform.
+- Plan and apply changes to provision clusters in Zilliz Cloud.
+- Verify the creation of your Zilliz Cloud clusters.
+
+### Prerequisites
+
+Before you begin, make sure you have completed the initial setup steps outlined in the [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md) guide. Additionally, ensure that you have the necessary permissions and access credentials to interact with the Zilliz Cloud API.
+
+
+## Retrieving Your Zilliz Cloud Project ID
+
+There are two ways to find your Zilliz Cloud project ID:
+
+**1. Zilliz Cloud Console:**
+
+Refer to the Zilliz Cloud documentation for details on obtaining your project ID through the console: [How Can I Obtain the Project ID?](https://support.zilliz.com/hc/en-us/articles/22048954409755-How-Can-I-Obtain-the-Project-ID)
+
+**2. Zilliz Cloud Data Source (Optional):**
+
+For convenience, you can use the `zillizcloud_project` data source to retrieve the ID of the default project associated with your Zilliz Cloud account.
+
+## Selecting a Zilliz Cloud Region
+
+This tutorial will use the `aws-us-east-2` region.  However, you can choose a different region based on your needs.
+
+For a full list of available cloud providers and regions, refer to the Zilliz Cloud documentation: [Cloud Providers & Regions](https://docs.zilliz.com/docs/cloud-providers-and-regions)
+
+### Creating a Cluster
+
+With the `project ID` and `region ID` at hand, creating Zilliz Cloud clusters is straightforward. Below is an illustrative example defining zillizcloud_cluster resources within Terraform configuration:
+
+Append the following code to your `main.tf` file mentioned in the [Getting Started with Zilliz Cloud Terraform Provider](./get-start.md) guide.
+
+```hcl
+
+data "zillizcloud_project" "default" {
+  # Fetching the default project information to be used in cluster provisioning
+}
+
+resource "zillizcloud_cluster" "standard_plan_cluster" {
+  cluster_name = "Cluster-02"                        # The name of the cluster
+  region_id    = "aws-us-east-2"                     # The region where the cluster will be deployed
+  plan         = "Standard"                          # The service plan for the cluster
+  cu_size      = "1"                                 # The size of the compute unit
+  cu_type      = "Performance-optimized"             # The type of compute unit, optimized for performance
+  project_id   = data.zillizcloud_project.default.id # Linking to the project ID fetched earlier
+}
+
+
+```
+**Explanation of the Configuration:**
+
+This code creates a Zilliz Cloud cluster named "Cluster-02" in the "aws-us-east-2" region. It serves the "Standard" plan with a single, performance-optimized compute unit, making it suitable for workloads requiring more processing power.
+
+
+### Planning and Applying Changes
+
+Once you've defined the cluster resources, it's time to apply the changes to provision the Zilliz Cloud clusters. Navigate to your Terraform project directory and execute the following commands:
+
+```bash
+terraform apply -auto-approve
+```
+
+**Note**: The `-auto-approve` flag avoids prompting for confirmation before applying the changes. Use caution, especially in production environments. It's recommended to thoroughly review the plan before applying.
+
+Terraform will orchestrate the creation of the specified clusters based on your configuration. Once the process is complete, Terraform will display the output values for the cluster's connection address, username, and password.
+
+### Verifying Provisioned Clusters
+
+After applying the changes, you can verify the provisioned Zilliz Cloud clusters either through the Zilliz Cloud dashboard. Ensure that the clusters are created with the desired configurations and are functioning as expected.
+
+## Destroying the Cluster(Optional)
+If you want to destroy the cluster, you can run the following command:
+```
+$ terraform destroy
+```
+
+## Next Steps
+- [Upgrading Zilliz Cloud Cluster Compute Unit Size with Terraform](./scale-cluster.md)
diff --git a/templates/guides/get-start.md b/templates/guides/get-start.md
@@ -0,0 +1,73 @@
+## Getting Started with Zilliz Cloud Terraform Provider
+
+This guide walks you through the process of installing and configuring the Zilliz Cloud provider.
+
+### 1.Prerequisites
+
+Before you begin, ensure you have the following:
+
+1. **Terraform Installed**: Download and install Terraform from [here](https://www.terraform.io/downloads.html) by following the provided instructions.
+
+2. **Zilliz Cloud Account**: Access to Zilliz Cloud and your API Key are essential. Refer to the [documentation](https://docs.zilliz.com/docs/manage-api-keys) to obtain your API key.
+
+## 2. Download Zilliz Cloud Terraform Provider
+
+Start by configuring the Zilliz Cloud provider within your Terraform configuration file (`main.tf`). Follow these steps:
+
+```hcl
+terraform {
+  required_providers {
+    zillizcloud = {
+      source = "zilliztech/zillizcloud"
+    }
+  }
+}
+```
+
+## 3. Initialize Terraform Configuration
+
+Initialize the Terraform configuration by running:
+
+```bash
+terraform init
+```
+
+Terraform will download the `zillizcloud` provider and install it in a hidden subdirectory of your current working directory, named `.terraform`.
+
+### 4. Authenticate Zilliz Cloud Terraform Provider
+
+Your Zilliz Cloud API Key is required to use the Terraform Provider. There are two ways to configure this.
+
+#### Option 1: Specify API Key in Provider Block
+
+Append the following code to your `main.tf` file:
+
+```hcl
+provider "zillizcloud" {
+  api_key = "<your-api-key>"
+}
+```
+
+Replace `<your-api-key>` with your Zilliz Cloud API Key.
+
+#### Option 2: Use Environment Variable
+
+Set the API key as an environment variable:
+
+```bash
+export ZILLIZCLOUD_API_KEY="<your-api-key>"
+```
+
+Then the provider declaration in your `main.tf` file is simply:
+
+```hcl
+provider "zillizcloud" {
+}
+```
+
+By following these steps, you should have the Zilliz Cloud Terraform provider configured and ready to move on to the next steps.
+
+## Next Steps
+- Explore creating a **Free Plan** Cluster: [Creating a Free Plan Cluster](./create-a-free-cluster.md)
+- Explore creating a **Serverless Plan** Cluster: [Creating a Serverless Plan Cluster](./create-a-serverless-cluster.md)
+- Explore creating a **Standard Plan** Cluster: [Creating a Standard Plan Cluster](./create-a-standard-cluster.md)