Skip to main content

Using Conditional Statements in Configuration Fields

This topic describes how to use Replicated template functions in the Config custom resource to conditionally show or hide configuration fields for your application on the Replicated admin console Config page.

Overview​

The when property in the Config custom resource denotes configuration items that are displayed on the admin console Config page only when a condition evaluates to true. When the condition evaluates to false, the field is not displayed. It can be useful to show or hide fields so that your users are only provided the configuration options that are relevant to them. This helps to reduce user error when configuring the application.

You can conditionally show or hide configuration fields based on the user's environment, license entitlements, and preferences. For example, conditional statements in the when property can be used to evaluate:

  • The Kubernetes distribution of the cluster
  • If the license includes a specific feature entitlement
  • The number of users that the license permits
  • If the user chooses to bring their own external database, rather than using an embedded database offered with the application

For more information about the Config custom resource when property, see when in Config.

You can construct conditional statements in the when property using Replicated template functions. Replicated template functions are a set of custom template functions based on the Go text/template library that can be used to generate values specific to customer environments. For more information about Replicated template functions, including a full list of available template functions, see About Template Functions. For more information about the Go library, see text/template in the Go documentation.

Conditional Statement Examples​

This section includes examples of common types of conditional statements used in the when property of the Config custom resource.

For additional examples of using conditional statements in the Config custom resource, see Applications in the platform-examples repository in GitHub.

Cluster Distribution Check​

It can be useful to show or hide configuration fields depending on the distribution of the cluster because different distributions often have unique requirements.

In the following example, the when properties use the Distribution template function to return the Kubernetes distribution of the cluster where Replicated KOTS is running. If the distribution of the cluster matches the specified distribution, then the when property evaluates to true. For more information about the Distribution template function, see Distribution in Static Context.

# Config custom resource
apiVersion: kots.io/v1beta1
kind: Config
metadata:
  name: config-sample
spec:
  groups:
    - name: example_settings
      title: My Example Config
      description: Example fields for using Distribution template function
      items:
      - name: gke_distribution
        type: label
        title: "You are deploying to GKE"
        when: 'repl{{ eq Distribution "gke" }}'
      - name: kurl_distribution
        type: label
        title: "You are deploying to kURL"
        when: 'repl{{ eq Distribution "kurl" }}'
      - name: eks_distribution
        type: label
        title: "You are deploying to EKS"
        when: 'repl{{ eq Distribution "eks" }}'
      ...

The following image shows how only the gke_distribution item is displayed on the Config page when KOTS is running in a GKE cluster:

Config page with the text "You are deploying to GKE"

View a larger version of this image

kURL Cluster Check​

It can be useful to show or hide configuration fields if the cluster was provisioned by Replicated kURL because kURL distributions often include add-ons to manage functionality such as ingress and storage. This means that kURL clusters frequently have fewer configuration options for the end user.

In the following example, the when property of the not_kurl group uses the IsKurl template function to evaluate if the cluster was provisioned by kURL. For more information about the IsKurl template function, see IsKurl in Static Context.

# Config custom resource
apiVersion: kots.io/v1beta1
kind: Config
metadata:
  name: config-sample
spec:
  groups:
    - name: all_distributions
      title: Example Group
      description: This group always displays.
      items:
      - name: example_item
        title: This item always displays.
        type: text
    - name: not_kurl
      title: Non-kURL Cluster Group
      description: This group displays only if the cluster is not provisioned by kURL.
      when: 'repl{{ not IsKurl }}'
      items:
      - name: example_item_non_kurl
        title: The cluster is not provisioned by kURL.
        type: label

As shown in the image below, both the all_distributions and non_kurl groups are displayed on the Config page when KOTS is not running in a kURL cluster:

Config page displays both groups from the example

View a larger version of this image

However, when KOTS is running in a kURL cluster, only the all_distributions group is displayed, as shown below:

Config page displaying only the first group from the example

View a larger version of this image

License Field Value Equality Check​

You can show or hide configuration fields based on the values in a license to ensure that users only see configuration options for the features and entitlements granted by their license.

In the following example, the when property of the new_feature_config item uses the LicenseFieldValue template function to determine if the user's license contains a newFeatureEntitlement field that is set to true. For more information about the LicenseFieldValue template function, see LicenseFieldValue in License Context.

apiVersion: kots.io/v1beta1
kind: Config
metadata:
  name: config-sample
spec:
  groups:
    - name: example_settings
      title: My Example Config
      description: Example fields for using LicenseFieldValue template function
      items:
      - name: new_feature_config
        type: label
        title: "You have the new feature entitlement"
        when: '{{repl (LicenseFieldValue "newFeatureEntitlement") }}'

As shown in the image below, the Config page displays the new_feature_config item when the user's license contains newFeatureEntitlement: true:

Config page displaying the text "You have the new feature entitlement"

View a larger version of this image

License Field Value Integer Comparison​

You can show or hide configuration fields based on the values in a license to ensure that users only see configuration options for the features and entitlements granted by their license. You can also compare integer values from license fields to control the configuration experience for your users.

The following example uses the LicenseFieldValue template function to evaluate the number of seats permitted by the license. This example also uses the Atoi function in the strconv Go package to convert the string values from the license to integers, then uses Go binary comparison operators to compare the integers.

