Conditionally Including or Excluding Resources
This topic describes how to use Replicated KOTS annotations and Replicated template functions to include or exclude optional resources based on a conditional statement.
Overview
Often, vendors need a way to optionally install resources depending on users' configuration choices. For example, a common use case is giving the user the choice to use an external database or an embedded database. In this scenario, when a user chooses to use their own external database, it is not desirable to deploy the embedded database resources (StatefulSet, Service, and so on).
To include or exclude resources from your application deployment, you can use the kots.io/exclude
or kots.io/when
annotation on the resource. You can also set the value of the annotation to a conditional statement using Replicated template functions. For information about Replicated template functions, see About Template Functions in Template Functions.
Requirements
The kots.io/exclude
nor kots.io/when
annotations have the following requirements:
By default, if neither
kots.io/exclude
norkots.io/when
is present on a resource, the resource is included.Only one of the
kots.io/exclude
norkots.io/when
annotations can be present on a single resource. If both are present, thekots.io/exclude
annotation is applied, and thekots.io/when
annotation is ignored.The
kots.io/exclude
norkots.io/when
annotations must be written in quotes (for example,"kots.io/exclude":
). This is because Kubernetes annotations cannot be booleans and must be strings. For more information about Kubernetes annotations, see Annotations in the Kubernetes documentation.
Conditionally Exclude a Resource
When the kots.io/exclude: '<bool>'
annotation is present on a resource and evaluates to true, the resource is excluded from the deployment.
The following example excludes the Postgres StatefulSet
when the user disables a install_postgres
checkbox on the Replicated admin console Config page:
apiVersion: apps/v1
kind: Statefulset
metadata:
name: postgresql
annotations:
"kots.io/exclude": '{{repl ConfigOptionEquals "install_postgres" "0" }}'
labels:
app: postgresql
spec:
selector:
matchLabels:
app: postgresql
strategy:
type: Recreate
template:
metadata:
labels:
app: postgresql
spec:
containers:
- name: postgresql
image: "postgres:9.6"
imagePullPolicy: ""
...
Conditionally Include a Resource
When the kots.io/when: '<bool>'
annotation is present on a resource and evaluates to false, the resource is excluded from the deployment.
The following example excludes the postgres StatefulSet
resource when the install_postgres
checkbox is enabled:
apiVersion: apps/v1
kind: Statefulset
metadata:
name: postgresql
annotations:
"kots.io/when": '{{repl ConfigOptionEquals "install_postgres" "1" }}'
labels:
app: postgresql
spec:
selector:
matchLabels:
app: postgresql
strategy:
type: Recreate
template:
metadata:
labels:
app: postgresql
spec:
containers:
- name: postgresql
image: "postgres:9.6"
imagePullPolicy: ""
...