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:

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:

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