chore: align meshstack_integration docs with API

Author: grubmeshi

docs/data-sources/integrations.md

@@ -3,12 +3,12 @@
 page_title: "meshstack_integrations Data Source - terraform-provider-meshstack"
 subcategory: ""
 description: |-
-  List of integrations.
+  Retrieve a list of integrations. Includes integrations that belong to your workspace as well as built-in integrations (replicator and metering). Platform administrators can retrieve any integration. Sensitive fields are masked with a hash value for security purposes.
 ---
 
 # meshstack_integrations (Data Source)
 
-List of integrations.
+Retrieve a list of integrations. Includes integrations that belong to your workspace as well as built-in integrations (replicator and metering). Platform administrators can retrieve any integration. Sensitive fields are masked with a hash value for security purposes.
 
 ## Example Usage
 
@@ -23,27 +23,27 @@ data "meshstack_integrations" "all" {
 
 ### Read-Only
 
-- `integrations` (Attributes List) List of integrations (see [below for nested schema](#nestedatt--integrations))
-- `workload_identity_federation` (Attributes) Workload identity federation information for built in integrations. (see [below for nested schema](#nestedatt--workload_identity_federation))
+- `integrations` (Attributes List) List of integrations. Each integration contains configuration for external CI/CD systems. (see [below for nested schema](#nestedatt--integrations))
+- `workload_identity_federation` (Attributes) Workload identity federation information for built-in integrations (replicator and metering). (see [below for nested schema](#nestedatt--workload_identity_federation))
 
 <a id="nestedatt--integrations"></a>
 ### Nested Schema for `integrations`
 
 Optional:
 
-- `status` (Attributes) (see [below for nested schema](#nestedatt--integrations--status))
+- `status` (Attributes) Status information of the integration. System-managed state. (see [below for nested schema](#nestedatt--integrations--status))
 
 Read-Only:
 
-- `metadata` (Attributes) (see [below for nested schema](#nestedatt--integrations--metadata))
-- `spec` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec))
+- `metadata` (Attributes) Metadata of the integration. Contains identifiers and ownership details. (see [below for nested schema](#nestedatt--integrations--metadata))
+- `spec` (Attributes) Specification of the integration. Contains configuration settings specific to the integration type. (see [below for nested schema](#nestedatt--integrations--spec))
 
 <a id="nestedatt--integrations--status"></a>
 ### Nested Schema for `integrations.status`
 
 Read-Only:
 
-- `is_built_in` (Boolean)
+- `is_built_in` (Boolean) Indicates whether this is a built-in integration (replicator or metering).
 - `workload_identity_federation` (Attributes) (see [below for nested schema](#nestedatt--integrations--status--workload_identity_federation))
 
 <a id="nestedatt--integrations--status--workload_identity_federation"></a>
@@ -89,26 +89,26 @@ Read-Only:
 
 Read-Only:
 
-- `owned_by_workspace` (String)
-- `uuid` (String)
+- `owned_by_workspace` (String) Identifier of the workspace that owns this integration.
+- `uuid` (String) UUID of the integration.
 
 
 <a id="nestedatt--integrations--spec"></a>
 ### Nested Schema for `integrations.spec`
 
 Read-Only:
 
-- `config` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config))
-- `display_name` (String)
+- `config` (Attributes) Configuration for the integration. Specifies one of github, gitlab, or azuredevops integration types. (see [below for nested schema](#nestedatt--integrations--spec--config))
+- `display_name` (String) Display name of the integration.
 
 <a id="nestedatt--integrations--spec--config"></a>
 ### Nested Schema for `integrations.spec.config`
 
 Optional:
 
-- `azuredevops` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config--azuredevops))
-- `github` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config--github))
-- `gitlab` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config--gitlab))
+- `azuredevops` (Attributes) Azure DevOps integration configuration. (see [below for nested schema](#nestedatt--integrations--spec--config--azuredevops))
+- `github` (Attributes) GitHub integration configuration. (see [below for nested schema](#nestedatt--integrations--spec--config--github))
+- `gitlab` (Attributes) GitLab integration configuration. (see [below for nested schema](#nestedatt--integrations--spec--config--gitlab))
 
 <a id="nestedatt--integrations--spec--config--azuredevops"></a>
 ### Nested Schema for `integrations.spec.config.azuredevops`
@@ -119,9 +119,9 @@ Required:
 
 Read-Only:
 
-- `base_url` (String)
-- `organization` (String)
-- `runner_ref` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config--azuredevops--runner_ref))
+- `base_url` (String) Base URL of the Azure DevOps instance (e.g., https://dev.azure.com).
+- `organization` (String) Azure DevOps organization name.
+- `runner_ref` (Attributes) Reference to the building block runner that executes Azure DevOps pipelines. (see [below for nested schema](#nestedatt--integrations--spec--config--azuredevops--runner_ref))
 
 <a id="nestedatt--integrations--spec--config--azuredevops--personal_access_token"></a>
 ### Nested Schema for `integrations.spec.config.azuredevops.personal_access_token`
@@ -136,8 +136,8 @@ Read-Only:
 
 Read-Only:
 
-- `kind` (String)
-- `uuid` (String)
+- `kind` (String) meshObject type, always meshBuildingBlockRunner.
+- `uuid` (String) UUID of the meshBuildingBlockRunner.
 
 
 
@@ -150,10 +150,10 @@ Required:
 
 Read-Only:
 
-- `app_id` (String)
-- `base_url` (String)
-- `owner` (String)
-- `runner_ref` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config--github--runner_ref))
+- `app_id` (String) GitHub App ID for authentication.
+- `base_url` (String) Base URL of the GitHub instance (e.g., https://github.com for GitHub.com or your GitHub Enterprise URL).
+- `owner` (String) GitHub organization or user that owns the repositories.
+- `runner_ref` (Attributes) Reference to the building block runner that executes GitHub workflows. (see [below for nested schema](#nestedatt--integrations--spec--config--github--runner_ref))
 
 <a id="nestedatt--integrations--spec--config--github--app_private_key"></a>
 ### Nested Schema for `integrations.spec.config.github.app_private_key`
@@ -168,8 +168,8 @@ Read-Only:
 
 Read-Only:
 
-- `kind` (String)
-- `uuid` (String)
+- `kind` (String) meshObject type, always meshBuildingBlockRunner.
+- `uuid` (String) UUID of the meshBuildingBlockRunner.
 
 
 
@@ -178,16 +178,16 @@ Read-Only:
 
 Read-Only:
 
-- `base_url` (String)
-- `runner_ref` (Attributes) (see [below for nested schema](#nestedatt--integrations--spec--config--gitlab--runner_ref))
+- `base_url` (String) Base URL of the GitLab instance (e.g., https://gitlab.com or your self-hosted GitLab URL).
+- `runner_ref` (Attributes) Reference to the building block runner that executes GitLab pipelines. (see [below for nested schema](#nestedatt--integrations--spec--config--gitlab--runner_ref))
 
 <a id="nestedatt--integrations--spec--config--gitlab--runner_ref"></a>
 ### Nested Schema for `integrations.spec.config.gitlab.runner_ref`
 
 Read-Only:
 
-- `kind` (String)
-- `uuid` (String)
+- `kind` (String) meshObject type, always meshBuildingBlockRunner.
+- `uuid` (String) UUID of the meshBuildingBlockRunner.
 
 
 

docs/resources/integration.md

@@ -3,12 +3,12 @@
 page_title: "meshstack_integration Resource - terraform-provider-meshstack"
 subcategory: ""
 description: |-
-  Manages a meshIntegration in meshStack. Integrations configure external CI/CD systems (GitHub, GitLab, Azure DevOps) for building block execution.
+  Manages a meshIntegration in meshStack. Integrations configure external CI/CD systems (GitHub, GitLab, Azure DevOps) for building block execution. Secrets in the integration configurations are encrypted and stored securely. When retrieving the integration, these fields are returned with a hash value instead of the actual secret, enabling drift detection while maintaining security.
 ---
 
 # meshstack_integration (Resource)
 
-Manages a meshIntegration in meshStack. Integrations configure external CI/CD systems (GitHub, GitLab, Azure DevOps) for building block execution.
+Manages a meshIntegration in meshStack. Integrations configure external CI/CD systems (GitHub, GitLab, Azure DevOps) for building block execution. Secrets in the integration configurations are encrypted and stored securely. When retrieving the integration, these fields are returned with a hash value instead of the actual secret, enabling drift detection while maintaining security.
 
 ## Example Usage
 
@@ -77,20 +77,20 @@ resource "meshstack_integration" "example_gitlab" {
 
 ### Required
 
-- `metadata` (Attributes) Metadata of the integration. (see [below for nested schema](#nestedatt--metadata))
-- `spec` (Attributes) Specification of the integration. (see [below for nested schema](#nestedatt--spec))
+- `metadata` (Attributes) Metadata of the integration. Contains identifiers and ownership details. (see [below for nested schema](#nestedatt--metadata))
+- `spec` (Attributes) Specification of the integration. Contains configuration settings specific to the integration type. (see [below for nested schema](#nestedatt--spec))
 
 ### Read-Only
 
 - `ref` (Attributes) Reference to integration, can be used in building block definitions. (see [below for nested schema](#nestedatt--ref))
-- `status` (Attributes) Status information of the integration. Computed by meshStack. (see [below for nested schema](#nestedatt--status))
+- `status` (Attributes) Status information of the integration. System-managed state computed by meshStack. (see [below for nested schema](#nestedatt--status))
 
 <a id="nestedatt--metadata"></a>
 ### Nested Schema for `metadata`
 
 Required:
 
-- `owned_by_workspace` (String) Identifier of the workspace that owns this integration.
+- `owned_by_workspace` (String) Identifier of the workspace that owns this integration. The integration will be owned by the workspace specified here.
 
 Read-Only:
 

internal/provider/integration_resource_schema.go

@@ -68,11 +68,13 @@ func (r *integrationResource) Schema(_ context.Context, _ resource.SchemaRequest
 	)
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "Manages a meshIntegration in meshStack. " +
-			"Integrations configure external CI/CD systems (GitHub, GitLab, Azure DevOps) for building block execution.",
+			"Integrations configure external CI/CD systems (GitHub, GitLab, Azure DevOps) for building block execution. " +
+			"Secrets in the integration configurations are encrypted and stored securely. When retrieving the integration, " +
+			"these fields are returned with a hash value instead of the actual secret, enabling drift detection while maintaining security.",
 
 		Attributes: map[string]schema.Attribute{
 			"metadata": schema.SingleNestedAttribute{
-				MarkdownDescription: "Metadata of the integration.",
+				MarkdownDescription: "Metadata of the integration. Contains identifiers and ownership details.",
 				Required:            true,
 				Attributes: map[string]schema.Attribute{
 					"uuid": schema.StringAttribute{
@@ -83,7 +85,7 @@ func (r *integrationResource) Schema(_ context.Context, _ resource.SchemaRequest
 						},
 					},
 					"owned_by_workspace": schema.StringAttribute{
-						MarkdownDescription: "Identifier of the workspace that owns this integration.",
+						MarkdownDescription: "Identifier of the workspace that owns this integration. The integration will be owned by the workspace specified here.",
 						Required:            true,
 						PlanModifiers: []planmodifier.String{
 							stringplanmodifier.RequiresReplace(),
@@ -92,7 +94,7 @@ func (r *integrationResource) Schema(_ context.Context, _ resource.SchemaRequest
 				},
 			},
 			"spec": schema.SingleNestedAttribute{
-				MarkdownDescription: "Specification of the integration.",
+				MarkdownDescription: "Specification of the integration. Contains configuration settings specific to the integration type.",
 				Required:            true,
 				Attributes: map[string]schema.Attribute{
 					"display_name": schema.StringAttribute{
@@ -182,7 +184,7 @@ func (r *integrationResource) Schema(_ context.Context, _ resource.SchemaRequest
 				},
 			},
 			"status": schema.SingleNestedAttribute{
-				MarkdownDescription: "Status information of the integration. Computed by meshStack.",
+				MarkdownDescription: "Status information of the integration. System-managed state computed by meshStack.",
 				Computed:            true,
 				Attributes: map[string]schema.Attribute{
 					"is_built_in": schema.BoolAttribute{