Terraform can manage Rancher resources, but it doesn’t actually talk to Rancher itself; it talks to the Rancher API.
Let’s see what that looks like. Imagine you have a Rancher cluster, and you want to create a Kubernetes namespace within it.
provider "rancher" {
url = "https://your-rancher-server.com"
token = "your-rancher-api-token"
}
resource "rancher_namespace" "example" {
cluster_id = "c-xxxxx:p-xxxxx"
name = "my-awesome-namespace"
project_id = "c-xxxxx:p-xxxxx"
}
Here, url is the address of your Rancher instance, and token is an API key you generate within Rancher. The rancher_namespace resource then uses these credentials to reach out to the Rancher API and create that namespace in the specified cluster and project.
The core problem Terraform solves here is declarative infrastructure management for Rancher. Instead of clicking around in the UI or writing imperative scripts, you define your desired state in .tf files. Terraform then figures out how to get Rancher from its current state to your desired state. This applies to almost everything you can do in Rancher: clusters, projects, namespaces, node templates, user roles, and even downstream Kubernetes resources if you use the Kubernetes provider alongside the Rancher provider.
Internally, the Terraform Rancher provider is a client for the Rancher API. When you run terraform apply, it reads your .tf files, queries the Rancher API to understand the current state of your infrastructure, compares it to your desired state, and then makes API calls to create, update, or delete resources to match your configuration. It handles the complexities of resource dependencies and state management, so you don’t have to.
The cluster_id format c-xxxxx:p-xxxxx is a bit of a red herring. While it looks like it, it’s not actually a direct reference to a Kubernetes cluster ID and a project ID. The cluster_id parameter in the rancher_namespace resource is actually the Rancher API’s internal identifier for the cluster. This ID is often presented in the Rancher UI as part of the URL when you navigate to a specific cluster, or it can be retrieved using the Rancher API itself or the rancher2_cluster data source in Terraform. The p-xxxxx part is the project ID, which is also a Rancher-specific identifier.
What most people don’t realize is that the Rancher provider is essentially a wrapper around the Rancher API’s REST endpoints. Each resource type in Terraform (like rancher_namespace, rancher_project, rancher_cluster) maps directly to specific API calls. For example, creating a namespace involves a POST request to /v3/namespaces on your Rancher API endpoint, with the namespace definition in the request body. Terraform handles the authentication, serialization, and deserialization of data for these API calls, abstracting away the raw HTTP interactions.
Understanding how Rancher assigns and manages these internal IDs is key to effectively using the provider. You’ll often find yourself using data sources to look up these IDs dynamically rather than hardcoding them.
The next hurdle is managing the lifecycle of Kubernetes workloads themselves, which usually involves switching to the Kubernetes provider.