Parameters

App Parameters take Apps to the next level by allowing administrators to provide customizations for users who would like to deploy the App, while still maintaining control over the allowable inputs for those customizations.

An example use case for an App with Parameters could be a simple helm App that represents an organization's primary business application. The helm chart would define the deployments, configmaps, and any other kubernetes resources necessary to deploy the application. This application should be able to be deployed into "dev", "test", and "prod" environments, and the applications behavior is governed by environment variables (that define the application deployment stage) configured in a configmap in the deployment. As with any good helm chart, the chart contains values that allow for configuring the stage of the application. vCluster.Pro administrators could expose this App to vCluster.Pro users, and rather than relying on the users to properly set a helm value of "dev" or "test", the vCluster.Pro administrator can instead simply provide a list of valid options to the user. At time of deployment of the App, the user would be prompted to select from one of the valid options, and that option would be properly passed as a value to the chart.

The above example is an overly simplified example meant to give a glimpse of the flexibility of Apps with Parameters. Parameters can be used to provide a list of valid options to a user, or to simply accept a text field input. Raw text input can also be validated by a regular expression to ensure that users are not providing illegal input. The values of these Parameters can then be referenced anywhere in the App definition!

Parameter Definition

Parameters are provided as YAML data structures. The following snippet shows a simple parameter definition that will prompt a user to select from an entry in the options list:

- variable: mylabelvalue
  label: vClusterStatefulSetLabelValue
  description: Please select the value for the vCluster statefulset "my-label" key
  options:
    - one
    - two
  section: Labels

Parameters can also be free-form text fields that are optionally validated. The following snippet shows an example option that accepts a user input string and validates it against the validation regular expression:

- variable: anotherlabelvalue
  label: AnImportantValue
  description: Please enter this very important value
  section: Important Values
  required: true
  validation: "^\w+{8,63}$"

Accessing Parameter Values

The value of Parameters can be accessed in the rest of the App definition. If you have worked with go templates, this will be very familiar to you, but even if you haven't it is quite simple! Values can be accessed in your app using the {{ .Values. myvalue }} notation -- where myvalue is the name of in the variable field of your Parameters declaration.

Below is a simple example of referring to a variable named mylabelvalue:

labels:
  my-label: "{{ .Values.mylabelvalue }}"

vCluster.Pro Parameter values

In addition to user created parameters, the vCluster.Pro controller will always merge in some vCluster.Pro-specific parameters that are also available to you. The available parameters differ slightly depending on where you are deploying the App -- be it a virtual cluster or a space. These values are behind the vCluster.Pro key!

Object	YAML Key	Value
Project	project	The name of the project that contains the space/virtualcluster the app is being deployed into
Space	space	The name of the space (if applicable) the app is being deployed into
VirtualCluster	virtualClusterName	The name of the virtual cluster (if applicable) the app is being deployed into
Cluster	cluster	The name of the cluster the space/virtualcluster (and by extension the app) is in
VirtualClusterNamespace	virtualClusterNamespace	The namespace the virtualcluster is in

With this you could access the virtualClusterName as follows:

labels:
  my-label: "{{ .Values.loft.virtualClusterName }}"

Creating an App with Parameters

Creating an App with Parameters can be achieved via the vCluster.Pro UI.

1. Select the Templates field on the left menu bar.
2. Click the Apps option on the templates pane.
3. Click .
4. In the drawer that appears from the right, give your new app a name by replacing the 'my-app' placeholder name, or by updating the manifest YAML 'metadata.name' field.
5. Click the Parameters to access the Parameters configuration section.
6. Enter valid YAML representing the Parameters you would like to use with your App.
7. Make any additional modifications to your App.
8. Click the button.