It is possible to add cloud services (also known as resources) that are not supported out-of-the-box by Colony to your environments. This is done using Terraform modules. All Terraform-supported services are added to the blueprint environment using dedicated service YAMLs. Simply create your blueprint with the required components and add a Terraform module.

NOTE: Terraform services are non-persistent. In other words, a dedicated service is deployed for every sandbox/production environment. As such, for persistent services, manage them outside of Colony.

This article first shows how to build the service YAML file, which points to the relevant Terraform module, and then demonstrates how to include it in a blueprint.

Just like blueprints and applications, infrastructure services in CloudShell Colony are source-controlled YAML files. So make sure to create the service YAML file in your GitHub or BitBucket repository’s /services folder. For details, see Setting up a Blueprints Repository.

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

# cloud service modeled with Terraform 
---
spec_version: 1 
kind: TerraForm                           
inputs:                                   
  - DB_NAME
  - DB_USER
  - DB_PASS
  - SANDBOX_ID
  - VPC_ID
  - role_arn: PowerUserAccess
module:                                   
  source: https://github.com/cloudshell-colony/terraform/tree/master/rds-mysql
terraform_version: 0.11.11                
variables:                                
  var_file: terraform.tfvars              
  values:                                 
    - db_name: $DB_NAME
    - username: $DB_USER
    - password: $DB_PASS
    - sandbox_id: $colony.environment.id
    - vpc_id: $VPC_ID
outputs:                                   
  - hostname    
permissions:                              
  aws:
    role_arn: $role_arn 

Basic Attributes

#service.yaml
---
spec_version: 1
kind: TerraForm

These are mandatory YAML attributes classifying this file as a Terraform service and specify which version of the spec you'll be using. Currently, Version 1 is the latest version available.

Terraform Module

module:
  source: github.com/cloudshell-colony/terraform/rds-mysql

Colony supports all sources that are available in Terraform. Review the official documentation here: https://www.terraform.io/docs/modules/sources.html.

We recommend you keep your Terraform module in GitHub or another source control repository and reference that in your source definition.

Terraform supports both private and public repositories. 

For private repositories, use the following syntax:

git::https://%USER%:%PWD%@github.com/%ORGANIZATION%/%REPOSITORY%.git//%PATH_TO_TERRAFORM_MODULE_FOLDER%

Where “%USER%:%PWD%” defines a Gihub user that can access the repository. Note that you can replace the user/password with a token, as explained in this official GitHub Help page.

For example:

module:
  source: git::https://john.l:*****@github.com/QualiNext/shay_playground.git//terraform/output

Resource Tags

"tags = {
  Name = "allow_tls",
  Type = "security",
  Owner = "james.b"
}

module:
  source: github.com/QualiNext/terraform/resources_creator
  exclude_from_tagging:
    - azure_resource_group_1
    - web_server_vm

Terraform Version

terraform_version: 0.11.11

Colony installs the specified Terraform version in your setup environment during provisioning and then runs your Terraform module [Colony service].  

Terraform Variables 

inputs:                             
  - SANDBOX_DNS
  - DNS_ZONE_NAME
  - SUBDOMAIN
  - IS_PRIVATE_ZONE: false
  - ROLE_ARN: PowerUserAccess

variables:
  var_file: terraform.tfvars

  values:
    - AWS_REGION: $REGION
    - DNS_ZONE_NAME: $DNS_ZONE_NAME
    - IS_PRIVATE_ZONE: $IS_PRIVATE_ZONE
    - SUBDOMAIN: $SUBDOMAIN
    - SANDBOX_DNS: $SANDBOX_DNS

There are 3 different ways to send values to the Terraform module variables:

1. Use a Terraform Variable Definition (.tfvars) file to hard-code your variables. Place your .tfvars file next to the service YAML in your blueprint repository and declare its name in the var_file service YAML element. If you're using this method, the values section in the service YAML is not needed.
2. Specify variable values by listing all Terraform variables and assigning them values. These values can be defined in the service YAML file or be referenced with standard Colony inputs using the $ sign.
3. Merge both options 1 and 2. Use the .tfvars file for some variables and declare other variables in the service YAML file.

Working Demonstration 

Our working example demonstrates CloudShell Colony's out-of-the-box sample AWS RDS with Java Spring Website blueprint which includes an RDS MySQL Terraform service. The blueprint deploys a Java Spring website on a Tomcat server and a MySQL database. The managed service, used by the blueprint, deploys a scalable MySQL server with Amazon's Relational Database Service (RDS) using Terraform. This blueprint sample is available in CloudShell Colony's Samples repository. A similar working Azure example blueprint is located here. The modeling of the blueprints are functionally the same.

Let's review the AWS RDS with Java Spring Website blueprint:

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

---
spec_version: 1
kind: blueprint
metadata:
  description: >
    A Java Spring website deployed on a Tomcat
    server and MySQL database

clouds:
  - AWS: eu-west-1

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.hostname
      depends_on:
        - rds-mysql

services:                                 
  - rds-mysql:  
      input_values:
        - DB_NAME: $DB_NAME
        - DB_USER: $DB_USER
        - DB_PASS: $DB_PASS
        - SANDBOX_ID: $colony.environment.id
        - VPC_ID: $colony.environment.virtual_network_id

As discussed above, the blueprint YAML file includes a section for ‘Services’ that lists all the cloud services that will be configured when using this blueprint.