/provider-configuration

name: provider-configuration
description: >-
  Implement Terraform provider configuration and authentication with the
  Plugin Framework: provider schema for credentials (Optional + Sensitive
  attributes), environment variable fallbacks, credential provider chains
  (static config, then environment variables, shared credentials file, and
  platform identity), unknown-value guards in Configure(), secret redaction,
  configure-time credential validation, and diagnostics that name every
  source tried. Use when implementing or reviewing a provider's Configure
  method or provider schema, adding authentication options (API keys,
  tokens, profiles, credentials files, assume-role), deciding how a provider
  should resolve credentials, debugging "no valid credential sources" or
  missing-credentials errors, or unit testing credential resolution.
license: MPL-2.0
metadata:
  lifecycle-status: active
  copyright: Copyright IBM Corp. 2026
  version: "0.0.1"

Terraform Provider Configuration and Authentication

How a provider accepts connection settings and resolves credentials. Poor authentication UX is the first thing every user of a provider hits; a well-designed credential provider chain is what separates a production-grade provider from a demo. The examples use a fictional `examplecloud` provider and the [Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework/providers).

**References** (load when needed):

• `references/credential-chain.md` — complete, compilable credential chain

implementation (providers, chain, file profiles, Configure wiring, tests)

• `references/case-studies.md` — how the AWS provider (`aws-sdk-go-base`)

and smaller providers structure real credential chains

---

Provider Schema for Authentication

Every authentication attribute must be `Optional`, never `Required` — a `Required` attribute forces users to put credentials in configuration and makes environment-variable and credentials-file resolution impossible. Mark secrets `Sensitive` so Terraform redacts them in plan output, and state the environment-variable fallback in each description so `tfplugindocs` publishes the resolution rules.

func (p *examplecloudProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "endpoint": schema.StringAttribute{
                Optional:            true,
                MarkdownDescription: "API endpoint. May also be set via the `EXAMPLECLOUD_ENDPOINT` environment variable.",
            },
            "api_key": schema.StringAttribute{
                Optional:            true,
                MarkdownDescription: "API key. May also be set via the `EXAMPLECLOUD_API_KEY` environment variable, or in a shared credentials file.",
            },
            "api_secret": schema.StringAttribute{
                Optional:            true,
                Sensitive:           true,
                MarkdownDescription: "API secret. May also be set via the `EXAMPLECLOUD_API_SECRET` environment variable, or in a shared credentials file.",
            },
            "profile": schema.StringAttribute{
                Optional:            true,
                MarkdownDescription: "Named profile in the shared credentials file. May also be set via the `EXAMPLECLOUD_PROFILE` environment variable. Defaults to `default`.",
            },
            "skip_credentials_validation": schema.BoolAttribute{
                Optional:            true,
                MarkdownDescription: "Skip the identity check normally performed during provider configuration.",
            },
        },
    }
}

Never add a `Default` to a credential attribute, and never hardcode a credential anywhere in the provider. Defaults belong in the resolution logic (where environment variables and files can override them), not in the schema.

The Credential Provider Chain

Resolve credentials by consulting an ordered list of sources and taking the first one that produces a **complete** set. This is the pattern the AWS provider uses via [`aws-sdk-go-base`](https://github.com/hashicorp/aws-sdk-go-base), and it generalizes to any provider. The canonical precedence, highest first:

1. **Static configuration** — values set directly in the `provider` block. Explicit always wins. 2. **Environment variables** — `EXAMPLECLOUD_API_KEY`, etc. The CI-friendly path. 3. **Shared credentials file** — named profiles in `~/.examplecloud/credentials`, for humans with multiple accounts. 4. **Platform identity** — instance metadata, workload identity, or OIDC token exchange, where the platform offers it. Credentials nobody has to store.

Two rules make the chain predictable:

• **Resolve secrets as a set, not field-by-field.** If the environment

supplies an API key but no secret, that source offers nothing — fall through to the next source for *both* values. Mixing an env-var key with a file-profile secret produces authentication failures that are nearly impossible for users to debug.

• **Resolve non-secret connection settings field-by-field.** `endpoint`,

`profile`, or `insecure` can each independently follow config > env > file > default, because a mismatch there is visible and harmless.

The core abstraction is a single-method interface with a sentinel error that distinguishes "this source has nothing to offer" (fall through) from "this source is misconfigured" (surface it):

// ErrNoCredentials signals a source had nothing to offer. The chain falls
// through to the next source. Any other error means the source was
// configured but unusable (e.g. malformed credentials file) and is
// preserved so the final diagnostics can surface it.
var ErrNoCredentials = errors.New("no credentials found")

type Credentials struct {
    APIKey    string
    APISecret string
    Source    string // which provider supplied them, for logging
}