docs: clarify provider auth configuration (#8)

* docs: clarify provider auth configuration

Signed-off-by: Avi Miller <me@dje.li>

Author: Djelibeybi

README.md

@@ -14,24 +14,37 @@ This package implements:
 
 ## Authentication
 
-The provider currently keeps OCI auth intentionally simple:
+OCI SDKs support several authentication methods. This provider supports the two
+primary methods: API keys, for authentication outside OCI, and
+`instance_principal`, for authentication from instances within OCI.
 
-- explicit API key fields on `oraclecloud.Provider`
-- OCI config file credentials
-- Oracle CLI environment variables
+All OCI SDKs support some or all of Oracle's standard environment variables for
+authentication configuration, so this provider does too.
+
+The recommended and most prominently documented configuration style is the
+standard OCI config file, usually `~/.oci/config`, because it matches Oracle's
+preferred user workflow and works cleanly with existing OCI tooling.
+
+See the OCI Developer Guide for more on the [Authentication Methods](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm) and [Environment Variables](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clienvironmentvariables.htm).
 
 Supported `Auth` values:
 
 - `""` or `auto`
 - `api_key`
 - `config_file`
 - `environment`
+- `instance_principal`
+
+The `api_key`, `config_file`, and `environment` values are all API-key authentication;
+they only differ in where the credentials come from.
+
+`resource_principal` and token-based authentication are not currently supported.
+
+If you set `Auth` to `auto` or `config_file` with a valid `~/.oci/config` file available, or set `Auth` to `instance_principal` on an OCI instance with the appropriate policies applied, no further configuration is required to manage public DNS zones. However, both of these methods require `ViewID` to be configured to manage private zones by name.
 
-`instance_principal` is also wired through, but the package is primarily aimed at API-key based usage for now.
+For `environment`, or when populating the provider fields directly, the minimum required values are `TenancyOCID`, `UserOCID`, `Fingerprint`, `Region`, and either `PrivateKeyPath` or inline `PrivateKey`. `PrivateKeyPassphrase` is only needed when the private key is passphrase-protected.
 
-If you use `Auth: "config_file"` with `ConfigFile: "~/.oci/config"`, you do not also need to provide
-`TenancyOCID`, `UserOCID`, `Fingerprint`, `Region`, or `PrivateKey*` fields. `ConfigProfile` is optional
-and defaults to `DEFAULT` (or `OCI_CLI_PROFILE` if set).
+`CompartmentID` is required to List Zones.
 
 ## Provider Fields
 

provider.go

@@ -40,21 +40,35 @@ const (
 //
 // The provider is safe for concurrent use.
 type Provider struct {
+	// Auth selects how the provider obtains OCI credentials: auto, api_key,
+	// config_file, environment, or instance_principal.
 	Auth string `json:"auth,omitempty"`
 
+	// ConfigFile is the path to the OCI config file, usually ~/.oci/config.
 	ConfigFile    string `json:"config_file,omitempty"`
+	// ConfigProfile is the profile name within ConfigFile to use.
 	ConfigProfile string `json:"config_profile,omitempty"`
 
+	// PrivateKey is the PEM-encoded API signing key content.
 	PrivateKey           string `json:"private_key,omitempty"`
+	// PrivateKeyPath is the path to the PEM-encoded API signing key file.
 	PrivateKeyPath       string `json:"private_key_path,omitempty"`
+	// PrivateKeyPassphrase is the passphrase for the API signing key, if any.
 	PrivateKeyPassphrase string `json:"private_key_passphrase,omitempty"`
+	// TenancyOCID is the OCID of the tenancy that owns the credentials.
 	TenancyOCID          string `json:"tenancy_ocid,omitempty"`
+	// UserOCID is the OCID of the OCI user for API key authentication.
 	UserOCID             string `json:"user_ocid,omitempty"`
+	// Fingerprint is the fingerprint of the registered OCI API signing key.
 	Fingerprint          string `json:"fingerprint,omitempty"`
+	// Region is the OCI region used for DNS API requests.
 	Region               string `json:"region,omitempty"`
 
+	// Scope selects the DNS zone scope: GLOBAL or PRIVATE.
 	Scope         string `json:"scope,omitempty"`
+	// ViewID identifies the private DNS view when operating on private zones by name.
 	ViewID        string `json:"view_id,omitempty"`
+	// CompartmentID identifies the compartment to search when listing zones.
 	CompartmentID string `json:"compartment_id,omitempty"`
 
 	mu        sync.Mutex `json:"-"`