HCP Packer new data sources and nomenclature changes

.changelog/726.txt

@@ -0,0 +1,33 @@
+```release-note:breaking-change
+`data.hcp_packer_iteration`: Removed the `incremental_version` attribute. Use the `fingerprint`, `id` or `uuid` attributes instead.
+```
+
+```release-note:breaking-change
+`hcp_packer_channel_assignment`: Removed the `iteration_version` attribute. Use the `version_fingerprint` attribute instead.
+```
+
+```release-note:breaking-change
+`hcp_packer_channel_assignment`: Removed the `iteration_id` attribute. Use the `version_fingerprint` attribute instead.
+```
+
+```release-note:deprecation
+`hcp_packer_channel_assignment`: The `iteration_fingerprint` attribute is now deprecated and will be removed in a future release. 
+Refer to the `version_fingerprint` attribute release notes for more information.
+```
+
+```release-note:deprecation
+`data.hcp_packer_image`: This data source will be removed in a future release, and is superseded by `data.hcp_packer_artifact`
+```
+
+```release-note:deprecation
+`data.hcp_packer_iteration`: This data source will be removed in a future release, and is superseded by `data.hcp_packer_version`
+```
+
+```release-note:feature
+`data.hcp_packer_artifact`: Added the `hcp_packer_artifact` data source, which replaces `data.hcp_packer_image`
+```
+
+```release-note:feature
+`data.hcp_packer_version`: Added the `hcp_packer_version` data source, which replaces `data.hcp_packer_iteration`
+```
+

docs/data-sources/packer_artifact.md

@@ -0,0 +1,93 @@
+---
+page_title: "Data Source hcp_packer_artifact - terraform-provider-hcp"
+subcategory: "HCP Packer"
+description: |-
+  The HCP Packer Artifact data source retrieves information about an Artifact.
+---
+
+# hcp_packer_artifact (Data Source)
+
+The HCP Packer Artifact data source retrieves information about an Artifact.
+
+## Example Usage
+
+### Single artifact sourcing
+
+```terraform
+data "hcp_packer_artifact" "ubuntu-east" {
+  bucket_name  = "hardened-ubuntu-16-04"
+  channel_name = "production"
+  platform     = "aws"
+  region       = "us-east-1"
+}
+
+output "packer-registry-ubuntu-east-1" {
+  value = data.hcp_packer_artifact.ubuntu-east.external_identifier
+}
+```
+
+~> **Note:** The `channel` attribute in this data source may incur a billable request to HCP Packer. This attribute is intended for convenience when using a single artifact. When sourcing multiple artifacts from a single version, the `hcp_packer_version` data source is the alternative for querying a channel just once.
+
+### Multiple artifact sourcing from a single version
+
+```terraform
+data "hcp_packer_version" "hardened-source" {
+  bucket_name  = "hardened-ubuntu-16-04"
+  channel_name = "production"
+}
+
+data "hcp_packer_artifact" "ubuntu-east" {
+  bucket_name         = "hardened-ubuntu-16-04"
+  version_fingerprint = data.hcp_packer_version.hardened-source.fingerprint
+  platform            = "aws"
+  region              = "us-east-1"
+}
+
+data "hcp_packer_artifact" "ubuntu-west" {
+  bucket_name         = "hardened-ubuntu-16-04"
+  version_fingerprint = data.hcp_packer_version.hardened-source.fingerprint
+  platform            = "aws"
+  region              = "us-west-1"
+}
+
+output "packer-registry-ubuntu-east-1" {
+  value = data.hcp_packer_artifact.ubuntu-east.external_identifier
+}
+
+output "packer-registry-ubuntu-west-1" {
+  value = data.hcp_packer_artifact.ubuntu-west.external_identifier
+}
+```
+
+~> **Note:** This data source only returns the first found artifact's metadata filtered by the given arguments, from the returned list of artifacts associated with the specified version. Therefore, if multiple artifacts exist in the same region, it will only pick one of them. In this case, you can filter artifacts by a source build name (Ex: `amazon-ebs.example`) using the `component_type` optional argument.
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `bucket_name` (String) The name of the HCP Packer Bucket where the Artifact is located.
+- `platform` (String) Name of the platform where the HCP Packer Artifact is stored.
+- `region` (String) The Region where the HCP Packer Artifact is stored, if any.
+
+### Optional
+
+- `channel_name` (String) The name of the HCP Packer Channel the Version containing this Artifact is assigned to.
+The Version currently assigned to the Channel will be fetched. 
+Exactly one of `channel_name` or `version_fingerprint` must be provided.
+- `component_type` (String) Name of the Packer builder that built this Artifact. Ex: `amazon-ebs.example`.
+- `project_id` (String) The ID of the HCP Organization where the Artifact is located
+- `version_fingerprint` (String) The fingerprint of the HCP Packer Version where the Artifact is located. 
+If provided in the config, it is used to fetch the Version.
+Exactly one of `channel_name` or `version_fingerprint` must be provided.
+
+### Read-Only
+
+- `build_id` (String) The ULID of the HCP Packer Build where the Artifact is located.
+- `created_at` (String) The creation time of this HCP Packer Artifact.
+- `external_identifier` (String) An external identifier for the HCP Packer Artifact.
+- `id` (String) The ULID of the HCP Packer Artifact.
+- `labels` (Map of String) Labels associated with the build containing this image.
+- `organization_id` (String) The ID of the HCP Organization where the Artifact is located
+- `packer_run_uuid` (String) The UUID of the build containing this image.
+- `revoke_at` (String) The revocation time of the HCP Packer Version containing this Artifact. This field will be null for any Version that has not been revoked or scheduled for revocation.

