feat: add support for major openshift version upgrade

README.md

@@ -253,6 +253,7 @@ Optionally, you need the following permissions to attach Access Management tags
 | <a name="module_cbr_rule"></a> [cbr\_rule](#module\_cbr\_rule) | terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module | 1.32.6 |
 | <a name="module_cos_instance"></a> [cos\_instance](#module\_cos\_instance) | terraform-ibm-modules/cos/ibm | 8.21.25 |
 | <a name="module_existing_secrets_manager_instance_parser"></a> [existing\_secrets\_manager\_instance\_parser](#module\_existing\_secrets\_manager\_instance\_parser) | terraform-ibm-modules/common-utilities/ibm//modules/crn-parser | 1.2.0 |
+| <a name="module_get_ocp_version"></a> [get\_ocp\_version](#module\_get\_ocp\_version) | ./modules/get-ocp-version | n/a |
 
 ### Resources
 
@@ -293,6 +294,7 @@ Optionally, you need the following permissions to attach Access Management tags
 | <a name="input_additional_vpe_security_group_ids"></a> [additional\_vpe\_security\_group\_ids](#input\_additional\_vpe\_security\_group\_ids) | Additional security groups to add to all existing load balancers. This comes in addition to the IBM maintained security group. | <pre>object({<br/>    master   = optional(list(string), [])<br/>    registry = optional(list(string), [])<br/>    api      = optional(list(string), [])<br/>  })</pre> | `{}` | no |
 | <a name="input_addons"></a> [addons](#input\_addons) | Map of OCP cluster add-on versions to install (NOTE: The 'vpc-block-csi-driver' add-on is installed by default for VPC clusters and 'ibm-storage-operator' is installed by default in OCP 4.15 and later, however you can explicitly specify it here if you wish to choose a later version than the default one). For full list of all supported add-ons and versions, see https://cloud.ibm.com/docs/containers?topic=containers-supported-cluster-addon-versions | <pre>object({<br/>    debug-tool = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    image-key-synchronizer = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    openshift-data-foundation = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    vpc-file-csi-driver = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    static-route = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    cluster-autoscaler = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    vpc-block-csi-driver = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    ibm-storage-operator = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>    openshift-ai = optional(object({<br/>      version         = optional(string)<br/>      parameters_json = optional(string)<br/>    }))<br/>  })</pre> | `{}` | no |
 | <a name="input_allow_default_worker_pool_replacement"></a> [allow\_default\_worker\_pool\_replacement](#input\_allow\_default\_worker\_pool\_replacement) | (Advanced users) Set to true to allow the module to recreate a default worker pool. If you wish to make any change to the default worker pool which requires the re-creation of the default pool follow these [steps](https://github.com/terraform-ibm-modules/terraform-ibm-base-ocp-vpc?tab=readme-ov-file#important-considerations-for-terraform-and-default-worker-pool). | `bool` | `false` | no |
+| <a name="input_allow_kube_version_upgrade"></a> [allow\_kube\_version\_upgrade](#input\_allow\_kube\_version\_upgrade) | Set to true to allow the module to upgrade the kube version of the cluster. If you wish to make any change to the kube version, set this variable to true. | `bool` | `false` | no |
 | <a name="input_attach_ibm_managed_security_group"></a> [attach\_ibm\_managed\_security\_group](#input\_attach\_ibm\_managed\_security\_group) | Specify whether to attach the IBM-defined default security group (whose name is kube-<clusterid>) to all worker nodes. Only applicable if `custom_security_group_ids` is set. | `bool` | `true` | no |
 | <a name="input_cbr_rules"></a> [cbr\_rules](#input\_cbr\_rules) | The list of context-based restriction rules to create. | <pre>list(object({<br/>    description = string<br/>    account_id  = string<br/>    rule_contexts = list(object({<br/>      attributes = optional(list(object({<br/>        name  = string<br/>        value = string<br/>    }))) }))<br/>    enforcement_mode = string<br/>    tags = optional(list(object({<br/>      name  = string<br/>      value = string<br/>    })), [])<br/>    operations = optional(list(object({<br/>      api_types = list(object({<br/>        api_type_id = string<br/>      }))<br/>    })))<br/>  }))</pre> | `[]` | no |
 | <a name="input_cluster_config_endpoint_type"></a> [cluster\_config\_endpoint\_type](#input\_cluster\_config\_endpoint\_type) | Specify which type of endpoint to use for cluster config access: 'default', 'private', 'vpe', 'link'. A 'default' value uses the default endpoint of the cluster. | `string` | `"default"` | no |
@@ -308,6 +310,7 @@ Optionally, you need the following permissions to attach Access Management tags
 | <a name="input_existing_cos_id"></a> [existing\_cos\_id](#input\_existing\_cos\_id) | The COS id of an already existing COS instance to use for OpenShift internal registry storage. Only required if 'enable\_registry\_storage' and 'use\_existing\_cos' are true. | `string` | `null` | no |
 | <a name="input_existing_secrets_manager_instance_crn"></a> [existing\_secrets\_manager\_instance\_crn](#input\_existing\_secrets\_manager\_instance\_crn) | CRN of the Secrets Manager instance where Ingress certificate secrets are stored. If 'enable\_secrets\_manager\_integration' is set to true then this value is required. | `string` | `null` | no |
 | <a name="input_force_delete_storage"></a> [force\_delete\_storage](#input\_force\_delete\_storage) | Flag indicating whether or not to delete attached storage when destroying the cluster - Default: false | `bool` | `false` | no |
+| <a name="input_ibmcloud_api_key"></a> [ibmcloud\_api\_key](#input\_ibmcloud\_api\_key) | APIkey that's associated with the account to use, set via environment variable TF\_VAR\_ibmcloud\_api\_key | `string` | `null` | no |
 | <a name="input_ignore_worker_pool_size_changes"></a> [ignore\_worker\_pool\_size\_changes](#input\_ignore\_worker\_pool\_size\_changes) | Enable if using worker autoscaling. Stops Terraform managing worker count | `bool` | `false` | no |
 | <a name="input_kms_config"></a> [kms\_config](#input\_kms\_config) | Use to attach a KMS instance to the cluster. If account\_id is not provided, defaults to the account in use. | <pre>object({<br/>    crk_id           = string<br/>    instance_id      = string<br/>    private_endpoint = optional(bool, true) # defaults to true<br/>    account_id       = optional(string)     # To attach KMS instance from another account<br/>    wait_for_apply   = optional(bool, true) # defaults to true so terraform will wait until the KMS is applied to the master, ready and deployed<br/>  })</pre> | `null` | no |
 | <a name="input_manage_all_addons"></a> [manage\_all\_addons](#input\_manage\_all\_addons) | Instructs Terraform to manage all cluster addons, even if addons were installed outside of the module. If set to 'true' this module destroys any addons that were installed by other sources. | `bool` | `false` | no |

ibm_catalog.json

@@ -86,7 +86,7 @@
                 "crn:v1:bluemix:public:iam::::role:Viewer"
               ],
               "service_name": "Resource group only",
-              "notes":"Viewer access is required in the resource group you want to provision in."
+              "notes": "Viewer access is required in the resource group you want to provision in."
             },
             {
               "role_crns": [
@@ -1084,19 +1084,19 @@
               "notes": "Required for creating Virtual Private Cloud (VPC)."
             },
             {
-                "service_name": "cloud-object-storage",
-                "role_crns": [
-                    "crn:v1:bluemix:public:iam::::serviceRole:Manager",
-                    "crn:v1:bluemix:public:iam::::role:Editor"
-                ],
-                "notes": "Required for creating the OpenShift cluster's internal registry storage bucket."
+              "service_name": "cloud-object-storage",
+              "role_crns": [
+                "crn:v1:bluemix:public:iam::::serviceRole:Manager",
+                "crn:v1:bluemix:public:iam::::role:Editor"
+              ],
+              "notes": "Required for creating the OpenShift cluster's internal registry storage bucket."
             },
             {
               "role_crns": [
                 "crn:v1:bluemix:public:iam::::role:Viewer"
               ],
               "service_name": "Resource group only",
-              "notes":"Viewer access is required in the resource group you want to provision in."
+              "notes": "Viewer access is required in the resource group you want to provision in."
             }
           ],
           "architecture": {
@@ -1246,7 +1246,7 @@
             },
             {
               "key": "access_tags",
-              "hidden":true,
+              "hidden": true,
               "custom_config": {
                 "type": "array",
                 "grouping": "deployment",
@@ -1262,7 +1262,8 @@
             {
               "key": "disable_outbound_traffic_protection"
             }
-          ]
+          ],
+          "terraform_version": "1.10.5"
         }
       ]
     }

main.tf

@@ -121,6 +121,16 @@ resource "ibm_resource_tag" "cos_access_tag" {
   tag_type    = "access"
 }
 
+##############################################################################
+# OCP current version
+##############################################################################
+
+module "get_ocp_version" {
+  source           = "./modules/get-ocp-version"
+  cluster_name     = var.cluster_name
+  ibmcloud_api_key = var.ibmcloud_api_key
+}
+
 ##############################################################################
 # Create a OCP Cluster
 ##############################################################################
@@ -153,7 +163,10 @@ resource "ibm_container_vpc_cluster" "cluster" {
   security_groups = local.cluster_security_groups
 
   lifecycle {
-    ignore_changes = [kube_version]
+    precondition {
+      condition     = module.get_ocp_version.ocp_version < 0 || local.ocp_version_num <= module.get_ocp_version.ocp_version || var.allow_kube_version_upgrade
+      error_message = "Kube version changes are disabled unless allow_kube_upgrade is set to true."
+    }
   }
 
   # default workers are mapped to the subnets that are "private"
@@ -224,7 +237,11 @@ resource "ibm_container_vpc_cluster" "autoscaling_cluster" {
   security_groups = local.cluster_security_groups
 
   lifecycle {
-    ignore_changes = [worker_count, kube_version]
+    ignore_changes = [worker_count]
+    precondition {
+      condition     = module.get_ocp_version.ocp_version < 0 || local.ocp_version_num <= module.get_ocp_version.ocp_version || var.allow_kube_version_upgrade
+      error_message = "Kube version changes are disabled unless allow_kube_upgrade is set to true."
+    }
   }
 
   # default workers are mapped to the subnets that are "private"

modules/get-ocp-version/main.tf

@@ -0,0 +1,12 @@
+##############################################################################
+# OCP Cluster Version
+##############################################################################
+
+data "external" "get_ocp_cluster_version" {
+  program = ["bash", "${path.module}/scripts/get_ocp_cluster_version.sh"]
+
+  query = {
+    cluster_name     = var.cluster_name
+    ibmcloud_api_key = var.ibmcloud_api_key
+  }
+}

modules/get-ocp-version/outputs.tf

@@ -0,0 +1,8 @@
+##############################################################################
+# Outputs
+##############################################################################
+
+output "ocp_version" {
+  description = "OpenShift version of the cluster"
+  value       = tonumber(data.external.get_ocp_cluster_version.result["ocp_version"])
+}

modules/get-ocp-version/scripts/get_ocp_cluster_version.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+## Returns the OCP major.minor version for the given cluster
+## Script is designed to be used with Terraform "external" data source
+## It always outputs JSON (even on error) so Terraform plan/apply does not break
+
+set -euo pipefail
+
+login(){
+    # Login into the IBM Cloud CLI
+    echo "[login] Login to IBM Cloud CLI" >&2
+    DIR="$(cd "$(dirname "$0")" && pwd)"
+    "$DIR"/ibm_cloud_login.sh >/dev/null 2>&1
+    echo "[login] Login complete" >&2
+}
+
+get_ocp_version(){
+    local cluster_name=$1
+    echo " Retrieving OCP version for cluster $cluster_name" >&2
+
+    local output
+    output=$(ibmcloud oc cluster get -c "$cluster_name" --output json 2>/dev/null || true)
+
+    local version
+    version=$(echo "$output" | jq -r '.masterKubeVersion' | cut -d. -f1,2)
+
+    if [[ -z "$version" || "$version" == "null" ]]; then
+        echo "Could not retrieve version for cluster $cluster_name" >&2
+        version="-1"
+    fi
+
+    echo "$version"
+}
+
+## Always return JSON even if something fails
+handle_error() {
+    echo '{"ocp_version": "-1"}'
+    exit 0
+}
+
+## Parse variables passed from Terraform "query"
+## (reads stdin JSON and converts to shell vars)
+eval "$(jq -r '@sh "cluster_name=\(.cluster_name) IBMCLOUD_API_KEY=\(.ibmcloud_api_key)"')"
+export IBMCLOUD_API_KEY
+
+## Trap all errors after parsing input
+trap 'handle_error' ERR
+
+## Login and retrieve version
+login
+ocp_version=$(get_ocp_version "$cluster_name")
+
+## Return JSON to Terraform
+jq -n -r --arg ocp_version "$ocp_version" '{"ocp_version":$ocp_version}'

modules/get-ocp-version/scripts/ibm_cloud_login.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -euo pipefail
+
+attempts=1
+# Expects the environment variable $IBMCLOUD_API_KEY to be set
+until ibmcloud login -q --no-region || [ $attempts -ge 3 ]; do
+    attempts=$((attempts+1))
+    echo "Error logging in to IBM Cloud CLI..." >&2
+    sleep 5
+done

modules/get-ocp-version/variables.tf

@@ -0,0 +1,14 @@
+##############################################################################
+# Input Variables
+##############################################################################
+
+variable "ibmcloud_api_key" {
+  description = "APIkey that's associated with the account to use, set via environment variable TF_VAR_ibmcloud_api_key"
+  type        = string
+  sensitive   = true
+}
+
+variable "cluster_name" {
+  type        = string
+  description = "Name of the target IBM Cloud OpenShift Cluster"
+}

modules/get-ocp-version/version.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.9.0"
+  required_providers {
+    external = {
+      source  = "hashicorp/external"
+      version = ">= 2.2.3"
+    }
+  }
+}

tests/go.mod

@@ -2,7 +2,7 @@ module github.com/terraform-ibm-modules/terraform-ibm-base-ocp-vpc
 
 go 1.24.0
 
-toolchain go1.24.5
+toolchain go1.25.0
 
 require (
 	github.com/gruntwork-io/terratest v0.50.0

tests/pr_test.go

@@ -97,6 +97,7 @@ func setupQuickstartOptions(t *testing.T, prefix string) *testschematic.TestSche
 		TarIncludePatterns: []string{
 			"*.tf",
 			quickStartTerraformDir + "/*.tf", "scripts/*.sh", "kubeconfig/README.md",
+			"modules/get-ocp-version/*.tf", "modules/get-ocp-version/scripts/*.sh",
 		},
 		TemplateFolder:         quickStartTerraformDir,
 		Tags:                   []string{"test-schematic"},
@@ -135,7 +136,7 @@ func TestRunFullyConfigurableInSchematics(t *testing.T) {
 	options := testschematic.TestSchematicOptionsDefault(&testschematic.TestSchematicOptions{
 		Testing:               t,
 		Prefix:                "ocp-fc",
-		TarIncludePatterns:    []string{"*.tf", fullyConfigurableTerraformDir + "/*.*", fullyConfigurableTerraformDir + "/scripts/*.*", "scripts/*.sh", "kubeconfig/README.md", "modules/kube-audit/*.*", "modules/kube-audit/kubeconfig/README.md", "modules/kube-audit/scripts/*.sh", fullyConfigurableTerraformDir + "/kubeconfig/README.md", "modules/kube-audit/helm-charts/kube-audit/*.*", "modules/kube-audit/helm-charts/kube-audit/templates/*.*"},
+		TarIncludePatterns:    []string{"*.tf", fullyConfigurableTerraformDir + "/*.*", fullyConfigurableTerraformDir + "/scripts/*.*", "scripts/*.sh", "kubeconfig/README.md", "modules/kube-audit/*.*", "modules/kube-audit/kubeconfig/README.md", "modules/kube-audit/scripts/*.sh", fullyConfigurableTerraformDir + "/kubeconfig/README.md", "modules/kube-audit/helm-charts/kube-audit/*.*", "modules/kube-audit/helm-charts/kube-audit/templates/*.*", "modules/get-ocp-version/*.tf", "modules/get-ocp-version/scripts/*.sh"},
 		TemplateFolder:        fullyConfigurableTerraformDir,
 		Tags:                  []string{"test-schematic"},
 		DeleteWorkspaceOnFail: false,
@@ -171,7 +172,7 @@ func TestRunUpgradeFullyConfigurable(t *testing.T) {
 	options := testschematic.TestSchematicOptionsDefault(&testschematic.TestSchematicOptions{
 		Testing:               t,
 		Prefix:                "fc-upg",
-		TarIncludePatterns:    []string{"*.tf", fullyConfigurableTerraformDir + "/*.*", fullyConfigurableTerraformDir + "/scripts/*.*", "scripts/*.sh", "kubeconfig/README.md", "modules/kube-audit/*.*", "modules/kube-audit/kubeconfig/README.md", "modules/kube-audit/scripts/*.sh", fullyConfigurableTerraformDir + "/kubeconfig/README.md", "modules/kube-audit/helm-charts/kube-audit/*.*", "modules/kube-audit/helm-charts/kube-audit/templates/*.*"},
+		TarIncludePatterns:    []string{"*.tf", fullyConfigurableTerraformDir + "/*.*", fullyConfigurableTerraformDir + "/scripts/*.*", "scripts/*.sh", "kubeconfig/README.md", "modules/kube-audit/*.*", "modules/get-ocp-version/*.tf", "modules/get-ocp-version/scripts/*.sh", "modules/kube-audit/kubeconfig/README.md", "modules/kube-audit/scripts/*.sh", fullyConfigurableTerraformDir + "/kubeconfig/README.md", "modules/kube-audit/helm-charts/kube-audit/*.*", "modules/kube-audit/helm-charts/kube-audit/templates/*.*"},
 		TemplateFolder:        fullyConfigurableTerraformDir,
 		Tags:                  []string{"test-schematic"},
 		DeleteWorkspaceOnFail: false,

variables.tf

@@ -2,6 +2,13 @@
 # Input Variables
 ##############################################################################
 
+variable "ibmcloud_api_key" {
+  description = "APIkey that's associated with the account to use, set via environment variable TF_VAR_ibmcloud_api_key"
+  type        = string
+  sensitive   = true
+  default     = null
+}
+
 # Resource Group Variables
 variable "resource_group_id" {
   type        = string
@@ -40,6 +47,12 @@ variable "vpc_subnets" {
   description = "Metadata that describes the VPC's subnets. Obtain this information from the VPC where this cluster is created."
 }
 
+variable "allow_kube_version_upgrade" {
+  type        = bool
+  description = "Set to true to allow the module to upgrade the kube version of the cluster. If you wish to make any change to the kube version, set this variable to true."
+  default     = false
+}
+
 variable "allow_default_worker_pool_replacement" {
   type        = bool
   description = "(Advanced users) Set to true to allow the module to recreate a default worker pool. If you wish to make any change to the default worker pool which requires the re-creation of the default pool follow these [steps](https://github.com/terraform-ibm-modules/terraform-ibm-base-ocp-vpc?tab=readme-ov-file#important-considerations-for-terraform-and-default-worker-pool)."