The application YAML is a document that defines the application. It resides under a folder with the application name, under the /applications folder in the GitHub/BitBucket repository that is associated with the space. For details, see Setting up a Blueprints Repository.
For example, the application acme_dashboard would reside in:
/applications/acme_dashboard/acme_dashboard.yaml
In this article:
- Metadata
- Application Inputs and outputs
- Infrastructure
- Source
- Configuration
- Debugging
- Verifying ingress-healthcheck parameters on AWS/Azure
TIP: For more information about each sequence or key value pair, click the icon next to it.
--- spec_version: 1
kind: application inputs:
- ...: '' - ...: '' infrastructure:
compute:
spec: azure: vm_size: ... aws: instance_type: ... connectivity:
external: - port_info: port: .... internal: - port_info: port: .... permissions:
aws: iam_instance_profile: ... source:
os_type: ... image: ami: - id: ... region: ... username: ... azure_image: - urn: ... username: ... configuration:
initialization: script: ....sh start: script: ....sh healthcheck: wait_for_ports: ... timeout: ...
The Application YAML consists of multiple sections, which are detailed below. The minimal configurations that the application YAML needs to include in order to be functional are:
- Basic metadata attributes
- At least one image source, including the OS type for the application's VM
Metadata
---
spec_version: 1
kind: application
kind/ spec_version: These are mandatory YAML attributes classifying this file as an application and specifying which version of the spec you'll be using. Currently, version 1 is the latest version available.
Application Inputs and outputs
The inputs section is where you list the parameters required by your application. In addition, you can also use outputs from your application scripts as inputs in the environment's other applications and services. For details, see Working with Parameters.
Infrastructure
In this section you define the infrastructure on which the application will run on. You can choose the compute, define ports to open for external or internal communication and configure custom permissions. The exact compute specifications are different per cloud provider. The whole infrastructure section is optional, and if not defined defaults will be used.
IMPORTANT: The application YAML is cloud-agnostic and can include definitions for different cloud providers as well as multiple AWS regions. Ultimately, the blueprint yaml determines which cloud provider will be used in the sandbox.
infrastructure:
compute:
spec:
azure:
vm_size: Standard_A3
aws:
instance_type: t2.medium
kubernetes:
cpu: 250m
ram: 64Mi
connectivity:
internal:
- port_info:
port-range: 135, 1024-65353
permissions:
aws:
iam_instance_profile: $iam_instance_profile
Compute
These are the compute specifications required by your application.
Field | Value | Description | Supports inputs? |
vm_size | The name of a Vm size on Azure, e.g. Standard_D2_v3 |
(Mandatory for Azure) Azure VM size. Use Azure's PowerShell to search for available VM sizes in the region you are using. For example: all available image sizes in the West US region by running the following command in Azure Portal's Cloud Shell:
A list of VM sizes in the West US region is displayed (the image includes a partial list): For additional size search options, see Azure VM list -sizes. |
Yes |
instance_type | The name of an AWS instance type, e.g. c5.large, can also contain CSV of types to pick the first available one | (Mandatory for AWS) EC2 instance type. | Yes |
cpu |
Same format as Kubernetes. For details, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes |
(Mandatory for Kubernetes) CPU limitation for Kubernetes VM. This limitation is implemented in Kubernetes both as a request and a limit. If you don't set this limitation, Kubernetes will manage the application's CPU. For details, see Requests and limits in this official Kubernetes help page. |
Yes |
ram |
Same format as Kubernetes. For details, see |
(Mandatory for Kubernetes) RAM limitation for Kubernetes VM. This limitation is implemented in Kubernetes both as a request and a limit. If you don't set this limitation, Kubernetes will manage the application's RAM. For details, see Requests and limits in this official Kubernetes help page. |
Yes |
Connectivity
This section defines the ports for communication with the application and the ingress-healhcheck.
Ports
Use port for single port:
infrastructure:
connectivity:
internal:
- port_info:
port: 3000
Or port-range for range of ports:
infrastructure:
connectivity:
internal:
- port_info:
port-range: 135,1024-65353
ingress-healthcheck
The ingress-healthcheck is provided out of the box with Colony and verifies that the applications that are supposed to be accessible from outside the environment are indeed accessible. As such, it only operates on external application ports (those defined in the ingress section of the blueprint YAML). For this purpose, the ingress-healthcheck uses the AWS application load balancer or Azure application gateway to run these checks and therefore cannot finish before the ALB or AG is up and running in the environment. When this check passes, the environment will transition to an Active state. For a detailed explanation about each health check setting, see Amazon's Health Checks for Your Target Groups and Microsoft's Health Probes documentation.
infrastructure:
connectivity:
internal:
- port_info:
port: 3000
ingress-healthcheck:
healthy-threshold: 5
interval: 30
path: /
status-codes: 200-299
timeout: 5
unhealthy-threshold: 2
The above ingress-healthcheck section displays the default settings. These determine that the application is accessible on port 3000 and that it should be considered healthy if it returns a status code of 2XX from the root of its API (as defined in the ‘path’ element). This is a very common example but in some cases applications will return (for example) 404 from the root path and only return a valid status code from a more specific path (e.g. /API/Health). For additional information, see the Verifying ingress-healthcheck parameters on AWS/Azure section at the bottom of this article.
Field | Value | Description | Supports inputs? |
healthy-threshold | numeric | Number of consecutive checks that need to pass before considering the instance of the application healthy. | No |
interval | numeric | Polling interval, in seconds. | No |
path | string |
Path of the URL to use for the test. In other words, /api/health means the load balancer will access this path in the URL and compare the status code it gets in the response with the status codes that appear in the status-codes element to determine if this is a healthy or unhealthy response. |
No |
status-codes | string | Accepted http responses. | No |
timeout | numeric | the amount of time in seconds to wait for a respond before considering it unhealthy | No |
unhealthy-threshold | numeric | Number of consecutive checks that need to fail before considering the instance of the application unhealthy | No |
Here you specify permissions to your infrastructure instances to perform actions using the cloud provider's services. In the case of AWS for example, you can assign your EC2 machine with an IAM role to be used by your application when accessing any AWS service (such as S3 bucket).
AWS:
infrastructure:
permissions:
aws:
iam_instance_profile: {iam_instance_profile_name}
Azure:
infrastructure:
permissions:
azure:
{managed_identity_id}: {managed_identity}
Field | Value | Description | Supports inputs? |
managed_identity_id | {resource_group_name/identity_name} | (Mandatory User-assigned managed identity. | Yes |
iam_instance profile | string | (Mandatory) Name of the EC2 instance profile (not the full ARN). | Yes |
Source
OS_Type
source:
os_type: linux
Field | Value | Description | Supports inputs? |
os_type | linux|windows | Operating system for the application's VM. | No |
Image
The application's images are defined in the source section of the application YAML.
The application YAML is image-agnostic, so you can define one or more images for the application. You can define an image per cloud provider. In AWS, you can possibly define an image in each relevant region. When the application is added to a blueprint, the image is selected according to the cloud account and region defined in the blueprint. This allows your application to be used in multiple blueprints, across regions and cloud providers.
source:
os_type: linux
AWS AMI image format
Colony supports 2 AMI image formats: marketplace and custom. Custom images can be private or public.
source:
os_type: linux
image:
ami:
- id: ami-0ba9283e196fbedb0
region: eu-west-2
username: ubuntu2
Field | Value | Description | Supports inputs? |
ami-id |
ID of an AMI, e.g. ami-007607e9a8435f3bc |
(Mandatory) AMI image to be used. | No |
region |
Id of an AWS region e.g. eu-west-1 / |
(Mandatory) AWS region ID. For example, us-east-1. Note that you can define only one image source per region |
No |
username |
Any valid username string for the OS of the requested image |
(Optional) Username to set on the application's instance, to allow direct access to the instance. For SSH/RDP connection to the instance, make sure the username is defined both in the AMI image and application YAML. Password is not needed. |
No |
Azure image format
Colony supports 3 image types: public images (urn), custom images (custom) and shared image gallery (gallery). These can be written in two formats, as a concatenated string using the custom key or as a dictionary with key-value pairs.
Public image:
source:
os_type: linux
image:
azure_image:
- urn: Canonical:UbuntuServer:16.04-LTS:latest
username: adminuser
Custom image:
- custom: "/subscriptions/24tfe408-4612-497c-b81e-7ec6g784f9db/resourceGroups/my-resource-group/providers/Microsoft.Compute/images/my-custom-image"
or:
source:
image:
azure_image:
- custom_image:
subscription_id: "24tfe408-4612-497c-b81e-7ec6g784f9db"
resource_group: "my-resource-group"
image: "my-custom-image"
Shared gallery image:
- custom: "/subscriptions/24tfe408-4612-497c-b81e-7ec6g784f9db/resourceGroups/my-resource-group/providers/Microsoft.Compute/galleries/my_image_gallery/images/my-custom-gallery-image/versions/1.0.0"
or:
source:
image:
azure_image:
- gallery:
subscription_id: "24tfe408-4612-497c-b81e-7ec6g784f9db"
resource_group: "my-resource-group"
shared_image_gallery: "my_image_gallery"
image_definition: "my-custom-gallery-image"
image_version: "1.0.0"
Field | Value | Description | Supports inputs? |
publisher | string | (Mandatory) Publisher name. | No |
offer | string | (Mandatory) Offer name. | No |
sku | string | (Mandatory) SKU id. | No |
urn | string |
(Optional) Version number (or "latest"). Omit this argument to use the latest version. To use an image from Azure's marketplace, you can locate the image URN by searching Azure's marketplace using Azure's PowerShell. For example, searching for all virtual machines related to Drupal by running the following command in Azure's Cloud Shell:
The following list of available virtual machines was displayed: For more information about finding Windows VM images in the Azure Marketplace, see Find Windows VM images in the Azure Marketplace with Azure PowerShell. NOTE: Some publishers have unique legal terms and privacy requirements. When using a third-party publisher image for the first time, make sure to first install the image directly from your cloud provider's management UI and accept all required legal terms and privacy statements. Once all legal terms are accepted, you can proceed to use the image in CloudShell Colony. |
No |
username | string |
(Optional) Username to set on the application's VM, to allow SSH/RDP access to the VM. In Azure, if the user doesn’t exist on the VM, Colony will create the VM with a default user. No need to specify a password as Colony generates it automatically. |
Yes |
subscription_id | the ID of the subscription to deploy to in the Azure account | (Optional) Azure subscription id. Omit this argument if you want Colony to use the Subcription ID of the cloud account. | Yes |
resource_group | string | (Mandatory) Resource group name. | Yes |
image | string |
(Mandatory) Image name. To use a custom Azure image in CloudShell Colony, you must first create a custom image of an Azure VM with Azure PowerShell. |
Yes |
shared_image_gallery | string | (Mandatory) Shared image gallery name. | Yes |
image_definition | string | (Mandatory) The name of the image in the gallery. | Yes |
image_version | string | (Optional) The version number of the gallery image (or "latest". Omit this argument to use the latest version. | Yes |
Kubernetes docker image format
source:
image:
docker_image:
- name: 513341655526.dkr.ecr.eu-west-1.amazonaws.com/myregistrykey
pull_secret: my-secret
tag: v2.3.0
username: ubuntu
Field | Description | Supports inputs? |
name | (Mandatory) Name of the docker image. By default, Colony will search for the image on Docker Hub. | No |
pull_secret |
(Optional) Name of the secret. Used to specify a private image repository. The secret must exist in the same namespace as the sandbox to be deployed (the namespace defined in the current space's Kubernetes cluster). For details, see this official Kubernetes help page. |
Yes |
tag | Tag defining image version to use. | No |
username | (Optional) Username to set on the application's VM, to allow direct access to the VM. |
Configuration
This section is where you reference scripts or commands to be used in configuring, launching and checking the health status of your application. For details, see Application Scripts.
Debugging
To allow debugging of your application, Colony provides the option to connect to the VM(s) on which the application is deployed.
There are two connection methods:
- Bastion is a component that is deployed in the sandbox environment and provides a more secure connection, but it also incurs a cost as it is deployed on a dedicated virtual machine.
- Direct access provides connections via an RDP/SSH client file
Configuring this option is done in the blueprint and application YAMLs. The blueprint YAML defines the connection method to use and the application YAML is where you define the connection protocol. For additional information about each option, see The Blueprint YAML File - Debugging.
Bastion
To enable these access links, add the debugging section to your application YAML and define the protocol(s) that will be used for the connection.
debugging:
connection_protocol: {protocol}
Field | Values | Description | Supports inputs? |
protocol |
RDP | SSH | RDP,SSH |
(Optional) Protocol for in-browser connection to VM. | No |
Direct access
To enable direct access connections to the application, add the following section:
debugging:
allow_direct_access: true
connection_protocol: SSH
Field | Values | Description | Supports inputs? |
allow_direct_access |
true false (default) |
Enables direct_access connections to the VM via an RDP or SSH client. | No |
protocol |
RDP | SSH | RDP,SSH |
(Optional) Protocol for in-browser connection to VM. | No |
Verifying ingress-healthcheck parameters on AWS/Azure
This section is related to the infrastructure section's ingress-healthcheck above.
It is possible that the parameters are already defined correctly in your application YAML. However, since the change is not yet applied to the system, the sandbox may currently remain healthy even if the settings are wrong. In this situation, you cannot tell within Colony whether a correction is required. Therefore, when developing the application YAML, we recommend to verify the settings on AWS/Azure.
If you choose to skip this verification step, there is a chance environments created from your blueprint will stop reaching the ‘active’ state and will instead move to ‘Active with error’ or remain ‘launching’ once the change is in. When this occurs, you will need to start modifying the values until they are correct and the environment is active.
Before you start, copy the sandbox ID from the sandbox environment's URL in Colony. For example:
To verify ingress-healtcheck settings in AWS:
- Open the AWS console and navigate to the EC2 Dashboard.
- From the left pane, select Target Groups.
- Search for the sandbox environment's target groups using the colony-sandbox-id tag.
For example: - Locate the target group that has a load balancer.
If your blueprint contains several externally exposed applications or exposed ports you will have multiple target groups and will need to run the following checks for each relevant target group.
- Click the target group's name and select the Targets tab.
- Click the Clear filters button.
The target group's instances are displayed, along with their status.
Look for targets that have an unhealthy status. This means that the ingress-healthcheck in the application is configured incorrectly.
In this particular case, the default healthcheck path "/" returns the 302 (redirect) http response code while http response code 200 is expected (see the status-codes parameter in the ingress-healthcheck code example here).
To correct this, you can modify the application YAML path to one that does return 200 when accessed or change the expected status code for the defined path to the one being returned. Another option is to change the behavior of you application to return a different status code for the path.
To verify ingress-healthcheck settings in Azure:
- Open the Azure Portal.
- Search for the sandbox ID and click the environment's resource group.
- Click the name of the "Application gateway" resource.
- From the left pane, select Backend health.
The environment's VMs are displayed, along with their status. - Check the health status of the backend pool, it should appear as above.
If the status is unhealthy, use the information in the ‘details’ field to understand the gap between what the application returned and what the ingress-healthcheck set the application gateway to expect.
For example:
In the above image, the application returned status 302, which is not the expected http response. To correct this, you can modify the application YAML path to one that does return 200 when accessed or change the expected status code for the defined path to the one being returned. Another option is to change the behavior of you application to return a different status code for the path.
Comments
0 comments
Please sign in to leave a comment.