Misc doc updates (#119)

* add note about release stage for internal contributors

* merge quick-start context into overview
and remove quick-start

* remove federation example
as that feature is still in beta

* add federation beta banner to consul cluster

* Hashicorp -> HashiCorp TM

* update header
to one that more accurately represents content

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,10 @@
 <!--
 Adding a new resource or datasource? Use this checklist to get started: https://github.com/hashicorp/terraform-provider-hcp/blob/main/contributing/checklist-resource.md
+
+HashiCorp contributors, please consider: what stage of release is your feature in?
+If the feature is for internal Hashicorp usage only, it should be maintained on a feature branch until ready for beta release.
+If the feature is for select beta users, it can be merged to main and released as a new minor version. A beta banner must be added to the documentation.
+If the feature is ready for all HCP users, it can be merged to main and released as a new minor version. You may wish to coordinate with the release of the feature in the UI.
 -->
 
 ### :hammer_and_wrench: Description

docs/index.md

@@ -18,7 +18,18 @@ See the Release Notes on Github for more detail. Please upgrade to the patch v0.
 
 The HCP provider supports authentication via a Client ID and a Client Secret. The [authentication guide](guides/auth.md) describes how to obtain client credentials.
 
-## Example Usage
+## Getting Started
+
+Everything in HashiCorp Cloud Platform (HCP) starts with the HashiCorp Virtual Network (HVN).
+
+HVNs enable you to deploy HashiCorp Cloud products without having to manage the networking details. They give you a simple setup for creating a network on AWS, in the region of your choice, and with the option to specify a CIDR range.
+
+Creating a network peering from your HVN will allow you to connect and launch AWS resources to your HCP account.
+Peer your Amazon VPC with your HVN to enable resource access. After creating, you will need to accept the peering request and set up your VPC’s security groups and routing table on your AWS account. The Amazon VPC can be managed with the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs).
+
+Once you have an HVN, HCP Consul and HCP Vault enable you to quickly deploy Consul and Vault clusters in AWS across a variety of environments while offloading the operations burden to the SRE experts at HashiCorp.
+
+One final note: with a fully deployed HCP Consul, you need to deploy Consul clients inside of the peered VPC to fully access your Consul features.
 
 ```terraform
 // Pin the version
@@ -77,14 +88,6 @@ resource "hcp_consul_cluster" "example" {
   tier       = "development"
 }
 
-// Create a secondary Consul cluster to federate with the existing Consul cluster
-resource "hcp_consul_cluster" "example_secondary" {
-  hvn_id       = hcp_hvn.example_hvn.hvn_id
-  cluster_id   = "hcp-tf-example-consul-cluster-secondary"
-  tier         = "development"
-  primary_link = hcp_consul_cluster.example.self_link
-}
-
 // Create a Vault cluster in the same region and cloud provider as the HVN
 resource "hcp_vault_cluster" "example" {
   cluster_id = "hcp-tf-example-vault-cluster"

docs/resources/consul_cluster.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "hcp_consul_cluster Resource - terraform-provider-hcp"
 subcategory: ""
 description: |-
@@ -27,6 +26,7 @@ resource "hcp_consul_cluster" "example" {
 }
 ```
 
+-> **Note:** The `primary_link` attribute is related to federation, a feature that is currently in private beta.
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -83,4 +83,4 @@ Import is supported using the following syntax:
 ```shell
 # The import ID is {cluster_id}
 terraform import hcp_consul_cluster.example consul-cluster
-```
+```

examples/provider/provider.tf

@@ -54,14 +54,6 @@ resource "hcp_consul_cluster" "example" {
   tier       = "development"
 }
 
-// Create a secondary Consul cluster to federate with the existing Consul cluster
-resource "hcp_consul_cluster" "example_secondary" {
-  hvn_id       = hcp_hvn.example_hvn.hvn_id
-  cluster_id   = "hcp-tf-example-consul-cluster-secondary"
-  tier         = "development"
-  primary_link = hcp_consul_cluster.example.self_link
-}
-
 // Create a Vault cluster in the same region and cloud provider as the HVN
 resource "hcp_vault_cluster" "example" {
   cluster_id = "hcp-tf-example-vault-cluster"

templates/index.md.tmpl

@@ -18,7 +18,18 @@ See the Release Notes on Github for more detail. Please upgrade to the patch v0.
 
 The HCP provider supports authentication via a Client ID and a Client Secret. The [authentication guide](guides/auth.md) describes how to obtain client credentials.
 
-## Example Usage
+## Getting Started
+
+Everything in HashiCorp Cloud Platform (HCP) starts with the HashiCorp Virtual Network (HVN).
+
+HVNs enable you to deploy HashiCorp Cloud products without having to manage the networking details. They give you a simple setup for creating a network on AWS, in the region of your choice, and with the option to specify a CIDR range.
+
+Creating a network peering from your HVN will allow you to connect and launch AWS resources to your HCP account.
+Peer your Amazon VPC with your HVN to enable resource access. After creating, you will need to accept the peering request and set up your VPC’s security groups and routing table on your AWS account. The Amazon VPC can be managed with the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs).
+
+Once you have an HVN, HCP Consul and HCP Vault enable you to quickly deploy Consul and Vault clusters in AWS across a variety of environments while offloading the operations burden to the SRE experts at HashiCorp.
+
+One final note: with a fully deployed HCP Consul, you need to deploy Consul clients inside of the peered VPC to fully access your Consul features.
 
 {{tffile "examples/provider/provider.tf"}}
 

templates/resources/consul_cluster.md.tmpl

@@ -0,0 +1,23 @@
+---
+page_title: "{{.Type}} {{.Name}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Type}} ({{.Name}})
+
+{{ .Description | trimspace }}
+
+## Example Usage
+
+{{ tffile "examples/resources/hcp_consul_cluster/resource.tf" }}
+
+-> **Note:** The `primary_link` attribute is related to federation, a feature that is currently in private beta.
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+Import is supported using the following syntax:
+
+{{ codefile "shell" "examples/resources/hcp_consul_cluster/import.sh" }}