A blueprint models an application stack in a specific configuration. Blueprints typically include applications and cloud services. Each blueprint is defined in a dedicated YAML file that resides in the /blueprints folder within the GitHub/BitBucket repository that is associated with the space. For details, see Setting up a Blueprints Repository.

In this article:

• Example of a blueprint YAML
• Basic Attributes
• Metadata
• Clouds
• Applications
• Services
• Artifacts
• Debugging
• Infrastructure
• Ingress
• Inputs

Example of a blueprint YAML

TIP: For more information about each sequence or key-value pair, click the  icon next to it.

spec_version: 1 
kind: blueprint                    
environmentType: sandbox 
 
metadata:                          
  description: > 
    A Java Spring website deployed on a Tomcat server and MySQL Aurora serverless cluster 

clouds:                            
  - AWS: eu-west-1 
 
artifacts:                         
  - java-spring-website: latest/colony-java-spring-sample-1.0.0-BUILD-SNAPSHOT.war 
      inputs: 
        - DB_USER: root
        - DB_PASS:
            display_style: masked
            description: >
              please set the root database password default_value: Colony!123
        - DB_NAME: demo_db

applications: 
  - java-spring-website:
      instances: 1
      input_values: 
        - DB_USER: $DB_USER 
        - DB_PASS: $DB_PASS 
        - DB_NAME: $DB_NAME 
        - DB_HOSTNAME: $colony.applications.rds-mysql-aurora-cluster.hostname 
        depends_on:  
          - rds-mysql-aurora-cluster 
services: 
  - rds-mysql-aurora-cluster: 
      input_values: 
        - DB_NAME: $DB_NAME 
        - DB_USER: $DB_USER 
        - DB_PASS: $DB_PASS 
        - CLUSTER_MIN_CAPACITY: 2 
        - CLUSTER_MAX_CAPACITY: 4 
        - SANDBOX_ID: $colony.environment.id 
        - VPC_ID: $colony.environment.virtual_network_id 
debugging: 
  availability: on

The blueprint YAML consists of multiple sections that are detailed below. In order to be functional, the blueprint YAML must include the following:

• Basic YAML attributes
• Cloud definition
• At least one application defined

Basic Attributes

kind: application 
spec_version: 1 

Metadata

Here you can define the blueprint's description. The description is visible to users when they launch a sandbox and select the blueprint from the catalog. 

metadata: 
  description: {description}  

Clouds

In this section you define the cloud account or Kubernetes compute service in which the environment will be deployed. For the blueprint to be valid, all the applications that the blueprint uses should have a source defined for the blueprint’s cloud provider type, in the specified region.

NOTE: Currently, it is possible to specify only one cloud account or Kubernetes compute service in the blueprint. Multiple regions per cloud account are not supported. 

Format:

For cloud accounts AWS and Azure:

clouds:
  - {cloud_account_name}: {region_name}

For Kubernetes compute services:

clouds:
  - {cloud_account_name}: {kubernetes-compute-service-name}

Examples:

clouds:
  - aws1: eu-west-1

clouds:
  - azure-staging: westeurope

clouds:
  - aws1/kubernetes-testing

Applications

In this section of the blueprint YAML, you declare the applications that are part of this blueprint, provide information about the instances they will be deployed on, define dependencies between the applications and services, and pass input values to the applications. To learn how to specify the dependencies between services and/or applications and the dependency hierarchy, see Specifying deployment order and dependencies.

The applications are defined in their own YAML files. The YAMLs should reside in a dedicated /applications folder located in the same repository as the blueprint YAML. For more information see The Application YAML File. 

applications: 
  - {app_name1}: 
      instances: {instances_number} 
      target: {target_instance} 
      input_values: 
        - {input_name}: {input_value} 
      depends_on: 
        - {app_or_service_name}

NOTE: It is possible to deploy an application either on its own on one or more instances (“instances”), or in a shared instance together with other applications (“target”). To learn how to map your applications to the required compute instances, see Mapping Applications to Compute Instances. 

Example:

applications: 
  - java-spring-website: 
      instances: 1 
      input_values: 
        - DB_USER: $DB_USER 
        - DB_PASS: $DB_PASS 
        - DB_NAME: $DB_NAME 
        - DB_HOSTNAME: $colony.applications.rds-mysql-aurora-cluster.hostname 
      depends_on: 
        - rds-mysql-aurora-cluster 

Redirecting traffic to certain applications using Ingress rules

Advanced scenarios call for a more flexible configuration of your sandbox environment’s application load balancer. For example, in cases where your sandbox environment includes multiple applications and you need to redirect the traffic to certain applications based on a URL path. 

