Specifying version constraints

Use version constraints to declare the Terraform, Terraform provider, or Ansible version that you want to use for your Terraform template, or Ansible playbook.

Schematics concurrently supports multiple images that each package a specific version of the IBM Cloud Provider plug-in, other Terraform providers, such as the REST API provider, and the Ansible executable. Each image is built, tested, and verified by IBM Cloud. Included Terraform provider versions are tested and packaged for a specific Terraform CLI version.

It is good practice to declare the version that your Terraform template, or Ansible playbook requires by using version constraints. This way, you can ensure that your templates and playbooks continue to work, even if Terraform, Terraform providers, or Ansible publish new versions that might introduce breaking changes.

Overview of Schematics images and packaged Terraform providers

Use the ibmcloud schematics version command to retrieve a list of Schematics images and the Terraform provider and Ansible executable versions that are packaged in each image. For example in the following CLI output, the IBM Cloud Provider plug-in latest version is tested on Terraform v1.1.

Schematics supports the 5 most recent versions of IBM Cloud Provider Plug-in for Terraform binaries in its image. For more information, see latest releases. Following are some constraints that you must follow when using the IBM Cloud provider in your Terraform template.

It is recommended to use Terraform v1.0 or higher.

If you are using Terraform v0.13 or higher, you can arbitrarily choose any version of the IBM Cloud provider, in your template. Then, Schematics automatically download the IBM Cloud provider either locally from the cache or remotely from the HashiCorp Configuration Language (HCL) Terraform Registry.

To use any of the predefined Schematics images, you must explicitly declare the version of the IBM Cloud Provider plug-in in your Terraform template that includes the provider versions that you want. For more information, see Specifying version constraints for the Terraform CLI and Terraform providers.

You cannot change the default version for the Ansible executable. You can only specify the version of referenced Ansible roles and collections.

ibmcloud schematics version


  Template Type   Version
  terraform       terraform_v1.3
  Additional terraform Providers   Version
  IBM Cloud Provider               v1.38.2
  Red Hat OpenShift client         v3.11.0
  ansible                          v2.9.23
  Ansible Provisioner              v2.3.3
  Provider for REST API            v1.10.0
                                  
  Template Type   Version
  terraform       terraform_v1.4
  Additional terraform Providers   Version
  ansible                          v2.9.23
  Red Hat OpenShift client         v3.11.0
  Ansible Provisioner              v2.3.3
  IBM Cloud Provider               v1.38.2
  Provider for REST API            v1.10.0
                                  
  Template Type   Version
  terraform       terraform_v1.5
  Additional terraform Providers   Version
  IBM Cloud Provider               v1.38.2
  Provider for REST API            v1.10.0
  ansible                          v2.9.23
  Ansible Provisioner              v2.3.3
  Red Hat OpenShift client         v3.11.0
                                  
  Template Type   Version
  terraform       terraform_v1.6
  Additional terraform Providers   Version
  Red Hat OpenShift client         v3.11.0
  ansible                          v2.9.23
  IBM Cloud Provider               v1.38.2
  Provider for REST API            v1.10.0
  Ansible Provisioner              v2.3.3
                                  
  OK

Specifying version constraints for the Terraform CLI and Terraform providers

You can choose to specify the Terraform CLI version and the version of any of the providers that you want to use by using Terraform version constraints. For more information about how to specify version constraints, see the Terraform documentation.

Version constraints for the Terraform CLI

When you create a Schematics workspaces and choose a Terraform version such as v1.4, your Terraform templates are executed by using the default patch version that is set in Schematics. For example, if you choose terraform_v1.4, your templates are applied by using Terraform v0.13.4. You can use the required_providers block in your provider definition to force the Terraform engine in Schematics to pull a later version.

You can only specify versions that are higher than the default MAJOR.MINOR.PATH version that is set in Schematics. In the codeblock version = "x.x.x" signifies the IBM Cloud provider version.

terraform {
    required_providers {
        version = "1.39.1"
    }
}

You can specify Terraform required_versions that are higher than the default MAJOR.MINOR.PATH in the Terraform configuration file. In the codeblock the required_version = ">=1.0.0, <2.0" signifies the Terraform version.

terraform {
required_version = ">=1.0.0, <2.0"
  required_providers {
    ibm = {
      source = "IBM-Cloud/ibm"
    }
  }
}

Version constraints for Terraform providers

To use any of the predefined Schematics images, you must explicitly declare the version of the IBM Cloud Provider plug-in in your Terraform template that includes the provider versions that you want.

If IBM Cloud Provider plug-in version is not declared in your Terraform template, the latest version of the provider plug-in is automatically used in Schematics.

Example to specify a predefined Schematics image:

The following example shows how to use the Schematics image that was built for the IBM Cloud Provider plug-in v1.39.1. This image includes specific versions for other providers, such as the REST API provider.

terraform {
    required_providers {
        ibm = {
        source = "IBM-Cloud/ibm"
        version = "v1.39.1"
    }
    }

Example to use specific Terraform provider versions:

To use a different IBM Cloud Provider plug-in version, or to pin your Terraform configuration file to a specific version of another external provider, such as AWS, Helm or Kubernetes, use the following syntax.

terraform {
    required_providers {
        ibm = {
        source = "IBM-Cloud/ibm"
        version = "~> 1.38.1"
    }
    aws = {
        version = ">= 2.7.0"
        source = "hashicorp/aws"
    }
    }

Specifying version constraints in Ansible

Schematics currently supports the latest Ansible version v2.9.23 only. When you create a Schematics action, you must ensure that your Ansible playbooks can be run with this version. You cannot specify a specific Ansible version for your playbook.

However, if you use existing Ansible roles or collections in your playbook, you can specify the version of the role or collection that you want to run by using a requirements.yml file. For more information about how to reference roles and collections in your playbook, see Referencing Ansible roles in your playbook and Referencing Ansible collections in your playbook. To learn more about how to specify versions for roles and collections, see the Ansible documentation.

roles:
  - name: andrewrothstein.kubectl
    version: 1.1.50