docs/data-sources/packer_image.md

@@ -9,57 +9,7 @@ description: |-
 
 The Packer Image data source gets an image associated with an iteration, either from a specific iteration or from the iteration assigned to a given Channel.
 
-## Example Usage
-
-### Single image sourcing
-
-```terraform
-data "hcp_packer_image" "baz" {
-  bucket_name    = "hardened-ubuntu-16-04"
-  cloud_provider = "aws"
-  channel        = "production"
-  region         = "us-east-1"
-}
-
-output "packer-registry-ubuntu-east-1" {
-  value = data.hcp_packer_image.baz.cloud_image_id
-}
-```
-
-~> **Note:** The `channel` attribute in this data source may incur a billable request to HCP Packer. This attribute is intended for convenience when using a single image. When sourcing multiple images from a single iteration, the `hcp_packer_iteration` data source is the alternative for querying a channel just once.
-
-### Multiple image sourcing from a single iteration
-
-```terraform
-data "hcp_packer_iteration" "hardened-source" {
-  bucket_name = "hardened-ubuntu-16-04"
-  channel     = "production"
-}
-
-data "hcp_packer_image" "foo" {
-  bucket_name    = "hardened-ubuntu-16-04"
-  cloud_provider = "aws"
-  iteration_id   = data.hcp_packer_iteration.hardened-source.ulid
-  region         = "us-east-1"
-}
-
-data "hcp_packer_image" "bar" {
-  bucket_name    = "hardened-ubuntu-16-04"
-  cloud_provider = "aws"
-  iteration_id   = data.hcp_packer_iteration.hardened-source.ulid
-  region         = "us-west-1"
-}
-
-output "packer-registry-ubuntu-east-1" {
-  value = data.hcp_packer_image.foo.cloud_image_id
-}
-
-output "packer-registry-ubuntu-west-1" {
-  value = data.hcp_packer_image.bar.cloud_image_id
-}
-```
-
-~> **Note:** This data source only returns the first found image's metadata filtered by the given arguments, from the returned list of images associated with the specified iteration. Therefore, if multiple images exist in the same region, it will only pick one of them. In this case, you can filter images by a source build name (Ex: `amazon-ebs.example`) using the `component_type` optional argument.
+~> **Deprecated:** This data source is deprecated and will be removed in a future release. Please use the [`hcp_packer_artifact`](./packer_artifact) data source instead.
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/packer_iteration.md

@@ -9,14 +9,7 @@ description: |-
 
 The Packer Image data source iteration gets the most recent iteration (or build) of an image, given a channel.
 
-## Example Usage
-
-```terraform
-data "hcp_packer_iteration" "hardened-source" {
-  bucket_name = "hardened-ubuntu-16-04"
-  channel     = "megan-test"
-}
-```
+~> **Deprecated:** This data source is deprecated and will be removed in a future release. Please use the [`hcp_packer_version`](./packer_version) data source instead.
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -39,7 +32,6 @@ If a project is not configured in the HCP Provider config block, the oldest proj
 - `created_at` (String) Creation time of this iteration
 - `fingerprint` (String) The unique fingerprint associated with this iteration; often a git sha.
 - `id` (String) The ID of this resource.
