When launching a sandbox based on your blueprint, the user/API/CI process can enter input parameters that will be used by your application and optionally used by the application scripts.
This article explains how to declare which parameters are required by your application, how to pass user inputs from your blueprint to your application, how to use outputs from your application scripts as inputs and how to use parameters in your application scripts. We present an example that covers the use of parameters for both the configuration of the cloud provider network (opening the required port for incoming traffic) and the configuration of an Apache server.
In this article:
- Defining application parameters
- Passing inputs to your application
- Using outputs in other applications and services
- Using parameters in application scripts
Defining application parameters
In your application's YAML file, under the inputs section, declare all the parameters required by your application. The following is an excerpt from an apache-application YAML, in which the connectivity port is defined using an input parameter:
---
spec_version: 1
kind: application
inputs:
- port_number
infrastructure:
connectivity:
external:
- port_info:
port: $port_number
In this example, under the inputs section, the parameter's port_number is declared and under the infrastructure section the application's connectivity port is assigned with the input value $port_number. To learn more about assigning application parameters with a value from input, see Passing input value from your blueprint to your application.
Passing inputs to your application
It is possible to define inputs for the application YAML and use them in all the fields that support inputs (see detailed tables in each section above). The value for those inputs is passed in the blueprint YAML.
The inputs are defined as follows:
inputs:
- {input_name1}
- {input_name2}: {default_value}
It is possible to define the input either with or without a default value. The input name must be unique, must start with alphabetic character or ‘_’, followed by a string of alphanumeric characters or ‘_’.
There are several ways to define inputs in the application/service YAML:
- Write the input with a value: - port_number: 80
- Use an input from the blueprint: - port_number: $Access_Port
- If the input name in the application/service is the same as the name of the blueprint input, you can do one of the following:
- port_number: $port_number
or just the input name to assign it the blueprint input’s value: - port_number
To use the input in any of the supported fields, enter the $ sign followed by the input name. Inputs can be used standalone ($input_name) or as part of a string (shortcut: api.${colony.environment.id}.nectarsleep.com).
To use the input in any of the supported fields, enter the $ sign followed by the input name. In the following example, we declare an input named “azure_vm_size” with a default value “Standard_D2_v3” and use it to define the VM size of the application’s instance in Azure.
inputs:
- azure_vm_size: Standard_D2_v3
infrastructure:
compute:
spec:
azure:
vm_size: $azure_vm_size
When declaring an input parameter, use any of the following parameter definition components:
display_style |
To display the password content in the UI, do not assign a value. To hide the password behind bullets, enter the value 'masked'. |
description | In the relevant UI field, enter a description to be displayed to the user. |
default_value |
When the sandbox is created, the default value automatically fills in. The end user can choose to edit the value or leave as-is. |
optional |
This is a boolean value: enter either true or false. When optional is set to true, the user can leave the parameter empty. When optional is set to false, empty value(s) result in validation error(s). |
There are two ways to declare input parameters: short form and long form.
Short form example:
inputs:
- apache_port: 1234
Long form example:
inputs:
- apache_port:
default_value: 1234
However, if you want to change more than one property of the parameter, you MUST use the long form (if you don't, the YAML file will not be valid). For example:
inputs:
- apache_port:
display_style: masked
default_value: 1234
Using outputs in other applications and services
The application can also declare outputs, commonly populated by the scripts associated with the application and used as inputs in other applications, application scripts and services.
First, define the outputs in your application YAML.
kind: application
ostype: windows
inputs:
- PORT: 3001
- WELCOME_STRING: Welcome to Quali Colony!
- PUBLIC_ADDRESS: 'none'
outputs:
- name
- version
- hostname
To use these outputs, ythe application's init script must declare them as environment values and fill in their values. There are different ways to do this for Windows and Linux operating systems.
Windows example (using a PS1 file):
$env:hostname="demoapp-server-windows.$env:DOMAIN_NAME"
$env:name='demo-server';
$env:version='1.0'
Linux example (using a bash file):
export name=$SERVER_NAME
export version=$SERVER_VERSION
export hostname ="/;/env"
Note that Colony doesn't care where the value inside the scripts comes, as long as by the end of the init script, there exist environment variables with the exact same names as the outputs defines in the YAML,. When the script ends, Colony collects the environment variable values and places them them in the output variables.
To pass an output as an input value to other applications and services in the environment, use the following format in the blueprint YAML:
$colony.applications.{app_name}.outputs.{output_name}
For example:
applications:
- client-app:
input_values:
- server-password: $colony.applications.server-app.outputs.password
Using parameters in application scripts
Environment Variables
When CloudShell Colony deploys your application, it automatically creates an environment variable for each parameter declared under the inputs section of your application's YAML. In addition, CloudShell Colony creates the following environment variables:
ARTIFACTS_PATH | The path to the folder in which Colony keeps all your scripts and artifacts. |
DOMAIN_NAME |
The local DNS name that identifies your sandbox. IMPORTANT: This parameter has been deprecated but is still supported for backwards compatibility. Use the $colony.applications.app_name.dns input instead. For details, see The Blueprint YAML File. |
SANDBOX_ID | The identifier of the sandbox. |
COLONY_INSTANCE_ID | The identifier of the compute instance. |
The following example shows the use of environment variable port_number to configure the Apache server's connectivity port. By creating the environment variables, CloudShell Colony makes the application parameters available for use by your application scripts.
sed -i "s/Listen 80/Listen $port_number/g" /etc/apache2/ports.conf
sed -i "s/80/$port_number /g" /etc/apache2/sites-enabled/000-default.conf
systemctl start apache2
Comments
0 comments
Please sign in to leave a comment.