feat: remove archive_file resource deprecated status (#367)

* feat: remove `archive_file` resource deprecation notice - from what i gathered from the git history, this resource was introduced in `v2.3.0` in a deprecated state - discussion with the community involving @bendbennett resulted in the consideration of this deprecation being removed (see: #218) - since `v2.x` there has been a strong focus on keeping this provider limited to the `data` source, so some of this proposed change is taking a best guess at what makes sense while trying not to depart from the overall approach - i acknowledge that this appears to be in some ways orthogonal to the goal of the project, but there has been little movement in regards to this widely-requested feature (understandably so, based on reasons mentioned above). - there are cases, primarily in a remote build server context, where the design decisions/limitations of the `data` source makes the adoption and usage of this provider much more challenging. this change is proposed as a stop-gap until a larger focus is able to put on this project by the primary contributing team * docs: notes for `archive_file` `resource` versus `data` source * docs: changie release notes for #218 * docs: changie formatting Co-authored-by: Selena Goods <[email protected]> --------- Co-authored-by: Selena Goods <[email protected]>
hashicorp · Nov 19, 2024 · 84ef43b · 84ef43b
1 parent b320c74
commit 84ef43b
Show file tree

Hide file tree

Showing 10 changed files with 110 additions and 11 deletions.
diff --git a/.changes/unreleased/FEATURES-20240912-140136.yaml b/.changes/unreleased/FEATURES-20240912-140136.yaml
@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'resource/archive_file: Remove `deprecated` status'
+time: 2024-09-12T14:01:36.373922-04:00
+custom:
+    Issue: "218"
diff --git a/DESIGN.md b/DESIGN.md
@@ -1,15 +1,15 @@
 # Archive Provider Design
 
-The Archive Provider offers focussed functionality specifically geared towards archiving files. Specifically, 
-the provider data source generates zip archives of individual or multiple files. 
+The Archive Provider offers focussed functionality specifically geared towards archiving files. The provider generates
+zip archives of individual or multiple files.
 
 Below we have a collection of _Goals_ and _Patterns_: they represent the guiding principles applied during the
 development of this provider. Some are in place, others are ongoing processes, others are still just inspirational.
 
 ## Goals
 
 * [_Stability over features_](.github/CONTRIBUTING.md)
-* Provide data source for generating zip archives.
+* Provide a mechanism for generating zip archives.
 
 General to development:
 

diff --git a/docs/data-sources/file.md b/docs/data-sources/file.md
@@ -2,12 +2,12 @@
 page_title: "archive_file Data Source - terraform-provider-archive"
 subcategory: ""
 description: |-
-  Generates an archive from content, a file, or directory of files.
+  Generates an archive from content, a file, or directory of files. The archive is built during the terraform plan, so you must persist the archive through to the terraform apply. See the archive_file resource for an alternative if you cannot persist the file, such as in a multi-phase CI or build server context.
 ---
 
 # archive_file (Data Source)
 
-Generates an archive from content, a file, or directory of files.
+Generates an archive from content, a file, or directory of files. The archive is built during the terraform plan, so you must persist the archive through to the terraform apply. See the `archive_file` resource for an alternative if you cannot persist the file, such as in a multi-phase CI or build server context.
 
 ## Example Usage
 

diff --git a/docs/resources/file.md b/docs/resources/file.md
@@ -1,16 +1,56 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "archive_file Resource - terraform-provider-archive"
 subcategory: ""
 description: |-
-  NOTE: This resource is deprecated, use data source instead.
+  Generates an archive from content, a file, or directory of files.
 ---
 
 # archive_file (Resource)
 
-**NOTE**: This resource is deprecated, use data source instead.
+Generates an archive from content, a file, or directory of files.
 
+## Example Usage
 
+```terraform
+# Archive a single file.
+
+resource "archive_file" "init" {
+  type        = "zip"
+  source_file = "${path.module}/init.tpl"
+  output_path = "${path.module}/files/init.zip"
+}
+```
+
+```terraform
+# Archive multiple files and exclude file.
+
+resource "archive_file" "dotfiles" {
+  type        = "zip"
+  output_path = "${path.module}/files/dotfiles.zip"
+  excludes    = ["${path.module}/unwanted.zip"]
+
+  source {
+    content  = data.template_file.vimrc.rendered
+    filename = ".vimrc"
+  }
+
+  source {
+    content  = data.template_file.ssh_config.rendered
+    filename = ".ssh/config"
+  }
+}
+```
+
+```terraform
+# Archive a file to be used with Lambda using consistent file mode
+
+resource "archive_file" "lambda_my_function" {
+  type             = "zip"
+  source_file      = "${path.module}/../lambda/my-function/index.js"
+  output_file_mode = "0666"
+  output_path      = "${path.module}/files/lambda-my-function.js.zip"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/examples/resources/file/lambda.tf b/examples/resources/file/lambda.tf
@@ -0,0 +1,8 @@
+# Archive a file to be used with Lambda using consistent file mode
+
+resource "archive_file" "lambda_my_function" {
+  type             = "zip"
+  source_file      = "${path.module}/../lambda/my-function/index.js"
+  output_file_mode = "0666"
+  output_path      = "${path.module}/files/lambda-my-function.js.zip"
+}
diff --git a/examples/resources/file/multiple-files.tf b/examples/resources/file/multiple-files.tf
@@ -0,0 +1,17 @@
+# Archive multiple files and exclude file.
+
+resource "archive_file" "dotfiles" {
+  type        = "zip"
+  output_path = "${path.module}/files/dotfiles.zip"
+  excludes    = ["${path.module}/unwanted.zip"]
+
+  source {
+    content  = data.template_file.vimrc.rendered
+    filename = ".vimrc"
+  }
+
+  source {
+    content  = data.template_file.ssh_config.rendered
+    filename = ".ssh/config"
+  }
+}
diff --git a/examples/resources/file/resource.tf b/examples/resources/file/resource.tf
@@ -0,0 +1,7 @@
+# Archive a single file.
+
+resource "archive_file" "init" {
+  type        = "zip"
+  source_file = "${path.module}/init.tpl"
+  output_path = "${path.module}/files/init.zip"
+}
diff --git a/internal/provider/data_source_archive_file.go b/internal/provider/data_source_archive_file.go
@@ -46,7 +46,10 @@ func (d *archiveFileDataSource) ConfigValidators(context.Context) []datasource.C
 
 func (d *archiveFileDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		Description: "Generates an archive from content, a file, or directory of files.",
+		Description: "Generates an archive from content, a file, or directory of files. " +
+			"The archive is built during the terraform plan, so you must persist the archive through to the terraform apply. " +
+			"See the `archive_file` resource for an alternative if you cannot persist the file, " +
+			"such as in a multi-phase CI or build server context.",
 		Blocks: map[string]schema.Block{
 			"source": schema.SetNestedBlock{
 				Description: "Specifies attributes of a single source file to include into the archive. " +

diff --git a/internal/provider/resource_archive_file.go b/internal/provider/resource_archive_file.go
@@ -44,8 +44,7 @@ func (d *archiveFileResource) ConfigValidators(context.Context) []resource.Confi
 
 func (d *archiveFileResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		Description:        `**NOTE**: This resource is deprecated, use data source instead.`,
-		DeprecationMessage: `**NOTE**: This resource is deprecated, use data source instead.`,
+		Description: "Generates an archive from content, a file, or directory of files.",
 		Blocks: map[string]schema.Block{
 			"source": schema.SetNestedBlock{
 				Description: "Specifies attributes of a single source file to include into the archive. " +

diff --git a/templates/resources/file.md.tmpl b/templates/resources/file.md.tmpl
@@ -0,0 +1,20 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+## Example Usage
+
+{{ tffile "examples/resources/file/resource.tf" }}
+
+{{ tffile "examples/resources/file/multiple-files.tf" }}
+
+{{ tffile "examples/resources/file/lambda.tf" }}
+
+{{ .SchemaMarkdown | trimspace }}