-- `incremental_version` (Number, Deprecated) Incremental version of this iteration
 - `organization_id` (String) The ID of the organization this HCP Packer registry is located in.
 - `revoke_at` (String) The revocation time of this iteration. This field will be null for any iteration that has not been revoked or scheduled for revocation.
 - `ulid` (String) The ULID of this iteration.

docs/data-sources/packer_version.md

@@ -0,0 +1,43 @@
+---
+page_title: "hcp_packer_version Data Source - terraform-provider-hcp"
+subcategory: "HCP Packer"
+description: |-
+  The HCP Packer Version data source retrieves information about a Version.
+---
+
+# hcp_packer_version (Data Source)
+
+The HCP Packer Version data source retrieves information about a Version.
+
+## Example Usage
+
+```terraform
+data "hcp_packer_version" "hardened-source" {
+  bucket_name  = "hardened-ubuntu-16-04"
+  channel_name = "dev"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `bucket_name` (String) The name of the HCP Packer Bucket where the Version is located
+- `channel_name` (String) The name of the HCP Packer Channel the Version is assigned to.
+The version currently assigned to the Channel will be fetched.
+
+### Optional
+
+- `project_id` (String) The ID of the HCP Organization where the Version is located
+
+### Read-Only
+
+- `author_id` (String) The name of the person who created this HCP Packer Version
+- `created_at` (String) The creation time of this HCP Packer Version
+- `fingerprint` (String) The fingerprint of the HCP Packer Version
+- `id` (String) The ULID of the HCP Packer Version
+- `name` (String) The name of the HCP Packer Version
+- `organization_id` (String) The ID of the HCP Organization where the Version is located
+- `revoke_at` (String) The revocation time of this HCP Packer Version. This field will be null for any Version that has not been revoked or scheduled for revocation
+- `updated_at` (String) The last time this HCP Packer Version was updated

docs/guides/packer-channel-management.md

@@ -18,34 +18,29 @@ resource "hcp_packer_channel" "advanced" {
 }
 
 resource "hcp_packer_channel_assignment" "advanced" {
-  bucket_name  = hcp_packer_channel.advanced.bucket_name
-  channel_name = hcp_packer_channel.advanced.name
-
-  # Exactly one of version, id, or fingerprint must be set:
-  iteration_version = 12
-  # iteration_id = "01H1SF9NWAK8AP25PAWDBGZ1YD"
-  # iteration_fingerprint = "01H1ZMW0Q2W6FT4FK27FQJCFG7"
+  bucket_name         = hcp_packer_channel.advanced.bucket_name
+  channel_name        = hcp_packer_channel.advanced.name
+  version_fingerprint = "01H1ZMW0Q2W6FT4FK27FQJCFG7"
 }
 ```
 
-## Setting the channel assignment to the latest complete iteration
+## Setting the channel assignment to the latest complete version
 
 ```terraform
-data "hcp_packer_iteration" "alpine_latest" {
-  bucket_name = "alpine"
-  channel     = "latest"
+data "hcp_packer_version" "alpine_latest" {
+  bucket_name  = "alpine"
+  channel_name = "latest"
 }
 
 resource "hcp_packer_channel" "alpine_advanced" {
   name        = "advanced"
-  bucket_name = data.hcp_packer_iteration.alpine_latest.bucket_name
+  bucket_name = data.hcp_packer_version.alpine_latest.bucket_name
 }
 
 resource "hcp_packer_channel_assignment" "alpine_advanced" {
-  bucket_name  = hcp_packer_channel.alpine_advanced.bucket_name
-  channel_name = hcp_packer_channel.alpine_advanced.name
-
-  iteration_version = data.hcp_packer_iteration.alpine_latest.incremental_version
+  bucket_name         = hcp_packer_channel.alpine_advanced.bucket_name
+  channel_name        = hcp_packer_channel.alpine_advanced.name
+  version_fingerprint = data.hcp_packer_version.alpine_latest.fingerprint
 }
 ```
 