Such flexibility can be added to your sandbox environment by adding Ingress rules to your blueprint. For details, see Ingress.

Services

In this section of the blueprint YAML, you declare the services that are part of this blueprint, define application and service dependencies, and pass input values to the services. Each service is defined in a dedicated service YAML file that should reside in a /services folder that is located in the same repository as the blueprint YAML. To learn how to specify the dependencies between services and/or applications and the dependency hierarchy, see Specifying deployment order and dependencies.

NOTE: Colony currently supports services based on Terraform. For more information see The Service YAML File (Modeling Cloud Services with Terraform).  

services: 
  - {service_name}: 
      input_values: 
        - {input_name}: {input_value}

Artifacts

Deploying an application might require using certain artifacts. For example, deploying a new version of your software using artifacts when testing a new version of your code. 

Colony integrates with common artifact repository providers such as Azure Storage, AWS S3 and JFrog Artifactory. 

Artifacts are defined in the blueprint YAML and exposed as inputs to the user who launches the blueprint. You can optionally provide a default value for the artifact’s path or keep it empty making the input mandatory for the end user to fill in. For details about defining artifacts in Colony, see Adding Artifacts to your Blueprint. 

artifacts: 
- {application_name}: '{artifact_path}' 

Colony pulls these artifacts from your storage provider into your artifacts folder on the application’s compute instance(s). 

Example:

artifacts: 
- demoapp-server: ' demoapp-server/production/demoapp-server.tar.gz' 

Defining artifacts to the application's initialization scripts

Make sure to properly define a parameter to hold the path to your artifacts folder on your compute instance. To deploy the artifacts, in your application's initialization script, add access to the artifact folder using the environment variable that holds the folder path. 

The following is a simple script that extracts the artifact file demoapp-server.tar.gz from the artifact folder located in $ARTIFACT_PATH.

cd $ARTIFACTS_PATH;

tar -xvf demoapp-server.tar.gz;

To learn more about defining and working with parameters in blueprints and applications, see Working with Parameters. 

Debugging

To allow debugging of the applications in the blueprint, Colony supports an in-browser connection (SSH or RDP) to the instance(s) on which the applications are deployed. To do this, Colony deploys, in the sandbox's cloud environment, a compute instance that provides a remote gateway capability into all the other instances in your environment. This feature is called Bastion and incurs an infrastructure cost from your cloud-provider, although it’s designed to minimize costs while maximizing your troubleshooting efficiency.

By default, the Bastion feature is enabled, and the Bastion instance is deployed and then powered off. You can turn it on and off via the Troubleshooting tab in your sandbox page. 

Optionally, you can also control the default Bastion behavior in the blueprint YAML. 

Note that you can control the availability and protocol of the debugging links also per application, in the application YAML. 

debugging: 
  bastion_availability: {availability_mode} 

Example:

debugging: 
  bastion_availability: {availability_mode} 

Infrastructure

Colony supports two deployment modes for an environment – dedicated and shared. In dedicated mode, Colony creates all the cloud infrastructure such as virtual network (VPC or VNET), subnets, security groups etc. specifically for the sandbox, and when the sandbox duration ends all of this cloud infrastructure is deleted. In shared mode, the administrator specifies, at the space level, the details of an existing virtual network and subnets as well as the cloud region to use, and Colony will deploy the sandbox's infrastructure in accordance. 

The above is true for sandbox (pre-production) environments. For production environments, Colony supports only the dedicated mode, in which all the infrastructure already exists in the cloud account and is provided to Colony in the production blueprint YAML. 

The cloud infrastructure is defined in the production blueprint YAML as follows: 

infrastructure: 
   green_host: green.lv-colony-prod.com
   connectivity: 
     virtual_network:  
       id: {virtual network id}  
       subnets: 
         gateway:  
          - {subnet id} 
         management:  
          - {subnet id} 
        application:  
           - {subnet id} 
           - {subnet id} 

In Azure, there should be a VNET prepared in advance, containing 1 empty subnet for the application gateway, 1 subnet for management and at least 1 subnet for applications. In AWS, there should be a VPC prepared in advance, containing 1 subnet for management and at least 2 subnets for application. 

Using an existing Application Load Balancer

For AWS deployments, it is possible to define an existing stack to be used for the environment infrastructure, which already contains an ALB. If such a stack is defined in the production blueprint YAML, the stack will not be automatically deleted when the production environment is terminated, and it can be re-used with the same ALB. 

The stack is defined as follows:

infrastructure: 
  stack: ‘{stack name}’ 

