Imported from kubedb/provider-aws (AGENTS.md). Install upstream with npx skills add kubedb/provider-aws. Copyright stays with the author.

AGENTS.md - KubeDB Provider AWS

This file provides instructions for AI coding agents working in this Crossplane provider repository.

Project Overview

Crossplane provider for AWS, built using Upjet code-generation tooling against the Terraform AWS provider schema (hashicorp/aws v5.0.1). Exposes XRM-conformant Kubernetes managed resources for AWS services that KubeDB depends on: RDS, DocumentDB, ElastiCache, MemoryDB, DynamoDB, EC2, IAM, Kafka (MSK), Kinesis, KMS, Elasticsearch, SecretsManager, and SNS. Generated CRDs live under the aws.kubedb.com API root group. Replacement of upstream terraform-provider-aws is pinned to github.com/upbound/terraform-provider-aws to expose the xpprovider symbol.

Go module: kubedb.dev/provider-aws (Go 1.22 / GO_REQUIRED_VERSION = 1.25 in Makefile).

Build & Development Commands

# Regenerate CRDs, controllers, and zz_*.go files from Terraform schema
go run cmd/generator/main.go "$PWD"

# Run provider locally out-of-cluster against current kubeconfig
make run

# Build provider and generator binaries
make build

# Build images, push, and install xpkg
make all

# Update build/ git submodule (required on first clone)
make submodules

End-to-End Testing

# Build, load image into kind, deploy provider
make local-deploy

# Run uptest example suite
make uptest UPTEST_EXAMPLE_LIST=examples/rds/cluster.yaml

# Full e2e: local-deploy + uptest
make e2e

Required env for uptest: UPTEST_EXAMPLE_LIST (comma-separated example paths) and optionally UPTEST_CLOUD_CREDENTIALS with DEFAULT=/PEER= AWS credential blocks.

Schema Regeneration Pipeline

The generator runs Terraform to fetch the provider schema, then runs Upjet's pipeline. Inputs:

• TERRAFORM_VERSION = 1.5.5
• TERRAFORM_PROVIDER_SOURCE = hashicorp/aws
• TERRAFORM_PROVIDER_VERSION = 5.0.1

Schema cache: config/schema.json (regenerated by make generate, which depends on $(TERRAFORM_PROVIDER_SCHEMA) and pull-docs).

CRD Diff Checks

# Detect breaking CRD changes vs base branch (CI)
MODIFIED_CRD_LIST="..." GITHUB_BASE_REF=main make crddiff

# Detect Terraform native state schema version changes
GITHUB_BASE_REF=main make schema-version-diff

Project Structure

apis/
  {service}/v1alpha1/      # Generated managed-resource types (zz_*_types.go)
  v1alpha1/                # StoreConfig types (ESS)
  v1beta1/                 # ProviderConfig types
  zz_register.go           # Aggregated AddToScheme registration
  register_crd.go          # CRD scheme additions
cmd/
  provider/main.go         # Provider entrypoint (kingpin flags, ctrl-runtime)
  generator/main.go        # Upjet pipeline driver: go run cmd/generator/main.go "$PWD"
  generator/crd_controller.go.txt  # Template body appended to dynamic controller
  dynamic-controller/      # Generates zz_dynamic_crd_controller.go
config/
  provider.go              # Upjet provider config (root group aws.kubedb.com)
  external_name.go         # External name conventions per resource
  overrides.go             # API group/kind overrides
  schema.json              # Cached Terraform provider schema (embedded)
  provider-metadata.yaml   # Embedded metadata for Upjet
  {service}/config.go      # Per-service Upjet Configure() functions
internal/
  clients/aws.go           # Terraform setup function, AWS credential plumbing
  clients/cache.go         # Provider config cache
  clients/provider_config.go
  controller/{service}/{kind}/    # Generated controllers (one dir per resource)
  controller/zz_setup.go          # Aggregated controller registration
  controller/zz_dynamic_crd_controller.go  # Dynamic CRD reconciler
  features/features.go     # Feature flag definitions
  version/                 # ldflags-injected version
examples/                  # User-facing example manifests (rds, dynamodb, ...)
examples-generated/        # Auto-generated from Terraform docs
package/
  crossplane.yaml          # xpkg metadata
  crds/                    # Generated CustomResourceDefinitions
