From 84ef43bb64e23bcbcb77d72af1198ae124d06ffd Mon Sep 17 00:00:00 2001 From: Cody Maust Date: Tue, 19 Nov 2024 14:27:09 -0500 Subject: [PATCH] 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 --------- Co-authored-by: Selena Goods --- .../unreleased/FEATURES-20240912-140136.yaml | 5 ++ DESIGN.md | 6 +-- docs/data-sources/file.md | 4 +- docs/resources/file.md | 46 +++++++++++++++++-- examples/resources/file/lambda.tf | 8 ++++ examples/resources/file/multiple-files.tf | 17 +++++++ examples/resources/file/resource.tf | 7 +++ internal/provider/data_source_archive_file.go | 5 +- internal/provider/resource_archive_file.go | 3 +- templates/resources/file.md.tmpl | 20 ++++++++ 10 files changed, 110 insertions(+), 11 deletions(-) create mode 100644 .changes/unreleased/FEATURES-20240912-140136.yaml create mode 100644 examples/resources/file/lambda.tf create mode 100644 examples/resources/file/multiple-files.tf create mode 100644 examples/resources/file/resource.tf create mode 100644 templates/resources/file.md.tmpl diff --git a/.changes/unreleased/FEATURES-20240912-140136.yaml b/.changes/unreleased/FEATURES-20240912-140136.yaml new file mode 100644 index 00000000..460a7f1e --- /dev/null +++ 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 index c3776e31..77d6b1f2 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # 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. @@ -9,7 +9,7 @@ development of this provider. Some are in place, others are ongoing processes, o ## 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 index 7a6246a5..ad54a602 100644 --- 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 index 11ab1c66..e8dad5bd 100644 --- 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 diff --git a/examples/resources/file/lambda.tf b/examples/resources/file/lambda.tf new file mode 100644 index 00000000..5d7b8e46 --- /dev/null +++ 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 new file mode 100644 index 00000000..3a138319 --- /dev/null +++ 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 new file mode 100644 index 00000000..8a4963de --- /dev/null +++ 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 index c65755bf..990e3e6a 100644 --- 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 index 22368fe6..fe06d56f 100644 --- 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 new file mode 100644 index 00000000..a99c1089 --- /dev/null +++ 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 }}