Rancher2 Terraform Provider for Infrastructure as Code

Infrastructure as code is an important methodology for ensuring that distributed systems are treated as cattle and not pets. Kubernetes and Rancher clusters are no different. You should be able to provision Rancher clusters, Kubernetes clusters, and all apps with automation. The official Rancher2 Terraform provider supports Rancher v2 resources, allowing you to automate everything from cluster provisioning to RBAC configuration.

Terraform is written in files with the extension .tf. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure.

Provider Configuration and Prerequisites

Before automating Rancher with Terraform, the required foundation must be in place.

Prerequisites required for a Rancher2 Terraform workflow:

• Terraform 1.5+ installed
• Rancher instance with API access
• Rancher API token created in User Settings > API & Keys
• Compatible Rancher and Rancher2 provider versions
• Basic Terraform knowledge

The Rancher API key has the same permissions and access level as the user it is associated with. The provider configuration establishes the connection to the Rancher server and defines state storage for team collaboration.

Example provider block from the reference configuration:

```hcl
terraform {
required_providers {
rancher2 = {
source = "rancher/rancher2"
}
}
backend "s3" {
bucket = "terraform-state-rancher"
key = "rancher/terraform.tfstate"
region = "us-east-1"
}
}

provider "rancher2" {
apiurl = var.rancherurl
tokenkey = var.ranchertoken
insecure = false
}
```

Variables are defined to keep sensitive values out of code:

```hcl
variable "rancher_url" {
description = "Rancher server URL"
type = string
}

variable "rancher_token" {
description = "Rancher API token"
type = string
sensitive = true
}

variable "environment" {
description = "Deployment environment"
type = string
default = "production"
}

variable "devops_password" {
description = "Password for the example DevOps user"
type = string
sensitive = true
}
```

Provider configuration options:

Set insecure = true only if Rancher uses a self-signed certificate. Values can be supplied via TFVARrancherurl, TFVARranchertoken, and TFVARdevops_password environment variables.

Terraform Workflow for Rancher2

To create a Rancher-provisioned cluster with Terraform, define the provider as Rancher 2 and set up the Rancher 2 provider with a Rancher API key. Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider.

When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary.

The standard Terraform lifecycle with Rancher2 is:

bash terraform init terraform plan \ -var="rancher_url=https://rancher.example.com" \ -var="rancher_token=token-xxxxx:yyyyyyyy" \ -var="devops_password=ChangeMe1234" terraform apply \ -var="rancher_url=https://rancher.example.com" \ -var="rancher_token=token-xxxxx:yyyyyyyy" \ -var="devops_password=ChangeMe1234"

Using environment variables instead of CLI flags:

bash export TF_VAR_rancher_url="https://rancher.example.com" export TF_VAR_rancher_token="token-xxxxx:yyyyyyyy" export TF_VAR_devops_password="ChangeMe1234" terraform apply

Cleanup is performed with:

bash terraform destroy

Terraform allows you to:
- Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates
- Codify infrastructure across many platforms, including Rancher and major cloud providers
- Commit infrastructure-as-code to version control
- Easily repeat configuration and setup of infrastructure
- Incorporate infrastructure changes into standard development practices
- Prevent configuration drift, in which some servers become configured differently than others

The official Rancher2 Terraform provider supports Rancher v2 resources, allowing you to automate everything from cluster provisioning to RBAC configuration.

Infrastructure as Code with RKE Templates and Node Templates

In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes. Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.

If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.

Node templates are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same.

Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control.

This section focuses on how to use Terraform with the Rancher 2 Terraform provider, which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster.

Terraform allows you to codify infrastructure across many platforms, including Rancher and major cloud providers. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure.

Application Provisioning Examples

The Rancher2 provider supports application deployment via rancher2appv2 resources. The following example provisions Rancher monitoring components with explicit dependencies.

```hcl
resource "rancher2appv2" "ranchermonitoringcrd" {
clusterid = rancher2clusterv2.productioncluster.clusterv1id
namespace = "cattle-monitoring-system"
name = "rancher-monitoring-crd"
reponame = "rancher-charts"
chartname = "rancher-monitoring-crd"
}

resource "rancher2appv2" "ranchermonitoring" {
clusterid = rancher2clusterv2.productioncluster.clusterv1id
namespace = "cattle-monitoring-system"
name = "rancher-monitoring"
reponame = "rancher-charts"
chartname = "rancher-monitoring"
values = yamlencode({
prometheus = {
prometheusSpec = {
retention = "30d"
storageSpec = {
volumeClaimTemplate = {
spec = {
storageClassName = "standard"
resources = {
requests = { storage = "50Gi" }
}
}
}
}
}
}
})
dependson = [rancher2appv2.ranchermonitoringcrd]
}
```

Resource attributes for app deployment:

This pattern demonstrates how infrastructure as code can automate the creation of infrastructure and other system components with declarative configuration.

Building and Developing the Provider

The Rancher2 provider is maintained in the terraform-providers repository. Development and custom builds require Go and the provider source.

Clone repository to: $GOPATH/src/github.com/terraform-providers/terraform-provider-rancher2

bash $ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers $ git clone [email protected]:terraform-providers/terraform-provider-rancher2

Enter the provider directory and build the provider:

bash $ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-rancher2 $ make build

If you're building the provider, follow the instructions to install it as a plugin. After placing it into your plugins directory, run terraform init to initialize it. Documentation about the provider specific configuration options can be found on the provider's website.

For development work, Go version 1.25+ is required. A Nix flake is also available in the repo which is used to generate an environment for build and test.

To compile the provider, run make build. This will build the provider and put the provider binary in a bin directory where the repo was cloned.

bash $ make build ... $ $GOPATH/bin/terraform-provider-rancher2 ...

There are a few full implementation examples in the "examples" directory, these are run by the CI using the "runtests.sh" script. The runtests script will run the examples to test. WARNING! These are real implementations, you will need AWS credentials in your environment and there will be a cost associated.

The original Terraform Provider for Rancher 1.x was incredibly popular for automating state in Rancher 1.x. So not long after we released 2.x, we started work on a Terraform provider to go with it. Hashicorp published the Rancher2 provider and it is now generally available. The repository used during initial development will be archived and all future development will occur in the terraform-providers repository.

Conclusion

Terraform with the Rancher2 provider enables infrastructure-as-code for Rancher v2 resources, allowing automation of cluster provisioning, RBAC configuration, and application deployment. The provider integrates Rancher API authentication with Terraform's declarative workflow, enabling state storage in S3, variable management for sensitive credentials, and repeatable cluster definitions.

Combining the Rancher2 provider with RKE templates and node templates provides a path to standardize hardware while preserving end-user flexibility in infrastructure provider selection. The ability to codify servers, databases, load balancers, monitoring, firewall settings, and SSL certificates through Rancher and major cloud providers ensures configuration drift prevention and version-controlled infrastructure evolution.

The provider's lifecycle of init, plan, apply, and destroy supports team collaboration through environment variables and backend state management. Application resources such as rancher2appv2 allow Helm chart deployment with explicit dependencies and encoded values, demonstrating production-ready automation of monitoring and other system components.

For operators who need to build or modify the provider, the open source repository supports make build workflows with Go 1.25+ and Nix flakes, and includes real implementation examples tested via CI. The provider remains a core tool for treating Kubernetes and Rancher clusters as cattle through code.

Sources

1. OneUptime Blog
2. SUSE Rancher Blog
3. Rancher Manager Docs
4. GitHub Terraform Provider Rancher2