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

Colony supports both custom images and shared gallery images. There are several definitions you can use to specify your image. The custom definition specifies the image path in one line and supports both custom images and shared gallery images. You can also specify the image in multiple lines (one for each argument) using custom_image or gallery.

NOTE: subscription_id is optional. Omit this argument if you want Colony to use the Subcription ID of the cloud account.

Custom image examples:

- 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 examples:

NOTE: Colony supports specifying specific gallery image versions using the image_version argument. Omit this argument if you want to use the latest version.

- 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"

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

Kubernetes docker image

source:
   image:
     docker_image:
       - name: 513341655526.dkr.ecr.eu-west-1.amazonaws.com/myregistrykey
         pull_secret: my-namespace/my-secret
         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.