In order to use an application in Colony Blueprints, you must first specify how to deploy and configure it.

The first step is to create a folder bearing the same name as the application you wish to create. This will be the location where you'll drop the scripts and YAML files which define that application.

Create a new file called [application_name].yaml and place it in the directory you've created.

For example, if your application is called acme_dashboard, you should now have the following structure in your source control:

/applications/acme_dashboard/acme_dashboard.yaml

The YAML file contains a few basic definitions about the application. In this section, we'll review the most basic ones needed in order to start the application:

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:
        aws:  ...
source:                 
  os_type: ...
  image:
    ami:
      - id: ...
        region: ...
        username: ...
    azure_image:
      - urn: ...
        username: ...
configuration:          
  initialization:
    script: ....sh
  start:
    script: ....sh
  healthcheck:
      wait_for_ports: ...
      timeout: ...

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.

Inputs

The inputs section is where you list the parameters required by your application. To learn all about working with parameters, receiving input from the blueprint and making parameters available for your application scripts, see Working with Parameters.

Infrastructure

The infrastructure section defines the default infrastructure requirements for the app.

infrastructure:         
  compute:              
    spec:
      azure:
        vm_size: Standard_A3
      aws: 
        instance_type: t2.medium
      kubernetes:
        cpu: 250m
        ram: 64Mi 
  connectivity:         
    external:
      - port_info:
          port: 5050 
    internal:
      - msdtc:
          port-range: 135, 1024-65353 
    permissions:          
    aws:
      iam_instance_profile:
        aws:  $iam_instance_profile

Compute: These are the compute specifications required by your application.

• For AWS, specify the EC2 Instance type.
• For Azure, specify the name of the required VM size. To find the required VM size name, use Azure's PowerShell to search for available VM sizes in the region you are using.
  In the following example, we listed all available image sizes in the West US region by running the following command in Azure Portal's Cloud Shell:

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

  A list of VM sizes in the West US region is displayed (the image includes a partial list):
  
  
  The size names appear under the Name column.
  For additional size search options, see Azure VM list -sizes.
• For Kubernetes, specify the cpu and ram limitations to impose on the application. These limitations are implemented in Kubernetes as both requests and limits. If you don't set these limitations, Kubernetes will manage the application's CPU and RAM. For details, see Requests and limits in this official Kubernetes help page.

Connectivity: these are the ports the app requires and that are required to interact with it. By default, ports can be assigned as external ports (available from outside the sandbox) or internal ports (available from inside the sandbox).

Colony supports port ranges for internal ports to easily define a range of ports that should be opened on the virtual machine. The port range is a list of port numbers and ranges separated by a comma. Multiple port ranges can overlap on the same instance via different applications. Ports defined in the port range element are not included in health checks and should be accessible to all instances inside the sandbox. Health checks run on the single port regardless of the port-range definition. Under a single port name element, Colony supports either a single port definition OR a single port-range definition. The port-range feature is not supported in a multi-node architecture.

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).

Source

OS_Type

source:
   os_type: linux

Specify the operating system. Enter either 'linux' or 'windows'.

Image

In your application YAML, you can use either an Azure marketplace image or a custom Azure image (but not both).

AWS AMI image

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

Specify the AMI-ID, the AWS region this image is applicable in and the username that will allow direct access to the VM. CloudShell Colony will automatically pick the image which matches the region the blueprint is being deployed to.

Azure marketplace image

source:
   os_type: linux
   image:
     azure_image:
       - urn: Canonical:UbuntuServer:16.04-LTS:latest
         username: adminuser

Specify the Azure image URN and the username that will allow direct access to the VM. In case you wish to use an image from Azure's marketplace, locate the required image URN by searching Azure's marketplace using Azure's PowerShell.
In the following example we searched for all virtual machines related to Drupal by running the following command in Azure's Cloud Shell:

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

The following list of available virtual machines was displayed:

The required URN number is specified in the URN column.
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.

Azure custom image

source:
   os_type: linux
   image:
     azure_image:
       - custom: colony-resourcegroup:test-image
         username: adminuser

To use a custom Azure image in CloudShell Colony, you must first create a custom image of an Azure VM with Azure PowerShell.

To add a custom Azure image:

1. Add the custom Azure image identifier in the following format: [resource group name]:[image_name]. In the example above, the custom identifier is colony-resourcegroup:test-image.
2. Enter a password that will be used for direct access to the VM.

Kubernetes docker image

source:
   image:
     docker_image:
       - name: my-k8s-image
         pull_secret: http://587541354594.dkr.ecr.eu-west-1.amazonaws.com/myregistrykey
         tag: v2.3.0

Specify the name of the docker image. By default, Colony will search for the image on Docker Hub. However, you can specify a private image repository using the pull_secret parameter where you define the path to the secret that contains the private repository's authentication credentials (in the format: <PrivateRepoUrl>/<ImageName>). For details, see this official Kubernetes help page.

And specify a tag if you want to use a specific image version.

Configuration

This section is where you reference scripts or commands to be used in configuring, launching and checking the health status of your application.

To learn more about running application scripts and commands in your application, see Application Scripts.