chore: Add missing documentation (#2781)

Add missing documentation that should resolve - #1087 - added descriptions for the `SNOWFLAKE_IAM_USER` and `AWS_EXTERNAL_ID` fields in stage - #2181 - added simple example and custom description with links for the snowflake_system_get_aws_sns_iam_policy to show how it could be used with AWS - Add missing parts for the Issue creating guide + FAQ - Pull out the SDK error to common package + usage in places where errors were compared with string instead of predefined error
Snowflake-Labs · May 7, 2024 · cc0a6a7 · cc0a6a7
1 parent 66e380d
commit cc0a6a7
Show file tree

Hide file tree

Showing 13 changed files with 72 additions and 32 deletions.
diff --git a/CREATING_ISSUES.md b/CREATING_ISSUES.md
@@ -57,15 +57,17 @@ It depends on the status of the feature. Snowflake marks features as follows:
 - Private Preview (PrPr)
 - Public Preview (PuPr)
 - Generally Available (GA)
-Currently, our main focus is on making the provider stable with the most stable GA features. 
-If you would like to see a preview feature in the provider, please place a request, but keep in mind that we will most likely take care of preview features after the first stable release (v1.0.0). 
-Also, If any of the features recently went GA, they will most likely be addressed after v1.0.0 right with the preview ones.
+
+Currently, our main focus is on making the provider stable with the most stable GA features, 
+but please take a closer look at our recently updated [roadmap](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/ROADMAP.md#05052024-roadmap-overview) 
+which describes our priorities for the next quarters.
 
 ### When will my bug report be fixed/released?
 Our team is checking daily incoming GitHub issues. The resolution depends on the complexity and the topic of a given issue, but the general rules are:
 - If the issue is easy enough, we tend to answer it immediately and provide fix depending on the issue and our current workload.
 - If the issue needs more insight, we tend to reproduce the issue usually in the matter of days and answer/fix it right away (also very dependent on our current workload).
 - If the issue is a part of the incoming topic on the [roadmap](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/ROADMAP.md), we postpone it to resolve it with the related tasks.
+
 The releases are usually happening once every two weeks, mostly done on Wednesday.
 
 ### How to migrate from version X to Y?
@@ -86,6 +88,12 @@ The provider is simply an abstraction issuing SQL commands through the Go Snowfl
 To see what SQLs are being run you have to set the `TF_LOG=DEBUG` environment variable. 
 To confirm the correctness of the SQLs, refer to the [official Snowflake documentation](https://docs.snowflake.com/).
 
+### How can I import already existing Snowflake infrastructure into Terraform?
+Please refer to [this document](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/resource_migration.md#3-two-options-from-here) 
+as it describes different approaches of importing the existing Snowflake infrastructure into Terrafrom as configuration. 
+One thing worth noting is that some approaches can be automated by scripts interacting with Snowflake and generating needed configuration blocks, 
+which is highly recommended for large-scale migrations.
+
 ## Commonly known issues
 ### Old Terraform CLI version
 **Problem:** Sometimes you can get errors similar to:
@@ -102,9 +110,15 @@ To confirm the correctness of the SQLs, refer to the [official Snowflake documen
 **Solution:** You have to be using at least 1.1.5 version of the Terraform CLI.
 
 ### Errors with connection to Snowflake
-**Problem:** If you are getting connection errors, there may be a chance of finding solution by error id.
+**Problem**: If you are getting connection errors with Snowflake error code, similar to this one:
+```text
+│
+│ Error: open snowflake connection: 390144 (08004): JWT token is invalid.
+│
+```
+**Solution**: Go to the [official Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth-troubleshooting#list-of-errors) and search by error code (390144 in this case).
 
-**Solution:** Go to the [official Snowflake documentation](https://docs.snowflake.com/) and search for your issue by error id.
+[GitHub issue reference](https://github.com/Snowflake-Labs/terraform-provider-snowflake/issues/2432#issuecomment-1915074774)
 
 ### How to set up the connection with the private key?
 **Problem:** From the version v0.78.0, we introduced a lot of provider configuration changes. One of them was deprecating `private_key_path` in favor of `private_key`.

diff --git a/docs/data-sources/system_get_aws_sns_iam_policy.md b/docs/data-sources/system_get_aws_sns_iam_policy.md
@@ -9,7 +9,17 @@ description: |-
 
 
 
+For more details, visit the official Snowflake documentation: https://docs.snowflake.com/en/sql-reference/functions/system_get_aws_sns_iam_policy.
+Read this guide to understand how to use the snowflake_system_get_aws_sns_iam_policy to integrate with AWS: https://docs.snowflake.com/en/user-guide/data-load-snowpipe-auto-s3#step-1-subscribe-the-snowflake-sqs-queue-to-the-sns-topic.
+It's SQL-based, but after knowing what has to be done use corresponding resources and data-sources from the Snowflake and AWS Terraform provider.
 
+## Example Usage
+
+```terraform
+data "snowflake_system_get_aws_sns_iam_policy" "snowflake_policy" {
+  aws_sns_topic_arn = "<aws_sns_topic_arn>"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/resources/stage.md b/docs/resources/stage.md
@@ -32,14 +32,14 @@ resource "snowflake_stage" "example_stage" {
 
 ### Optional
 
-- `aws_external_id` (String)
+- `aws_external_id` (String) A unique ID assigned to the specific stage. The ID has the following format: &lt;snowflakeAccount&gt;_SFCRole=&lt;snowflakeRoleId&gt;_&lt;randomId&gt;
 - `comment` (String) Specifies a comment for the stage.
 - `copy_options` (String) Specifies the copy options for the stage.
 - `credentials` (String, Sensitive) Specifies the credentials for the stage.
 - `directory` (String) Specifies the directory settings for the stage.
 - `encryption` (String) Specifies the encryption settings for the stage.
 - `file_format` (String) Specifies the file format for the stage.
-- `snowflake_iam_user` (String)
+- `snowflake_iam_user` (String) An AWS IAM user created for your Snowflake account. This user is the same for every external S3 stage created in your account.
 - `storage_integration` (String) Specifies the name of the storage integration used to delegate authentication responsibility for external cloud storage to a Snowflake identity and access management (IAM) entity.
 - `tag` (Block List, Deprecated) Definitions of a tag to associate with the resource. (see [below for nested schema](#nestedblock--tag))
 - `url` (String) Specifies the URL for the stage.

diff --git a/examples/data-sources/snowflake_system_get_aws_sns_iam_policy/data-source.tf b/examples/data-sources/snowflake_system_get_aws_sns_iam_policy/data-source.tf
@@ -0,0 +1,3 @@
+data "snowflake_system_get_aws_sns_iam_policy" "snowflake_policy" {
+  aws_sns_topic_arn = "<aws_sns_topic_arn>"
+}
diff --git a/pkg/datasources/system_get_aws_sns_iam_policy.go b/pkg/datasources/system_get_aws_sns_iam_policy.go
@@ -17,7 +17,6 @@ var systemGetAWSSNSIAMPolicySchema = map[string]*schema.Schema{
 		Required:    true,
 		Description: "Amazon Resource Name (ARN) of the SNS topic for your S3 bucket",
 	},
-
 	"aws_sns_topic_policy_json": {
 		Type:        schema.TypeString,
 		Computed:    true,

diff --git a/pkg/resources/grant_privileges_to_account_role.go b/pkg/resources/grant_privileges_to_account_role.go
@@ -741,8 +741,7 @@ func ReadGrantPrivilegesToAccountRole(ctx context.Context, d *schema.ResourceDat
 
 	client := meta.(*provider.Context).Client
 
-	// TODO(SNOW-891217): Use custom error. Right now, "object does not exist" error is hidden in sdk/internal/collections package
-	if _, err := client.Roles.ShowByID(ctx, id.RoleName); err != nil && err.Error() == "object does not exist" {
+	if _, err := client.Roles.ShowByID(ctx, id.RoleName); err != nil && errors.Is(err, sdk.ErrObjectNotFound) {
 		d.SetId("")
 		return diag.Diagnostics{
 			diag.Diagnostic{

diff --git a/pkg/resources/grant_privileges_to_database_role.go b/pkg/resources/grant_privileges_to_database_role.go
@@ -656,8 +656,7 @@ func ReadGrantPrivilegesToDatabaseRole(ctx context.Context, d *schema.ResourceDa
 	}
 
 	client := meta.(*provider.Context).Client
-	// TODO(SNOW-891217): Use custom error. Right now, "object does not exist" error is hidden in sdk/internal/collections package
-	if _, err := client.DatabaseRoles.ShowByID(ctx, id.DatabaseRoleName); err != nil && err.Error() == "object does not exist" {
+	if _, err := client.DatabaseRoles.ShowByID(ctx, id.DatabaseRoleName); err != nil && errors.Is(err, sdk.ErrObjectNotFound) {
 		d.SetId("")
 		return diag.Diagnostics{
 			diag.Diagnostic{

diff --git a/pkg/resources/grant_privileges_to_role.go b/pkg/resources/grant_privileges_to_role.go
@@ -828,7 +828,7 @@ func setRolePrivilegeOptions(privileges []string, allPrivileges bool, onAccount
 }
 
 func readRoleGrantPrivileges(ctx context.Context, client *sdk.Client, grantedOn sdk.ObjectType, id GrantPrivilegesToRoleID, opts *sdk.ShowGrantOptions, d *schema.ResourceData) error {
-	if _, err := client.Roles.ShowByID(ctx, sdk.NewAccountObjectIdentifier(id.RoleName)); err != nil && err.Error() == "object does not exist" {
+	if _, err := client.Roles.ShowByID(ctx, sdk.NewAccountObjectIdentifier(id.RoleName)); err != nil && errors.Is(err, sdk.ErrObjectNotFound) {
 		d.SetId("")
 		log.Printf("[DEBUG] Failed to retrieve account role. Marking the resource as removed.")
 		return nil

diff --git a/pkg/resources/role.go b/pkg/resources/role.go
@@ -2,6 +2,7 @@ package resources
 
 import (
 	"context"
+	"errors"
 	"fmt"
 
 	"github.com/Snowflake-Labs/terraform-provider-snowflake/pkg/internal/provider"
@@ -77,7 +78,7 @@ func ReadAccountRole(ctx context.Context, d *schema.ResourceData, meta any) diag
 
 	accountRole, err := client.Roles.ShowByID(ctx, id)
 	if err != nil {
-		if err.Error() == "object does not exist" {
+		if errors.Is(err, sdk.ErrObjectNotFound) {
 			d.SetId("")
 			return diag.Diagnostics{
 				diag.Diagnostic{

diff --git a/pkg/resources/stage.go b/pkg/resources/stage.go
@@ -80,11 +80,15 @@ var stageSchema = map[string]*schema.Schema{
 		Type:     schema.TypeString,
 		Optional: true,
 		Computed: true,
+		// Description based on https://docs.snowflake.com/en/user-guide/data-load-s3-config-aws-iam-role#step-3-create-an-external-stage
+		Description: "A unique ID assigned to the specific stage. The ID has the following format: &lt;snowflakeAccount&gt;_SFCRole=&lt;snowflakeRoleId&gt;_&lt;randomId&gt;",
 	},
 	"snowflake_iam_user": {
 		Type:     schema.TypeString,
 		Optional: true,
 		Computed: true,
+		// Description based on https://docs.snowflake.com/en/user-guide/data-load-s3-config-aws-iam-role#step-3-create-an-external-stage
+		Description: "An AWS IAM user created for your Snowflake account. This user is the same for every external S3 stage created in your account.",
 	},
 	"tag": tagReferenceSchema,
 }

diff --git a/pkg/sdk/errors.go b/pkg/sdk/errors.go
@@ -7,12 +7,17 @@ import (
 	"regexp"
 	"runtime"
 	"strings"
+
+	"github.com/Snowflake-Labs/terraform-provider-snowflake/pkg/sdk/internal/collections"
 )
 
 var (
 	ErrNilOptions                    = NewError("options cannot be nil")
 	ErrPatternRequiredForLikeKeyword = NewError("pattern must be specified for like keyword")
 
+	// re-importing from internal package
+	ErrObjectNotFound = collections.ErrObjectNotFound
+
 	// go-snowflake errors.
 	ErrObjectNotExistOrAuthorized = NewError("object does not exist or not authorized")
 	ErrAccountIsEmpty             = NewError("account is empty")

diff --git a/pkg/snowflake/errors.go b/pkg/snowflake/errors.go
diff --git a/templates/data-sources/system_get_aws_sns_iam_policy.md.tmpl b/templates/data-sources/system_get_aws_sns_iam_policy.md.tmpl
@@ -0,0 +1,24 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ if gt (len (split .Description "<deprecation>")) 1 -}}
+{{ index (split .Description "<deprecation>") 1 | plainmarkdown | trimspace | prefixlines "  " }}
+{{- else -}}
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+{{- end }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+For more details, visit the official Snowflake documentation: https://docs.snowflake.com/en/sql-reference/functions/system_get_aws_sns_iam_policy.
+Read this guide to understand how to use the snowflake_system_get_aws_sns_iam_policy to integrate with AWS: https://docs.snowflake.com/en/user-guide/data-load-snowpipe-auto-s3#step-1-subscribe-the-snowflake-sqs-queue-to-the-sns-topic.
+It's SQL-based, but after knowing what has to be done use corresponding resources and data-sources from the Snowflake and AWS Terraform provider.
+
+## Example Usage
+
+{{ tffile (printf "examples/data-sources/%s/data-source.tf" .Name) }}
+
+{{ .SchemaMarkdown | trimspace }}