Merge pull request #25 from permitio/raz/per-8701-add-more-documentat…

…ion-and-guidelines-for-terraform-provider

Add descriptions and links to our docs

internal/provider/common/schema.go

@@ -9,51 +9,60 @@ import (
 func CreateBaseResourceSchema() map[string]schema.Attribute {
 	return map[string]schema.Attribute{
 		"id": schema.StringAttribute{
-			Computed: true,
+			Computed:            true,
+			MarkdownDescription: "The resource ID. This is a unique identifier for the resource. ",
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"key": schema.StringAttribute{
-			Required: true,
+			Required:            true,
+			MarkdownDescription: "The key. This is a unique identifier. ",
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.RequiresReplace(),
 			},
 		},
 		"name": schema.StringAttribute{
-			Required: true,
+			MarkdownDescription: "The name. This is a human-readable name for the object. ",
+			Required:            true,
 		},
 		"description": schema.StringAttribute{
-			Optional: true,
-			Computed: true,
+			MarkdownDescription: "The description. This is a human-readable description for the object. ",
+			Optional:            true,
+			Computed:            true,
 		},
 		"organization_id": schema.StringAttribute{
-			Computed: true,
+			MarkdownDescription: "The organization ID. This is a unique identifier for the organization. ",
+			Computed:            true,
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"project_id": schema.StringAttribute{
-			Computed: true,
+			MarkdownDescription: "The project ID. This is a unique identifier for the project. ",
+			Computed:            true,
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"environment_id": schema.StringAttribute{
-			Computed: true,
+			MarkdownDescription: "The environment ID. This is a unique identifier for the environment. ",
+			Computed:            true,
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"created_at": schema.StringAttribute{
-			Computed: true,
+			MarkdownDescription: "The creation timestamp. This is a timestamp for when the object was created. ",
+			Computed:            true,
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"updated_at": schema.StringAttribute{
-			Optional: true,
-			Computed: true,
+			MarkdownDescription: "The update timestamp. This is a timestamp for when the object was last updated. ",
+			Optional:            true,
+			Computed:            true,
 		},
 	}
 }

internal/provider/conditionset_rules/resource.go

@@ -49,45 +49,53 @@ func (c *ConditionSetRuleResource) Metadata(_ context.Context, req resource.Meta
 
 func (c *ConditionSetRuleResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: "See [our documentation](https://api.permit.io/v2/redoc#tag/Condition-Set-Rules) for more information on condition sets rules.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the condition set rule",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"organization_id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the organization that owns the condition set rule",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"project_id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the project that owns the condition set rule",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"environment_id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the environment that owns the condition set rule",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"user_set": schema.StringAttribute{
-				Required: true,
+				Required:            true,
+				MarkdownDescription: "The userset that will be given permission, i.e: all the users matching this rule will be given the specified permission",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
 			},
 			"permission": schema.StringAttribute{
-				Required: true,
+				Required:            true,
+				MarkdownDescription: "The permission that will be granted to the userset on the resourceset. The permission can be either a resource action id, or {resource_key}:{action_key}, i.e: the \"permission name\".",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
 			},
 			"resource_set": schema.StringAttribute{
-				Required: true,
+				Required:            true,
+				MarkdownDescription: "The resourceset that represents the resources that are granted for access, i.e: all the resources matching this rule can be accessed by the userset to perform the granted permission",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},

internal/provider/conditionsets/resource.go

@@ -76,15 +76,17 @@ func (c *ResourceSetResource) Schema(_ context.Context, _ resource.SchemaRequest
 	}
 
 	resp.Schema = schema.Schema{
-		Attributes: attributes,
+		MarkdownDescription: "See the [our documentation](https://api.permit.io/v2/redoc#tag/Condition-Sets/operation/create_condition_set) for more information on condition sets.",
+		Attributes:          attributes,
 	}
 }
 
 func (c *UserSetResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	attributes := c.baseAttributes()
 
 	resp.Schema = schema.Schema{
-		Attributes: attributes,
+		MarkdownDescription: "See the [our documentation](https://api.permit.io/v2/redoc#tag/Condition-Sets/operation/create_condition_set) for more information on condition sets.",
+		Attributes:          attributes,
 	}
 }
 
@@ -95,44 +97,53 @@ func (c *conditionSetResource) Schema(_ context.Context, _ resource.SchemaReques
 func (c *conditionSetResource) baseAttributes() map[string]schema.Attribute {
 	return map[string]schema.Attribute{
 		"id": schema.StringAttribute{
-			Computed: true,
+			Computed:            true,
+			MarkdownDescription: "A unique id by which Permit will identify the condition set. The key will be used as the generated rego rule name.\n\n",
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"organization_id": schema.StringAttribute{
-			Computed: true,
+			Computed:            true,
+			MarkdownDescription: "The id of the organization to which the condition set belongs.",
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"project_id": schema.StringAttribute{
-			Computed: true,
+			MarkdownDescription: "The id of the project to which the condition set belongs.",
+			Computed:            true,
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"environment_id": schema.StringAttribute{
-			Computed: true,
+			MarkdownDescription: "The id of the environment to which the condition set belongs.",
+			Computed:            true,
 			PlanModifiers: []planmodifier.String{
 				stringplanmodifier.UseStateForUnknown(),
 			},
 		},
 		"key": schema.StringAttribute{
-			Required: true,
+			MarkdownDescription: "A unique id by which Permit will identify the condition set. The key will be used as the generated rego rule name.",
+			Required:            true,
 		},
 		"name": schema.StringAttribute{
-			Required: true,
+			MarkdownDescription: "A descriptive name for the set, i.e: 'US based employees' or 'Users behind VPN'",
+			Required:            true,
 		},
 		"description": schema.StringAttribute{
-			Optional: true,
-			Computed: true,
+			MarkdownDescription: "an optional longer description of the set",
+			Optional:            true,
+			Computed:            true,
 		},
 		"conditions": schema.StringAttribute{
-			Required: true,
+			MarkdownDescription: "a boolean expression that consists of multiple conditions, with and/or logic.",
+			Required:            true,
 		},
 		"resource": schema.StringAttribute{
-			Optional: true,
+			MarkdownDescription: "The resource id to which the condition set applies. This is only required for resource sets.",
+			Optional:            true,
 		},
 	}
 }

internal/provider/proxy_configs/resource.go

@@ -54,45 +54,54 @@ func (c *proxyConfigResource) Configure(_ context.Context, request resource.Conf
 
 func (c *proxyConfigResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: "See [the documentation](https://api.permit.io/v2/redoc#tag/Proxy-Config/operation/create_proxy_config) for more information about proxy configs.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the proxy config",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"organization_id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the organization that owns the proxy config",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"project_id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the project that owns the proxy config",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"environment_id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Unique id of the environment that owns the proxy config",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"key": schema.StringAttribute{
-				Required: true,
+				MarkdownDescription: "Proxy Config is set to enable the Permit Proxy to make proxied requests as part of the Frontend AuthZ.\n\n",
+				Required:            true,
 			},
 			"name": schema.StringAttribute{
-				Required: true,
+				MarkdownDescription: "The name of the proxy config, for example: 'Stripe API",
+				Required:            true,
 			},
 			"auth_mechanism": schema.StringAttribute{
-				Required: true,
+				MarkdownDescription: "Default: \"Bearer\"\nEnum: \"Bearer\" \"Basic\" \"Headers\"\nProxy config auth mechanism will define the authentication mechanism that will be used to authenticate the request.\n\nBearer injects the secret into the Authorization header as a Bearer token,\n\nBasic injects the secret into the Authorization header as a Basic user:password,\n\nHeaders injects plain headers into the request.",
+				Required:            true,
 				Validators: []validator.String{
 					authMechanismValidator{},
 				},
 			},
 			"auth_secret": schema.SingleNestedAttribute{
-				Required: true,
+				Required:            true,
+				MarkdownDescription: "Proxy config secret is set to enable the Permit Proxy to make proxied requests to the backend service.",
 				Attributes: map[string]schema.Attribute{
 					"bearer": schema.StringAttribute{
 						Optional: true,
@@ -107,7 +116,8 @@ func (c *proxyConfigResource) Schema(_ context.Context, _ resource.SchemaRequest
 				},
 			},
 			"mapping_rules": schema.ListNestedAttribute{
-				Required: true,
+				Required:            true,
+				MarkdownDescription: "Proxy config mapping rules will include the rules that will be used to map the request to the backend service by a URL and a http method.",
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
 						"url": schema.StringAttribute{

internal/provider/relations/resource.go

@@ -37,27 +37,32 @@ func (c *RelationResource) Schema(_ context.Context, _ resource.SchemaRequest, r
 	attributes := common.CreateBaseResourceSchema()
 
 	attributes["subject_resource"] = schema.StringAttribute{
-		Required: true,
+		Required:            true,
+		MarkdownDescription: "The subject resource ID or key",
 		PlanModifiers: []planmodifier.String{
 			stringplanmodifier.RequiresReplace(),
 		},
 	}
 	attributes["object_resource"] = schema.StringAttribute{
-		Required: true,
+		Required:            true,
+		MarkdownDescription: "The object resource ID or key",
 		PlanModifiers: []planmodifier.String{
 			stringplanmodifier.RequiresReplace(),
 		},
 	}
 
 	attributes["subject_resource_id"] = schema.StringAttribute{
-		Computed: true,
+		MarkdownDescription: "The subject resource ID",
+		Computed:            true,
 	}
 	attributes["object_resource_id"] = schema.StringAttribute{
-		Computed: true,
+		MarkdownDescription: "The object resource ID",
+		Computed:            true,
 	}
 
 	response.Schema = schema.Schema{
-		Attributes: attributes,
+		Attributes:          attributes,
+		MarkdownDescription: "See [the documentation](https://api.permit.io/v2/redoc#tag/Resource-Relations/operation/create_resource_relation) for more information about Relations",
 	}
 }