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:
          path: ''
          port: ....
    internal:
      - port_info:
          path: ''
          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
• Healthcheck script – either details for the default healthcheck or alternatively a custom healthcheck 

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: 135, 1024-65353 
    permissions:          
    aws:
      iam_instance_profile:  $iam_instance_profile

Compute

These are the compute specifications required by your application.

az vm list-sizes -l westus --output table

Connectivity

This section defines the ports for communication with the application and the ingress-healhcheck.

Ports

infrastructure:
  connectivity:
    internal:
    - port_info:
        port: 3000

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 help articles.

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. 

Permissions

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}

Source

OS_Type

source:
   os_type: linux

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

source:
   os_type: linux
   image:
     ami:
       - id: ami-0ba9283e196fbedb0
         region: eu-west-2
         username: ubuntu2

Azure image format

Colony supports 3 image formats: public images (urn), custom images (custom) and shared image gallery (gallery).

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"

az vm image list --offer Drupal --all --output table

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

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 supports an in-browser connection to the VM(s) on which the application is deployed. 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}

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:

1. Open the AWS console and navigate to the EC2 Dashboard.
2. From the left pane, select Target Groups.
3. Search for the sandbox environment's target groups using the colony-sandbox-id tag. 
   For example:
   
4. 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.

5. Click the target group's name and select the Targets tab.
   
6. 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:

1. Open the Azure Portal.
2. Search for the sandbox ID and click the environment's resource group.
   
3. Click the name of the "Application gateway" resource.
   
4. From the left pane, select Backend health.
   The environment's VMs are displayed, along with their status.
   
5. 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.