hack/                      # boilerplate.go.txt, embed.go, prepare.sh
build/                     # Crossplane build submodule (makelib/*.mk)
cluster/test/              # uptest setup scripts

Key Packages / APIs

• cmd/provider - Kingpin-driven entrypoint. Flags include --debug, --sync, --poll, --leader-election, --max-reconcile-rate, --provider-ttl, --terraform-version, --terraform-provider-source, --terraform-provider-version, --terraform-native-provider-path, --enable-external-secret-stores, --enable-management-policies.
• config.GetProvider(ctx, generationProvider bool) - Builds the Upjet *ujconfig.Provider. generationProvider=true uses embedded schema.json; false calls xpprovider.GetProviderSchema. Root group aws.kubedb.com, module path kubedb.dev/provider-aws, resource prefix aws.
• internal/clients.SelectTerraformSetup - Returns the Upjet terraform.SetupFn that injects AWS credentials from ProviderConfig into the Terraform plugin process. Supports IRSA / Web Identity / assume-role / static keys.
• internal/controller.NewCustomResourceReconciler - Wires the dynamic CRD reconciler (zz_dynamic_crd_controller.go) so resources are reconciled when their CRDs are installed.
• internal/features - EnableAlphaExternalSecretStores, EnableBetaManagementPolicies flags.
• apis/v1beta1.ProviderConfig - Cluster-scoped credential source binding.
• apis/v1alpha1.StoreConfig - External Secret Store config (alpha).

Generated Resource Files

Every managed resource follows the Upjet naming convention:

• apis/{service}/v1alpha1/zz_{kind}_types.go - Spec/Status types
• apis/{service}/v1alpha1/zz_generated_terraformed.go - Terraform conversion
• apis/{service}/v1alpha1/zz_generated.{deepcopy,managed,managedlist,resolvers}.go
• internal/controller/{service}/{kind}/zz_controller.go - Reconciler setup

Hand-written customizations go in config/{service}/config.go via the per-service Configure(p *ujconfig.Provider) function, registered in config/provider.go.

Testing

• No unit tests are shipped with most generated code. .golangci.yml skips zz_*.go files.
• E2E coverage uses uptest (v0.5.0): make uptest UPTEST_EXAMPLE_LIST=.... Examples that need pre-deletion hooks follow the uptest delete template.
• make e2e chains local-deploy and uptest.
• CI runs lint (golangci-lint v1.53.3), build, and unit-test targets via .github/workflows/ci.yml. Submodules must be checked out (submodules: true).
• Coverage uploaded via make cobertura (excludes zz_* files).

Dependencies

Critical go.mod replace directives:

golang.org/x/exp => golang.org/x/exp v0.0.0-20230713183714-613f0c0eb8a1
github.com/hashicorp/terraform-provider-aws => github.com/upbound/terraform-provider-aws v0.0.0-20231026091456-f2d38ee240d7

The second replace is mandatory: upstream terraform-provider-aws does not export the xpprovider package consumed by config/provider.go and internal/clients/aws.go.

Code Conventions

• Generated files are prefixed zz_ and excluded from linting and Cobertura coverage. Never edit them by hand; regenerate via go run cmd/generator/main.go "$PWD".
• Per-service customization lives in config/{service}/config.go with a Configure(p *ujconfig.Provider) entry point added to the list in config/provider.go.
• New AWS services require: a folder under config/{service}/, registration in config/provider.go, inclusion via CLIReconciledResourceList() or NoForkResourceList(), and rerunning the generator to produce apis/{service}/v1alpha1/ and internal/controller/{service}/.
• API root group is aws.kubedb.com. Sub-groups derive from Terraform import paths; overrides live in config/overrides.go (groupKindOverride).
• License headers come from hack/boilerplate.go.txt; the dynamic-controller generator and Upjet pipeline both inject it.
• Build submodule (build/) is shared Crossplane makelib; update with make submodules. Do not edit build/makelib/* directly.
• Image registry defaults: ghcr.io/kubedb for Docker images, xpkg.upbound.io/upbound for xpkg.
• Feature gates are toggled via --enable-* CLI flags wired through internal/features and Upjet's feature.Flags.
• Linter (.golangci.yml) deadline 10m; errcheck ignores fmt:.* and io/ioutil:^Read.*; shadow check disabled.