Example:

infrastructure: 
  stack: ‘demo-alb-internal'

Ingress

An Application Load Balancer (ALB in AWS) or Application Gateway (AG in Azure) is deployed, as part of an environment in Colony, to handle any external communication to the environment.

However, it is possible to define listeners that will be configured on the ALB/AG. These listeners define the external ports of the sandbox and the rules that connect them to the sandbox's applications. A listener can be of type HTTP or HTTPS, followed by the port number to open. For each listener, you can define a list of rules that determine when the traffic is forwarded to different applications. The rules can be based on a path, host header or both and are applied in the order they appear in the ingress section, from top to bottom.

This is done as follows:

ingress: 
  listeners: 
    - {listener type}: {listener port} 
      redirect_to_listener: {listener port} 
      certificate: {certificate} 
      rules: 
      - path: {path} 
        host: {host} 
        application: {application name} 
        port: {application port} 
        color: {environment color} 
        shortcut: {shortcut} 
        default: {default} 

For example:

ingress: 
  listeners: 
    - http: 80 
      redirect_to_listener: 443 
    - https: 443 
      certificate: $CERT_ARN 
      rules: 
      - path: /api/* 
        host: green.sometest.com 
        application: nectar-api 
        port: 3001 
        color: green 
        shortcut: green.sometest.com/api/index 
      - host: green.sometest.com 
        application: nectar-web 
        port: 3000 
        color: green 
        shortcut: green.sometest.com 
      - path: /api/* 
        application: nectar-api 
        port: 3001 
        color: blue 
        shortcut: sometest.com/api/index 
      - default: true 
        application: nectar-web 
        port: 3000 
        color: blue 
        shortcut: sometest.com 

ingress:
  listeners:
    - http: 80
      redirect_to_listener: 443
    - https: 443
      certificate: $CERT_ARN
      rules:
      - default: true
        application: nectar-web
        port: 80

Load balancers

It is also possible to disable the creation of an ALB/AG in the environment as the entry point to the sandbox, to reduce deployment time, especially on private environments, and to reduce the cost of the environment. This is done by including:

ingress: 
  enabled: false 

NOTE: Disabling the ALB or AG means that each application will get its own IP and open ports, and that the public health-check will be disabled. Note that ALB or AG will be disabled by default if no application in the environment exposes an external port.

Related Topics

• Disabling the Use of Load Balancers in Your Blueprint
• Using Existing Application Load Balancers (ALB) in Production Environments
• Redirecting Traffic to Certain Sandbox Applications.

Inputs

The inputs section is where you declare your blueprint parameters. Parameters are defined in your blueprint and can then be passed on to applications. Any input parameter specified under the inputs section of the blueprint can be provided by the user, API or CI plugin when creating a sandbox from this blueprint.

The inputs are defined as follows:

spec_version: 1 
kind: blueprint 
inputs: 
  - input_name:  
      display_style: masked
      description: please set the Apache server's port
      default_value: 1234
      optional: true
applications: 
  - apache: 
     instances: 1 
       input_values: 
         - port_number : $input_name

There are two ways to declare 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

The input names should be unique, must start with an alphabetic character or an underscore: "_", followed by a string of alphanumeric characters or "_". To use the input in any of the supported fields, enter the $ sign followed by the input name.  

The value for the input can be one of the following:

• Hardcoded value 
• Value coming from a blueprint input in the format ${input_name} 
• Output of another application ($colony.applications.app_name.outputs.output_name) or service ($colony.services.service_name.outputs.output_name)

In addition, you can use the following reserved input values that are calculated by Colony during the sandbox deployment:

• $colony.applications.app_name.dns: DNS name of the application app_name in the sandbox (as decided by the cloud provider)

• $colony.environment.id: Sandbox Id of the given sandbox

• $colony.applications.app_name.outputs.output_name: Output of another application

• $colony.services.service_name.outputs.output_name: Output of another service

• $colony.environment.public_address: Public address of the sandbox (as decided by the cloud provider)

• $colony.environment.virtual_network_id: Existing virtual network id to be used by the Sandbox being deployed (VPC ID in AWS or VNET Name in Azure)

For example, if you want to pass an Application A's DNS name to Application B, you can set the following input parameter in Application B:

APP_A_DNS = $colony.applications.app_name.dns

And then you can access the DNS name in Application B's scripts using the input variable $APP_A_DNS.

NOTE: Once a parameter is defined it can optionally be assigned with a default value. Assigning a value is done in the applications section of your blueprint.

To learn more about creating input parameters and assigning them with values, see Working with Parameters.