From 912ce37b20ce263765bc215c9912aa670bbdcb3b Mon Sep 17 00:00:00 2001
From: Anton Tolchanov <anton@tailscale.com>
Date: Thu, 17 Aug 2023 20:42:31 +0100
Subject: [PATCH] README.md: update defaults and examples

- Use a default version for the `tailnet` configuration parameter and
  remove it from the example;
- Suggest a weaker version constraint that uses the latest patch
  release;
- Document using OAuth client credentials rather than personal API keys;
- Make it more clear that setting `base_url` is only necessary if you
  are using a non-default coordination server.

Fixes #207
Fixes #243
---
 README.md             | 30 ++++++++++++++++++++----------
 tailscale/provider.go |  4 ++--
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 65fca2a1..ae42c94c 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# terraform-provider-tailscale 
+# terraform-provider-tailscale
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/tailscale/terraform-provider-tailscale.svg)](https://pkg.go.dev/github.com/tailscale/terraform-provider-tailscale)
 [![Go Report Card](https://goreportcard.com/badge/github.com/tailscale/terraform-provider-tailscale)](https://goreportcard.com/report/github.com/tailscale/terraform-provider-tailscale)
@@ -21,26 +21,36 @@ terraform {
   required_providers {
     tailscale = {
       source = "tailscale/tailscale"
-      version = "0.13.6"
+      version = "~> 0.13" // Latest 0.13.x
     }
   }
 }
 
 provider "tailscale" {
-  api_key = "my_api_key"
-  tailnet = "example.com"
+  api_key = "tskey-api-..."
 }
 ```
 
-In the `provider` block, replace `api_key` and `tailnet` with your own API key and tailnet organization name. Alternatively, use the
-`TAILSCALE_API_KEY` and `TAILSCALE_TAILNET` environment variables.
+In the `provider` block, set your API key in the `api_key` field. Alternatively, use the `TAILSCALE_API_KEY` environment variable.
 
-The default api endpoint is `https://api.tailscale.com`. If your coordination/control server api is at another endpoint, you can pass in `base_url` in the provider block.
+### Using OAuth client
+
+Instead of using a personal API key, you can configure the provider to use an [OAuth client](https://tailscale.com/kb/1215/oauth-clients/), e.g.:
+
+```terraform
+provider "tailscale" {
+  oauth_client_id = "..."
+  oauth_client_secret = "tskey-client-..."
+}
+```
+
+### API endpoint
+
+The default api endpoint is `https://api.tailscale.com`. If your coordination/control server API is at another endpoint, you can pass in `base_url` in the provider block.
 
 ```terraform
 provider "tailscale" {
-  api_key = "my_api_key"
-  tailnet = "example.com"
+  api_key = "tskey-api-..."
   base_url = "https://api.us.tailscale.com"
 }
 ```
@@ -54,5 +64,5 @@ terraform state replace-provider registry.terraform.io/davidsbond/tailscale regi
 ## Contributing
 
 Please review the [contributing guidelines](./CONTRIBUTING.md) and [code of conduct](.github/CODE_OF_CONDUCT.md) before
-contributing to this codebase. Please create a [new issue](https://github.com/tailscale/terraform-provider-tailscale/issues/new/choose) 
+contributing to this codebase. Please create a [new issue](https://github.com/tailscale/terraform-provider-tailscale/issues/new/choose)
 for bugs and feature requests and fill in as much detail as you can.
diff --git a/tailscale/provider.go b/tailscale/provider.go
index e46d0c66..42f7845f 100644
--- a/tailscale/provider.go
+++ b/tailscale/provider.go
@@ -54,9 +54,9 @@ func Provider(options ...ProviderOption) *schema.Provider {
 			},
 			"tailnet": {
 				Type:        schema.TypeString,
-				DefaultFunc: schema.EnvDefaultFunc("TAILSCALE_TAILNET", ""),
+				DefaultFunc: schema.EnvDefaultFunc("TAILSCALE_TAILNET", "-"),
 				Optional:    true,
-				Description: "The organization name of the Tailnet in which to perform actions. Can be set via the TAILSCALE_TAILNET environment variable.",
+				Description: "The organization name of the Tailnet in which to perform actions. Can be set via the TAILSCALE_TAILNET environment variable. Default is the tailnet that owns API credentials passed to the provider.",
 			},
 			"base_url": {
 				Type:        schema.TypeString,