Today, we are excited to announce our latest official provider: provider-terraform. This provider joins our existing official provider-aws, provider-azure, and provider-gcp in the official program by Upbound which ensures extended support to Upbound customers. This provider is also a new type of official provider as it doesn’t target a specific API but rather enables integration scenarios like reusing custom Terraform modules. With this announcement, we double down on our path of helping enterprises migrate to an internal cloud platform while supporting integration scenarios and securing existing investments.

Crossplane as the Framework

With Upbound Universal Crossplane, we provide an open source framework for building internal cloud platforms. Crossplane makes cloud APIs available as Kubernetes resources and allows contributors to author custom APIs by combining and adapting existing cloud APIs. All of this is powered by the Kubernetes core machinery around continuous reconciliation of the desired to the actual state.

Integration Is Key

The combination of Kubernetes + Crossplane has proven itself as an excellent integration platform. Infrastructure from public clouds can be combined with specialized cloud services and even on-premise services, while orthogonal concerns like policies or observability can be defined across all infrastructure.

With provider-terraform, we are expanding the available integration scenarios. While platform builders see the benefit of Crossplane, they still need to incorporate existing provisioning tools like Terraform. The reasons for this vary: Maybe they don’t have the authority over certain Terraform setups. Or when the platform team itself has invested a lot into custom domain-specific Terraform logic, they want to avoid migrating all at once and rather take a phased approach. With Crossplane and provider-terraform, we enable teams to start the journey with control-plane powered platforms and include Terraform for certain scenarios.

As one of the maintainers of the Provider, Bob Haddleton from Nokia further emphasizes on the benefits, saying, “provider-terraform is the Swiss Army knife for Crossplane - it provides the ability to leverage existing Terraform modules during a transition period, and fills in the gaps for resources that are not yet available in the official providers. It also provides a means of performing calculations and data manipulation that are outside the scope of the core Crossplane framework.”

How Does It Work?

Let’s get started! Provider-terraform is just a Crossplane provider, meaning it makes calls to some backend API, while making sure that the desired state described by the user is regularly reconciled with the actual state. In this case, the backend API is a Terraform workspace, which usually contains one or more custom Terraform modules.

Assuming you have Crossplane installed, you can install the provider-terraform with a simple command:

$ kubectl crossplane install provider xpkg.upbound.io/upbound/provider-terraform:v0.1.0

Afterwards, you need to configure the provider for the respective backend API. See our docs for details.

Let’s use the canonical bucket example with GCP to see how this works. Please note that this is purely for example purposes of a simple, straightforward resource. In most scenarios, we advise users to be using the Bucket resource from the GCP provider directly.

Let's say we have this existing HCL definition to create a bucket with a random suffix:

resource "random_id" "example" {
	byte_length = 4
}

resource "google_storage_bucket" "example" {
	name = "crossplane-example-${terraform.workspace}-${random_id.example.hex}"
	location      = "US"
	force_destroy = true

 public_access_prevention = "enforced"
}

We start by including the definition into the respective Crossplane resource. For this, we use the specific resource: workspace/tf.upbound.io. As with all Crossplane resources, the Workspace resource has a forProvider section where we specify our desired state. Here we define the state in a specific module parameter, where we can for example inline our definition. This would look like the following:

apiVersion: tf.upbound.io/v1beta1
kind: Workspace
metadata:
  name: example-inline
spec:
  forProvider:
    source: Inline
    module: |
      resource "random_id" "example" {
        byte_length = 4
      }

      resource "google_storage_bucket" "example" {
        name = "crossplane-example-${terraform.workspace}-${random_id.example.hex}"
        location      = "US"
        force_destroy = true

        public_access_prevention = "enforced"
      }

      // Outputs are written to the connection secret.
      output "url" {
        value       = google_storage_bucket.example.self_link
      }

Note: We have removed some YAML specifications for brevity. Please see the Quickstart for the full example.

This definition can then be applied to the control-plane cluster with

This definition can then be applied to the control-plane cluster with `kubectl apply -f <filename>`. Afterwards, the Crossplane magic kicks in and will make sure the resource will be created, continually observed, and updated if necessary.  You can check the status and the details with your usual Kubernetes tools like `kubectl describe workspace example-inline`.

For a platform builder, the next step would be including this Workspace resource in a Crossplane composition. This allows them to include other resources from any of the other Crossplane providers and provide an internal custom API to development teams requesting these resources. See the guide about Composite Resources for details. Experienced platform builders use Composite Resource Definitions as facades, behind which they decide to use provider-terraform or migrate to some other provider.

In the example above, we have in-lined the Terraform configuration. Alternatively, you can also specify a remote source like a Git repository from where the Terraform configurations are fetched. See the docs for more configuration options which enable different scenarios. Nuno Guedes from MBCP feels as though the “provider-terraform allows us to enforce the same configuration logic for shared components across different IaC streams while supporting multiple maturity levels in the organization.”

Summary

With the official provider-terraform, we are offering our customers a great way to start migrating to Crossplane while keeping their existing investments in Terraform. “With provider-terraform you can make the control plane out of your existing terraform code and extend it with the native Crossplane power” – Yury, maintainer of provider-terraform, Upbound.

We offer this provider completely open source for anyone to use and offer our customers additional support and services as part of our existing and upcoming product offerings. To get started, head over to the provider-terraform in Upbound’s marketplace.

We’d love to hear your stories on how you are using this provider. Please reach out in the Crossplane slack in the #providers channel or ping me @luebken.

If you are interested in learning more about Crossplane & how to incorporate it into your organization further, we have a guide that walks you through it. Check it out!