Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
DevOps & cloud

provider-configuration

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.

hashicorp · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add hashicorp/agent-skills --skill provider-configuration

About this skill


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.

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, 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
}
Read the complete source ↗