For more information about the LicenseFieldValue template function, see LicenseFieldValue in License Context. For more information about Atoi, see strconv in the Go documentation.

apiVersion: kots.io/v1beta1
kind: Config
metadata:
  name: config-sample
spec:
  groups:  
  - name: example_group
    title: Example Config
    items:
    - name: small
      title: Small (100 or Fewer Seats)
      type: text
      default: Default for small teams
      when: '{{repl le (atoi (LicenseFieldValue "numSeats")) 100 }}'
    - name: medium
      title: Medium (101-1000 Seats)
      type: text
      default: Default for medium teams
      when: '{{repl (and (ge (atoi (LicenseFieldValue "numSeats")) 101) (le (atoi (LicenseFieldValue "numSeats")) 1000)) }}'
    - name: large
      title: Large (More Than 1000 Seats)
      type: text
      default: Default for large teams
      when: '{{repl gt (atoi (LicenseFieldValue "numSeats")) 1000 }}'

As shown in the image below, if the user's license contains numSeats: 150, then the medium item is displayed on the Config page and the small and large items are not displayed:

Config page displaying the Medium (101-1000 Seats) item

View a larger version of this image

User-Supplied Value Check​

You can show or hide configuration fields based on user-supplied values on the Config page to ensure that users only see options that are relevant to their selections.

In the following example, the database_host and database_passwords items use the ConfigOptionEquals template function to evaluate if the user selected the external database option for the db_type item. For more information about the ConfigOptionEquals template function, see ConfigOptionEquals in Config Context.

apiVersion: kots.io/v1beta1
kind: Config
metadata:
  name: config-sample
spec:
  groups:  
  - name: database_settings_group
    title: Database Settings
    items:
    - name: db_type
      title: Database Type
      type: select_one
      default: external
      items:
      - name: external
        title: External Database
      - name: embedded
        title: Embedded Database
    - name: database_host
      title: Database Hostname
      type: text
      when: '{{repl (ConfigOptionEquals "db_type" "external")}}'
    - name: database_password
      title: Database Password
      type: password
      when: '{{repl (ConfigOptionEquals "db_type" "external")}}'

As shown in the images below, when the user selects the external database option, the database_host and database_passwords items are displayed. Alternatively, when the user selects the embedded database option, the items are not displayed:

Config page displaying the database host and password fields

View a larger version of this image

Config page with embedded database option selected

View a larger version of this image

Use Multiple Conditions in the when Property​

You can use more than one template function in the when property to create more complex conditional statements. This allows you to show or hide configuration fields based on multiple conditions being true.

The following example includes when properties that use both the ConfigOptionEquals and IsKurl template functions:

apiVersion: kots.io/v1beta1
kind: Config
metadata:
  name: config-sample
spec:
  groups:  
  - name: ingress_settings
    title: Ingress Settings
    description: Configure Ingress
    items:
    - name: ingress_type
      title: Ingress Type
      help_text: | 
        Select how traffic will ingress to the appliction.
      type: select_one
      items:
      - name: ingress_controller
        title: Ingress Controller
      - name: load_balancer
        title: Load Balancer
      default: "ingress_controller"
      required: true
      when: 'repl{{ not IsKurl }}'
    - name: ingress_host
      title: Hostname
      help_text: Hostname used to access the application.
      type: text
      default: "hostname.example.com"
      required: true
      when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "ingress_controller") }}'
    - name: ingress_annotations
      type: textarea
      title: Ingress Annotations
      help_text: See your ingress controller’s documentation for the required annotations.
      when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "ingress_controller") }}'
    - name: ingress_tls_type
      title: Ingress TLS Type
      type: select_one
      items:
      - name: self_signed
        title: Self Signed (Generate Self Signed Certificate)
      - name: user_provided
        title: User Provided (Upload a TLS Certificate and Key Pair)
      required: true
      default: self_signed
      when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "ingress_controller") }}'
    - name: ingress_tls_cert
      title: TLS Cert
      type: file
      when: '{{repl and (ConfigOptionEquals "ingress_type" "ingress_controller") (ConfigOptionEquals "ingress_tls_type" "user_provided") }}'
      required: true
    - name: ingress_tls_key
      title: TLS Key
      type: file
      when: '{{repl and (ConfigOptionEquals "ingress_type" "ingress_controller") (ConfigOptionEquals "ingress_tls_type" "user_provided") }}'
      required: true
    - name: load_balancer_port
      title: Load Balancer Port
      help_text: Port used to access the application through the Load Balancer.
      type: text
      default: "443"
      required: true
      when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "load_balancer") }}'
    - name: load_balancer_annotations
      type: textarea
      title: Load Balancer Annotations
      help_text: See your cloud provider’s documentation for the required annotations.
      when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "load_balancer") }}'

As shown in the image below, the configuration fields that are specific to the ingress controller display only when the user selects the ingress controller option and KOTS is not running in a kURL cluster:

Config page displaying the ingress controller options

View a larger version of this image

Additionally, the options relevant to the load balancer display when the user selects the load balancer option and KOTS is not running in a kURL cluster:

Config page displaying the load balancer options

View a larger version of this image