Rancher Terraform

The Rancher Terraform Provider allows administrators to create and manage RKE2 guest clusters using Terraform.

Deployment

Prerequisites

  • The Kubernetes cluster is built on top of Harvester VMs.
  • The Harvester VMs that run as guest Kubernetes nodes are in the same namespace.

Deploy Guest Clusters Using the Rancher Terraform Provider

  1. Create an API key.

    On the Rancher UI, go to Account & API Keys > Create API key > Create.

    Create API Key Access & Secret Keys

  2. Obtain the Harvester cluster ID.

    On the Rancher UI, go to Virtualization Management > Manage > Related Resources > Mgmt Cluster Name.

    Harvester Cluster ID

  3. Obtain the kubeconfig for the Harvester Cloud Provider and the Harvester CSI Driver.

    • UI
    • Shell

    On the Rancher UI, go to Virtualization Management. Locate the target Harvester cluster in the list and then select ⋮ > Download KubeConfig.

    Download Kubeconfig

    1. # Generate harvester cloud provider kubeconfig
    2. RANCHER_SERVER_URL="<RANCHER_SERVER_URL>" # Pure server URL like https://192.168.0.181:6443
    3. RANCHER_ACCESS_KEY="<RANCHER_ACCESS_KEY>"
    4. RANCHER_SECRET_KEY="<RANCHER_SECRET_KEY>"
    5. HARVESTER_CLUSTER_ID="<HARVESTER_CLUSTER_ID>"
    6. CLUSTER_NAME="rke2-demo"
    7. curl -k -X POST ${RANCHER_SERVER_URL}/k8s/clusters/${HARVESTER_CLUSTER_ID}/v1/harvester/kubeconfig \
    8. -H 'Content-Type: application/json' \
    9. -u ${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY} \
    10. -d '{"clusterRoleName": "harvesterhci.io:cloudprovider", "namespace": "default", "serviceAccountName": "'${CLUSTER_NAME}'"}' | xargs | sed 's/\\n/\n/g' > ${CLUSTER_NAME}-kubeconfig

  4. Prepare a provider.tf file with the following content:

    1. terraform {
    2. required_providers {
    3.     rancher2 = {
    4.         source  = "rancher/rancher2"
    5.         version = "4.2.0"
    6.         }
    7.     }
    8. }
    10. # Configure the Rancher2 provider to admin
    11. provider "rancher2" {
    12.     api_url    = "<api_url>" # API Endpoint on Account & API Keys page
    13.     access_key = "<access_key>"
    14.     secret_key = "<secret_key>"
    15.     insecure   = true # Set to true if the Rancher server uses a self-signed certificate
    16. }

  5. Prepare a main.tf file with the following content:

    1. # Get imported harvester cluster info
    2. data "rancher2_cluster_v2" "harv" {
    3.     name = "<harvester_cluster_name_in_rancher>"
    4. }
    6. # Create a new Cloud Credential for an imported Harvester cluster
    7. resource "rancher2_cloud_credential" "harv-cred" {
    8.     name = "harv-cred"
    9.     harvester_credential_config {
    10.         cluster_id = data.rancher2_cluster_v2.harv.cluster_v1_id
    11.         cluster_type = "imported"
    12.         kubeconfig_content = data.rancher2_cluster_v2.harv.kube_config
    13.     }
    14. }
    16. # Create a new rancher2 machine config v2 using harvester node_driver
    17. resource "rancher2_machine_config_v2" "rke2-machine" {
    18.     generate_name = "rke2-machine"
    19.     harvester_config {
    20.         vm_namespace = "default"
    21.         cpu_count = "2"
    22.         memory_size = "4"
    23.         disk_info = <<EOF
    24.         {
    25.             "disks": [{
    26.                 "imageName": "default/<vmimage-name>",
    27.                 "size": 15,
    28.                 "bootOrder": 1
    29.             }]
    30.         }
    31.         EOF
    32.         network_info = <<EOF
    33.         {
    34.             "interfaces": [{
    35.                 "networkName": "default/<network-name>"
    36.             }]
    37.         }
    38.         EOF
    39.         ssh_user = "<ssh_user>"
    40.         user_data = <<EOF
    41.         package_update: true
    42.         packages:
    43.         - qemu-guest-agent
    44.         - iptables
    45.         runcmd:
    46.         - - systemctl
    47.             - enable
    48.             - '--now'
    49.             - qemu-guest-agent.service
    50.         EOF
    51.     }
    52. }
    54. resource "rancher2_cluster_v2" "rke2-demo" {
    55.     name = "rke2-demo"
    56.     kubernetes_version = "v1.28.10+rke2r1"
    57.     rke_config {
    58.         machine_pools {
    59.             name = "pool1"
    60.             cloud_credential_secret_name = rancher2_cloud_credential.harv-cred.id
    61.             control_plane_role = true
    62.             etcd_role = true
    63.             worker_role = true
    64.             quantity = 1
    65.             machine_config {
    66.                 kind = rancher2_machine_config_v2.rke2-machine.kind
    67.                 name = rancher2_machine_config_v2.rke2-machine.name
    68.             }
    69.         }
    71.         machine_selector_config {
    72.             config = yamlencode({
    73.                 cloud-provider-config = file("${path.module}/rke2-demo-kubeconfig")
    74.                 cloud-provider-name = "harvester"
    75.             })
    76.         }
    78.         machine_global_config = <<EOF
    79.         cni: "calico"
    80.         disable-kube-proxy: false
    81.         etcd-expose-metrics: false
    82.         EOF
    84.         upgrade_strategy {
    85.             control_plane_concurrency = "1"
    86.             worker_concurrency = "1"
    87.         }
    89.         etcd {
    90.             snapshot_schedule_cron = "0 */5 * * *"
    91.             snapshot_retention = 5
    92.         }
    94.         chart_values = <<EOF
    95.         harvester-cloud-provider:
    96.         clusterName: rke2-demo
    97.         cloudConfigPath: /var/lib/rancher/rke2/etc/config-files/cloud-provider-config
    98.         EOF
    99.     }
    100. }

  6. Run terraform init.

  7. Run terraform apply.