diff --git a/README.md b/README.md index 1b564ca..3a1701f 100644 --- a/README.md +++ b/README.md @@ -4,31 +4,24 @@ This is the repository for the terraform-provider-zillizcloud, which allows one For general information about Terraform, visit the [official website](https://www.terraform.io) and the [GitHub project page](https://github.com/hashicorp/terraform). -## Support -Resources -- [cluster](./docs/resources/cluster.md) - - create - - scale - - import - -DataSource - -- [project](./docs/data-sources/project.md) -- [region](./docs/data-sources/regions.md) - - AWS - - GCP - - Azure - - Alibaba Cloud - - Tecent Cloud +## Table of Contents + -## API Documentation +- [User Guide](#user-guide) +- [API Documentation](#api-documentation) +- [Requirements](#requirements) +- [Building The Provider](#building-the-provider) + + -API Documentation can be found on the [Terraform Registry](https://registry.terraform.io/providers/zilliztech/zillizcloud/latest/docs). ## User Guide See [Zilliz Cloud Terraform Integration Overview](./docs/README.md) for more information. +## API Documentation + +API Documentation can be found on the [Terraform Registry](https://registry.terraform.io/providers/zilliztech/zillizcloud/latest/docs). ## Requirements diff --git a/docs/create-a-stand-cluster.md b/docs/create-a-stand-cluster.md new file mode 100644 index 0000000..6200c7c --- /dev/null +++ b/docs/create-a-stand-cluster.md @@ -0,0 +1,68 @@ +# Tutorial: Creating Zilliz a Standard Cloud Cluster Resources with Terraform + +This tutorial guides you through managing Zilliz Cloud clusters using the `zillizcloud_cluster` resource within Terraform. 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 Project IDs in Your Zilliz Cloud Account + +[How Can I Obtain the Project ID ?](https://support.zilliz.com/hc/en-us/articles/22048954409755-How-Can-I-Obtain-the-Project-ID) + +For convenience, you can use the `zillizcloud_project` data source to retrieve the ID of default project for your Zilliz Cloud account. + + +## Acquiring Region IDs for Zilliz Cloud Cluster + +[Cloud Providers & Regions](https://docs.zilliz.com/docs/cloud-providers-and-regions) + +In this tutorial, we will use the `aws-us-east-2` region. + +### 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: + + +```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 +} +``` +This example will create a Zilliz Cloud cluster: +- **Standard Plan Cluster**: This configuration creates a more advanced cluster named "Cluster-02" in the `aws-us-east-2` region. It uses the "Standard" service plan with a compute unit size of 1, optimized for performance, making it suitable for more demanding workloads. + +### 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. + +Review the plan generated by Terraform and confirm to apply the changes. Terraform will orchestrate the creation of the specified clusters based on your configuration. + +### 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. + +## Next Steps +- [Upgrading Zilliz Cloud Cluster Compute Unit Size with Terraform](./scale-cluster.md) diff --git a/docs/create-a-starter-cluster.md b/docs/create-a-starter-cluster.md new file mode 100644 index 0000000..116acdf --- /dev/null +++ b/docs/create-a-starter-cluster.md @@ -0,0 +1,48 @@ +# Tutorial: Creating Zilliz a Starter Cloud Cluster Resources with Terraform + +This tutorial guides you through managing Zilliz Cloud clusters using the `zillizcloud_cluster` resource within Terraform. 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. + + +### Creating a Cluster + +With the `project ID` at hand, creating Zilliz Cloud clusters is straightforward. Below is an illustrative example defining zillizcloud_cluster resources within Terraform configuration: + + +```hcl + +data "zillizcloud_project" "default" {} + +resource "zillizcloud_cluster" "starter_cluster" { + cluster_name = "Cluster-01" + project_id = data.zillizcloud_project.default.id +} + +``` +This example will create two Zilliz Cloud clusters: +- **Starter Cluster**: This configuration creates a basic cluster named "Cluster-01" within the default project. It's suitable for initial testing or small-scale applications. + +### 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. + +Review the plan generated by Terraform and confirm to apply the changes. Terraform will orchestrate the creation of the specified clusters based on your configuration. + +### 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. + diff --git a/docs/create-cluster.md b/docs/create-cluster.md deleted file mode 100644 index c1cb29f..0000000 --- a/docs/create-cluster.md +++ /dev/null @@ -1,163 +0,0 @@ -# Tutorial: Creating Zilliz Cloud Cluster Resources with Terraform - -This tutorial guides you through managing Zilliz Cloud clusters using the `zillizcloud_cluster` resource within Terraform. 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 Project IDs in Your Zilliz Cloud Account - -Every Zilliz Cloud cluster is associated with a project. To create a cluster, it's imperative to obtain the corresponding project ID. - -To access information regarding available projects, utilize the zillizcloud_projects data source as demonstrated below: - -```hcl -data "zillizcloud_project" "default" {} - -output "projects" { - value = data.zillizcloud_project.default -} -``` - -```shell -$ terraform apply --auto-approve - -data.zillizcloud_project.default: Reading... -data.zillizcloud_project.default: Read complete after 1s [id=proj-4487580fcfe2c8a4391686] - -Apply complete! Resources: 0 added, 0 changed, 0 destroyed. - -Outputs: - -projects = { - "created_at" = 1714892175000 - "id" = "proj-4487580fcfe2cxxxxx" - "instance_count" = 0 - "name" = "Default Project" -} -``` - -The project ID **"proj-4487580fcfe2cxxxxx"** is displayed in the output section. You can use your ID to create Zilliz Cloud clusters within the specified project, or refer to the project ID via `data.zillizcloud_project.default.id` in your Terraform configuration file. - -## Acquiring Region IDs for Zilliz Cloud Cluster - - - -To provision Zilliz Cloud clusters, you'll must specify the region where the cluster will be deployed. Zilliz Cloud supports multiple regions across various cloud providers, such as AWS, GCP, and Azure. You can retrieve the region IDs for each cloud provider using the zillizcloud_regions data source. - -```terraform - -data "zillizcloud_regions" "aws_region" { - cloud_id = "aws" -} - -data "zillizcloud_regions" "gcp_region" { - cloud_id = "gcp" -} - -data "zillizcloud_regions" "azure_region" { - cloud_id = "azure" -} - -output "aws_ouput" { - value = data.zillizcloud_regions.aws_region.items -} - - -output "gcp_ouput" { - value = data.zillizcloud_regions.gcp_region.items -} - -output "azure_ouput" { - value = data.zillizcloud_regions.azure_region.items -} -``` - - -``` -$ terraform apply --auto-approve - -learn-terraform terraform apply -auto-approve -data.zillizcloud_regions.gcp_region: Reading... -data.zillizcloud_regions.aws_region: Reading... -data.zillizcloud_regions.azure_region: Reading... -data.zillizcloud_project.default: Reading... -data.zillizcloud_regions.aws_region: Read complete after 0s -data.zillizcloud_regions.gcp_region: Read complete after 0s -data.zillizcloud_regions.azure_region: Read complete after 0s -data.zillizcloud_project.default: Read complete after 0s [id=proj-4487580fcfe2c8a4391686] - -You can apply this plan to save these new output values to the Terraform state, without changing any real infrastructure. - -Apply complete! Resources: 0 added, 0 changed, 0 destroyed. - -Outputs: - -aws_ouput = tolist([ -... - { - "api_base_url" = "https://api.aws-us-west-2.zillizcloud.com" - "cloud_id" = "aws" - "region_id" = "aws-us-west-2" - }, -... -]) -azure_ouput = tolist([ -... -]) -gcp_ouput = tolist([ -... -]) -``` - -Upon execution, this Terraform script retrieves region details for each cloud provider, facilitating subsequent cluster provisioning steps. In this session, we would use **aws-us-east-2** in the following example. - - -### 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: - - -```hcl -resource "zillizcloud_cluster" "starter_cluster" { - cluster_name = "Cluster-01" - project_id = data.zillizcloud_project.default.id -} - -resource "zillizcloud_cluster" "standard_plan_cluster" { - cluster_name = "Cluster-02" - region_id = "aws-us-east-2" - plan = "Standard" - cu_size = "1" - cu_type = "Performance-optimized" - project_id = data.zillizcloud_project.default.id -} -``` -This example will create two Zilliz Cloud clusters: -- **Starter Cluster**: This configuration creates a basic cluster named "Cluster-01" within the default project. It's suitable for initial testing or small-scale applications. -- **Standard Plan Cluster**: This configuration creates a more advanced cluster named "Cluster-02" in the `aws-us-east-2` region. It uses the "Standard" service plan with a compute unit size of 1, optimized for performance, making it suitable for more demanding workloads. - -### 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. - -Review the plan generated by Terraform and confirm to apply the changes. Terraform will orchestrate the creation of the specified clusters based on your configuration. - -### 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. - -## Next Steps -- [Upgrading Zilliz Cloud Cluster Compute Unit Size with Terraform](./scale-cluster.md) diff --git a/docs/get-start.md b/docs/get-start.md index bc8d66f..5b51a6f 100644 --- a/docs/get-start.md +++ b/docs/get-start.md @@ -10,7 +10,7 @@ Before you begin, ensure you have the following: 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. Configure Terraform Provider +## 2. Download Zilliz Cloud Terraform Provider Start by configuring the Zilliz Cloud provider within your Terraform configuration file (`main.tf`). Follow these steps: @@ -22,7 +22,27 @@ terraform { } } } +``` + +## 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 = "" } @@ -30,18 +50,19 @@ provider "zillizcloud" { Replace `` with your Zilliz Cloud API Key. -Alternatively, you can use the environment variable `ZILLIZCLOUD_API_KEY` instead of specifying it in the provider block. +#### Option 2: Use Environment Variable + +Set the API key as an environment variable: ```bash -$ export ZILLIZCLOUD_API_KEY="" +export ZILLIZCLOUD_API_KEY="" ``` -## 3. Initialize Terraform Configuration - -Initialize the Terraform configuration by running: +Then the provider declaration in your `main.tf` file is simply: -```bash -terraform init +```hcl +provider "zillizcloud" { +} ``` -Terraform will download the `zillizcloud` provider and install it in a hidden subdirectory of your current working directory, named `.terraform`. +By following these steps, you should have the Zilliz Cloud Terraform provider configured and ready to use in your Terraform projects. diff --git a/docs/list-project.md b/docs/list-project.md new file mode 100644 index 0000000..0f0e62a --- /dev/null +++ b/docs/list-project.md @@ -0,0 +1,34 @@ + +## Retrieving Project IDs in Your Zilliz Cloud Account + +Every Zilliz Cloud cluster is associated with a project. To create a cluster, it's imperative to obtain the corresponding project ID. + +To access information regarding available projects, utilize the zillizcloud_projects data source as demonstrated below: + +```hcl +data "zillizcloud_project" "default" {} + +output "projects" { + value = data.zillizcloud_project.default +} +``` + +```shell +$ terraform apply --auto-approve + +data.zillizcloud_project.default: Reading... +data.zillizcloud_project.default: Read complete after 1s [id=proj-4487580fcfe2c8a4391686] + +Apply complete! Resources: 0 added, 0 changed, 0 destroyed. + +Outputs: + +projects = { + "created_at" = 1714892175000 + "id" = "proj-4487580fcfe2cxxxxx" + "instance_count" = 0 + "name" = "Default Project" +} +``` + +The project ID **"proj-4487580fcfe2cxxxxx"** is displayed in the output section. You can use your ID to create Zilliz Cloud clusters within the specified project, or refer to the project ID via `data.zillizcloud_project.default.id` in your Terraform configuration file. diff --git a/docs/list-regions.md b/docs/list-regions.md new file mode 100644 index 0000000..361d54e --- /dev/null +++ b/docs/list-regions.md @@ -0,0 +1,73 @@ + +## Acquiring Region IDs for Zilliz Cloud Cluster + + + +To provision Zilliz Cloud clusters, you'll must specify the region where the cluster will be deployed. Zilliz Cloud supports multiple regions across various cloud providers, such as AWS, GCP, and Azure. You can retrieve the region IDs for each cloud provider using the zillizcloud_regions data source. + +```terraform + +data "zillizcloud_regions" "aws_region" { + cloud_id = "aws" +} + +data "zillizcloud_regions" "gcp_region" { + cloud_id = "gcp" +} + +data "zillizcloud_regions" "azure_region" { + cloud_id = "azure" +} + +output "aws_ouput" { + value = data.zillizcloud_regions.aws_region.items +} + + +output "gcp_ouput" { + value = data.zillizcloud_regions.gcp_region.items +} + +output "azure_ouput" { + value = data.zillizcloud_regions.azure_region.items +} +``` + + +``` +$ terraform apply --auto-approve + +learn-terraform terraform apply -auto-approve +data.zillizcloud_regions.gcp_region: Reading... +data.zillizcloud_regions.aws_region: Reading... +data.zillizcloud_regions.azure_region: Reading... +data.zillizcloud_project.default: Reading... +data.zillizcloud_regions.aws_region: Read complete after 0s +data.zillizcloud_regions.gcp_region: Read complete after 0s +data.zillizcloud_regions.azure_region: Read complete after 0s +data.zillizcloud_project.default: Read complete after 0s [id=proj-4487580fcfe2c8a4391686] + +You can apply this plan to save these new output values to the Terraform state, without changing any real infrastructure. + +Apply complete! Resources: 0 added, 0 changed, 0 destroyed. + +Outputs: + +aws_ouput = tolist([ +... + { + "api_base_url" = "https://api.aws-us-west-2.zillizcloud.com" + "cloud_id" = "aws" + "region_id" = "aws-us-west-2" + }, +... +]) +azure_ouput = tolist([ +... +]) +gcp_ouput = tolist([ +... +]) +``` + +Upon execution, this Terraform script retrieves region details for each cloud provider, facilitating subsequent cluster provisioning steps. In this session, we would use **aws-us-east-2** in the following example.