From 672ae729fad755ad3b6f170209035ae5f746b000 Mon Sep 17 00:00:00 2001 From: The Magician Date: Tue, 30 Oct 2018 15:39:36 -0700 Subject: [PATCH] Update provider docs for 2.0.0 (#2360) /cc @rileykarson --- website/docs/getting_started.html.markdown | 1 + website/docs/index.html.markdown | 9 +++-- website/docs/provider_reference.html.markdown | 35 +++++++++++++++---- website/docs/provider_versions.html.markdown | 7 ++-- 4 files changed, 40 insertions(+), 12 deletions(-) diff --git a/website/docs/getting_started.html.markdown b/website/docs/getting_started.html.markdown index 3b0f8abf..953784d6 100644 --- a/website/docs/getting_started.html.markdown +++ b/website/docs/getting_started.html.markdown @@ -225,6 +225,7 @@ the provider block (including how you can eliminate it entirely!). You can also check out the [GCP Community tutorials](https://cloud.google.com/community/tutorials/) such as: + * [Getting started with Terraform on Google Cloud Platform](https://cloud.google.com/community/tutorials/getting-started-on-gcp-with-terraform) * [Managing GCP Projects with Terraform](https://cloud.google.com/community/tutorials/managing-gcp-projects-with-terraform) * [Modular Load Balancing with Terraform](https://cloud.google.com/community/tutorials/modular-load-balancing-with-terraform) diff --git a/website/docs/index.html.markdown b/website/docs/index.html.markdown index 708c69f0..5b49f289 100644 --- a/website/docs/index.html.markdown +++ b/website/docs/index.html.markdown @@ -76,8 +76,11 @@ the issue! ## Contributing If you'd like to help extend the Google provider, we gladly accept community -contributions! Check out the [provider README](https://github.com/terraform-providers/terraform-provider-google) -for instructions about getting started developing, the [HashiCorp contribution guidelines](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md) +contributions! Pull requests should be made against [Magic Modules](https://github.com/GoogleCloudPlatform/magic-modules) +to ensure they are applied to both `google` and `google-beta`. + +Check out the [Magic Modules setup guide](https://github.com/GoogleCloudPlatform/magic-modules#one-time-setup) to get set up, the [provider README](https://github.com/terraform-providers/terraform-provider-google) +for instructions about running your generated code, the [HashiCorp contribution guidelines](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md) for a Terraform provider development overview, and the [Google provider contribution guidelines](https://github.com/terraform-providers/terraform-provider-google/blob/master/.github/CONTRIBUTING.md) for our provider-specific advice. @@ -85,7 +88,7 @@ for our provider-specific advice. The Google provider supports generally available (GA) and Beta GCP features. We are focusing on filling out general GA feature coverage and on adding support -for beta features that customers request. So if you need us to support a feature +for beta features that customers request. If you need us to support a feature whether GA or beta, please [file a feature request](https://github.com/terraform-providers/terraform-provider-google/issues/new?template=enhancement.md)! If you're interested in using Alpha GCP features, you should still [file a feature request](https://github.com/terraform-providers/terraform-provider-google/issues/new?template=enhancement.md) diff --git a/website/docs/provider_reference.html.markdown b/website/docs/provider_reference.html.markdown index c4aa8a2d..21829241 100644 --- a/website/docs/provider_reference.html.markdown +++ b/website/docs/provider_reference.html.markdown @@ -11,14 +11,15 @@ description: |- -> We recently introduced the `google-beta` provider. See [Provider Versions](https://terraform.io/docs/providers/google/provider_versions.html) for more details on how to use `google-beta`. -The `google` provider block is used to configure default values for your GCP -project and location (`zone` and `region`), and add your credentials. +The `google` and `google-beta` provider blocks are used to configure default values for +your GCP project and location (`zone` and `region`), and add your credentials. -> You can avoid using a provider block by using environment variables. Every -field of the `google` provider is optional. If you want to share configs between -environments and deploy to different projects, try it out! +field of `google` and `google-beta` is inferred from your environment when it +has not been explicitly set. Even better - the GA and beta providers will both +share the same values. -## Example Usage +## Example Usage - Basic provider blocks ```hcl provider "google" { @@ -38,9 +39,31 @@ provider "google-beta" { } ``` +## Example Usage - Using beta features with `google-beta` + +To use Google Cloud Platform features that are in beta, explicitly set the provider for your +resource to `google-beta`. See [Provider Versions](https://terraform.io/docs/providers/google/provider_versions.html) +for a full reference on how to use different GCP versions with the Google provider. + +```hcl +resource "google_compute_instance" "ga-instance" { + provider = "google" + + # ... +} + +resource "google_compute_instance" "beta-instance" { + provider = "google-beta" + + # ... +} +``` + + ## Configuration Reference -The following keys can be used to configure the provider. +The following keys can be used to configure the provider. Both `google` and `google-beta` +share the same configuration. * `credentials` - (Optional) The path or contents of a file that contains your service account private key in JSON format. You can download your existing diff --git a/website/docs/provider_versions.html.markdown b/website/docs/provider_versions.html.markdown index 463d1003..204e3ddb 100644 --- a/website/docs/provider_versions.html.markdown +++ b/website/docs/provider_versions.html.markdown @@ -8,14 +8,14 @@ description: |- # Google Provider Versions -The Google Provider comes in two versions: +Starting with version `1.19.0`, there are two versions of the Google provider: * terraform-provider-google * terraform-provider-google-beta All GA products and features are available in both versions of the provider. -In version 2.0.0 and beyond of the providers, beta features will only be available in the beta version of the provider. +From version `2.0.0` onwards, beta features are only available in the beta version of the provider (`google-beta`). Beta GCP Features have no deprecation policy and no SLA, but are otherwise considered to be feature-complete with only minor outstanding issues after their Alpha period. Beta is when GCP features are publicly announced, and is when they generally become publicly @@ -33,6 +33,7 @@ provider "google" { project = "my-project-id" region = "us-central1" } + provider "google-beta" { credentials = "${file("account.json")}" project = "my-project-id" @@ -62,7 +63,7 @@ If the `provider` field is omitted, Terraform will choose one of the versions av Resources can safely be converted from one version to the other without needing to rebuild infrastructure. -To go from GA to beta, simply change the `provider` field from `"google"` to `"google-beta"`. +To go from GA to beta, change the `provider` field from `"google"` to `"google-beta"`. To go from beta to GA, do the reverse. If you were previously using beta fields that you no longer wish to use: