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
- colony_sandbox_id
- colony_blueprint_name
- colony_environment_id
- colony_space_id
- "terraform-resource" tag to indicate that the service was created from a Terraform module.
NOTES: Custom tags you defined in the environment's blueprint are not assigned to Terraform services.
"tags = {
Name = "allow_tls",
Type = "security",
Owner = "james.b"
}
- If an error occurs when creating the tags, a "tagging Terraform failed. Please contact Colony Support." error message is displayed in the sandbox's Summary tab. Please contact Colony Support for assistance.
- Colony does not support tags in this format "tag = {name = "allow_tls"}". If you must use a Terraform module containing resources that use these "tag" definitions, you will need to explicitly tell Colony NOT to tag those resource types. This is done in the service YAML, under module. For example, excluding resource types "azure_resource_group_1" and web_server_vm" from module "resource_creator":
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:
- 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.
- 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.
- 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.
Comments
1 comment
Very informative. Thanks!
Please sign in to leave a comment.