@@ -68,19 +63,17 @@ Optionally, you can use Terraform functions/expressions to filter the list of bu
 
 Channel assignment for automatically created channels can be managed in many ways. A nonexhaustive example configuration is provided below.
 
-The `iteration_id` attribute is used for example purposes, but any of the three iteration identifier attributes can be used.
-
 ```terraform
-data "hcp_packer_iteration" "all_latest" {
+data "hcp_packer_version" "all_latest" {
   for_each = data.hcp_packer_bucket_names.all.names
 
-  bucket_name = each.key
-  channel     = "latest"
+  bucket_name  = each.key
+  channel_name = "latest"
 }
 
-data "hcp_packer_iteration" "bucket3_staging" {
-  bucket_name = "bucket3"
-  channel     = "staging"
+data "hcp_packer_version" "bucket3_staging" {
+  bucket_name  = "bucket3"
+  channel_name = "staging"
 }
 
 resource "hcp_packer_channel_assignment" "release" {
@@ -89,15 +82,15 @@ resource "hcp_packer_channel_assignment" "release" {
       for bucketName in keys(hcp_packer_channel.release) :
       bucketName => "none"
     },
-    { # Assigning channels that match a filter to an iteration fetched from another channel
+    { # Assigning channels that match a filter to an version fetched from another channel
       for bucketName in keys(hcp_packer_channel.release) :
-      bucketName => data.hcp_packer_iteration.all_latest[bucketName].id
+      bucketName => data.hcp_packer_version.all_latest[bucketName].fingerprint
       if endswith(bucketName, "-dev")
     },
     { # Individual channel assignments
       "bucket1" : "01H1SF9NWAK8AP25PAWDBGZ1YD"
       "bucket2" : "01H28NJ7WPCZA0FZZ8G3FGGTAF"
-      "bucket3" : data.hcp_packer_iteration.bucket3_staging.id
+      "bucket3" : data.hcp_packer_version.bucket3_staging.fingerprint
     }
   )
 
@@ -106,14 +99,14 @@ resource "hcp_packer_channel_assignment" "release" {
   # in the `hcp_packer_channel.release` resource if desired.
   channel_name = hcp_packer_channel.release[each.key].name
 
-  iteration_id = each.value
+  version_fingerprint = each.value
 }
 ```
 
 You are not required to configure an assignment for every channel at the same time as automatic channel creation. Using Terraform builtin functions/expressions, it is possible to limit which channels should have assignments configured by default.
 
-The default value used in the example is `"none"`, which causes Terraform to set the channel to have no assigned iteration and continue to ensure that an iteration is not assigned elsewhere. Each of the three iteration identifier attributes has a "zero value" for this purpose: `iteration_id` and `iteration_fingerprint` both use `"none"`, and `iteration_version` uses `0`. The default value can also be set to `null` if you want to ensure that every channel has an assignment defined explicitly rather than using a default.
+The default value used in the example is `"none"`, which causes Terraform to set the channel to have no assigned version and continue to ensure that a version is not assigned elsewhere. 
 
 If an invalid bucket name is provided in the `for_each` map, an error will be thrown. This helps to ensure that the configuration doesn't contain orphaned values, but can cause plan failures when buckets are deleted. If this behavior is undesirable, filter out invalid buckets from the result of the `merge` function.
 
-An [example module](https://github.com/hashicorp/terraform-provider-hcp/tree/main/examples/guides/packer_channel_management/bucket_names/example_module) is available that includes options to leave select channels unmanaged, require explicit configurations for select channels, ignore invalid bucket names in the configuration, and automatically assign an iteration fetched from another channel.
+An [example module](https://github.com/hashicorp/terraform-provider-hcp/tree/main/examples/guides/packer_channel_management/bucket_names/example_module) is available that includes options to leave select channels unmanaged, require explicit configurations for select channels, ignore invalid bucket names in the configuration, and automatically assign a version fetched from another channel.

docs/resources/packer_channel.md

@@ -23,7 +23,7 @@ resource "hcp_packer_channel" "staging" {
 
 ### Required
 
-- `bucket_name` (String) The slug of the HCP Packer Registry bucket where the channel should be created.
+- `bucket_name` (String) The name of the HCP Packer Registry bucket where the channel should be created.
 - `name` (String) The name of the channel being managed.
 
 ### Optional