GitHub - crossplane/upjet: A code generation framework and runtime for Crossplane providers (original) (raw)
Upjet - Generate Crossplane Providers from any Terraform Provider
Upjet is a code generation framework and Kubernetes controller runtime that transforms Terraform providers into Crossplane providers. It generates Kubernetes CRDs, reconciliation controllers, and example manifests while providing runtime libraries for API conversions, Terraform state management, and resource lifecycle operations. It powers the official AWS, Azure, and GCP providers along with 50+ community providers.
Table of Contents
- Key Features
- When to Use Upjet
- Architecture
- Providers Built with Upjet
- Documentation
- Contributing
- Community
- Prior Art
- License
Key Features
- Multiple Terraform Execution Modes
- Terraform CLI: Traditional fork-based Terraform CLI and Terraform provider process spawning
- Terraform Plugin SDK v2: Direct Go library integration (no-CLI invocation)
- Terraform Plugin Framework: Protocol-based communication via protov6 (no-CLI invocation)
- Automatic Resource Generation
- Kubernetes CRDs highly conformant to the Crossplane Resource Model (XRM) from Terraform schemas
- Reconciliation controllers with full CRUD lifecycle
- Example manifests, API documentation, (partial) API validation rules, etc.
- Cross-Resource References
- Kubernetes-native reference resolution between resources
- Automatic selector generation for resource lookups
- Management Policies (Crossplane v1.11+)
- Fine-grained control over resource lifecycle operations
- Observe-only mode for importing existing infrastructure
- Advanced Capabilities
- External name mapping for resource identification
- Late initialization from provider responses
- Sync & async operations for long-running resources
- Sensitive field handling with connection secrets
When to Use Upjet
Upjet is ideal when:
- A Terraform provider already exists for your target platform
- You want to leverage Terraform's battle-tested resource logic
- You need broad coverage of infrastructure resources quickly
- Your team is familiar with Terraform provider semantics
Consider a native Crossplane provider when:
- No Terraform provider exists for your platform
- You need deeply customized reconciliation logic
- You require precise control over the Kubernetes API surface
- Performance requirements exceed what Terraform execution allows
Architecture
Upjet bridges the gap between Terraform's vast provider ecosystem and Kubernetes-native infrastructure management. At build time, Upjet reads a Terraform provider's schema and generates everything needed for a Crossplane provider: Go types, Custom Resource Definitions, and reconciliation controllers. At runtime, these controllers use Terraform's resource logic to manage infrastructure, while exposing a pure Kubernetes API to users.
- Code Generation Pipeline - Transforms Terraform schemas into Go types, CRDs, and controllers
- Generic CR Reconcilers - Runtimes that handle reconciliation for all generated resources
- Documentation Scraper - Extracts and generates API documentation, example manifests (used for e2e testing and documentation), cross-resource references, etc. from Terraform docs
- Migration Framework - Supports migrating resources between different providers of the same external API, like migrating from the community AWS provider (crossplane-contrib/provider-aws) to the official provider (upbound/provider-aws)
- API Conversion Framework - Handles lifecycle management and breaking changes between API versions of the same CRD
- Resource Configuration Framework - Implements various configuration aspects (external name, sync/async behavior, API naming, API versions, cross-resource references, etc.) for Upjet resources
Providers Built with Upjet
Major Cloud Providers
Additional Providers
Browse the Upbound Marketplace for a full list of available providers.
Documentation
| Guide | Description |
|---|---|
| Generating a Provider | Create a new Crossplane provider from scratch |
| Configuring a Resource | External names, references, and resource customization |
| Adding New Resources | Add resources to an existing provider |
| Testing with Uptest | End-to-end testing framework |
| Monitoring | Prometheus metrics for the Upjet runtime |
| Upgrading to v2 | Migration guide from Upjet v1 to v2 |
| Managing CRD Versions | Handle Terraform schema changes across versions |
| Controller Template Variables | Variables available to the managed resource controller setup template |
| Main Template Variables | Variables available to the provider family main program template |
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Community
- Slack: #upjet onCrossplane Slack
- Twitter: @crossplane_io
- Issues: GitHub Issues
Prior Art
Upjet originates from the Terrajet project. See the originaldesign document.
License
Upjet is under the Apache 2.0 license with notice.