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 on the GitHub/BitBucket repository that is associated with the space.
In this article:
- Example of a blueprint YAML
- Basic Attributes
- Metadata
- Clouds
- Applications
- Services
- Artifacts
- Debugging
- Infrastructure
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: $outputs.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.SandboxId
- VPC_ID: $COLONY.VirtualNetworkId
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
| Field | Value | Description | Supports inputs? |
| spec_version | 1 | (Mandatory) YAML spec version, currently version 1 is the latest available | No |
| kind | blueprint | (Mandatory) Options are “application”, “blueprint” or “service”. In this case, specify “blueprint”. | No |
Metadata
Here you can define the blueprint's description and custom tags. The description is visible to users when they launch a sandbox and select the blueprint from the catalog. Custom tags are associated with all the cloud resources Colony creates in the cloud account for sandboxes based on this blueprint. In addition to colony’s default tags (TBD link to article). Note that these custom tags do not apply to Terraform services, which are detailed in The Service YAML File (Modeling Cloud Services with Terraform).
metadata:
description: {description}
tags:
{tag_name1}: {tag_value}
{tag_name2}: {tag_value}
| Field | Value | Description | Supports inputs? |
| description | string | (Optional) This description is displayed to users when they launch a sandbox and select the blueprint from the catalog. | No |
| tag_name | string |
(Optional) The name of the tag that is created in the cloud provider and associated with each of the environment's elements.
|
No |
| tag_value | string | (Optional) The value of the tag that is created in the cloud provider and associated with each of the environment's elements. | No |
Clouds
In this section you define the cloud account and region the environment will be deployed on. 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. Currently, only one cloud account and one region can be specified in the blueprint.
NOTE: Currently it is possible to specify only only one cloud account and one region.
clouds:
- {cloud_account_name}: {region_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.
| Field | Value | Description | Supports inputs? |
| app name | string |
(Mandatory) The name of the application. An application folder and YAML with this name should reside in the /applications folder in the blueprint YAML’s repository. For example: /applications/acme_web_server/acme_web_server.yaml |
No |
| instances number | Numeric, >=1 | (Optional) If you want the application to be deployed on its own, specify the number of instances (one or more). | Yes |
| target | string | (Optional) Provide an alias for the instance on which you want the application to be deployed. Use the same alias for other applications that will share the same instance. | No |
| input name | string | (Optional) The name of the application input. | No |
| input value | string | (Optional) The value you wish to pass to the application input. It can be (a) a hardcoded value, (b) a value that comes from a blueprint input in the format ${input_name} or (c) an output of another application or service in the format $output.app_or_service_name.outputname. | Yes |
| depends_on: app or service name | string | (Optional) The name of the application(s) and/or service(s) this application depends on. This means that the deployment of this application will start only after all its dependencies have completed deployment and their healthcheck script has successfully run. | No |
Example:
applications:
- java-spring-website:
instances: 1
input_values:
- DB_USER: $DB_USER
- DB_PASS: $DB_PASS
- DB_NAME: $DB_NAME
- DB_HOSTNAME: $outputs.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. To learn more about adding Ingress rules to your sandbox environment, see Redirecting Traffic to Certain Sandbox Applications.
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}
| Field | Value | Description | Supports inputs? |
| service name | string |
(Mandatory) The name of the service. A service folder and YAML with this name should reside in the /services folder in the blueprint YAML’s repository. For the blueprint to be valid, for example, the space repository must contain at least the following structure: /services/rds_db/rds_db_service.yaml |
No |
| input name | string | (Optional) The name of the service input. | No |
| input value | string | (Optional) The value you wish to pass to the application input. It can be either (a) a hardcoded value, (b) a value that comes from a blueprint input in the format ${input_name} or (c) an output of another application or service in the format $output.app_or_service_name.outputname. | Yes |
|
depends_on: application or service names |
string | (Optional) The name of the application(s) and/or service(s) this service depends on. This means that the deployment of this service will start only after all its dependencies have completed deployment and their healthcheck script has successfully run. | No |
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).
| Field | Value | Description | Supports inputs? |
| application name | string | (Optional) The name of the application that requires an artifact. In order to use multiple artifacts in a single application, they should be compressed into a single file on the storage provider. | No |
| artifact path | string | (Mandatory) The artifact path, relative to the root of the artifact repository in the space. The artifact path is exposed as an input to the user who launches the blueprint. | Yes |
Example:
artifacts:
- demoapp-server: ' demoapp-server/production/demoapp-server.tar.gz'
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:
availability: {availability_mode}
| Field | Value | Description | Supports inputs? |
| availability_mode | on|off|disabled |
(Mandatory) Bastion's default state in the sandbox:
|
No |
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:
connectivity:
virtual_network:
id: {virtual network id}
subnets:
gateway:
- {subnet id}
management:
- {subnet id}
application:
- {subnet id}
- {subnet id}
| Field | Value | Description | Supports inputs? |
| virtual network id | string | (Mandatory)
AWS – VPC Id Azure – VNET name |
Yes |
| gateway: subnet id | string | (Mandatory) Only applies to Azure | Yes |
| management: subnet id | string | (Mandatory) | Yes |
| application: subnet id | string | (Mandatory) | Yes |
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'| Field | Value | Description | Supports inputs? |
| Stack name | string | (Optional)
AWS – VPC Id Azure – VNET name |
Yes |
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 Jenkins plugin when creating a sandbox from this blueprint.
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.
Comments
0 comments
Please sign in to leave a comment.