Blueprints

Introduction

An application blueprint is a packaged tarball file (*.tar.gz) that contains the application manifest YAML file (jovianx.yaml) and the Helm Charts directories that are referenced by the application manifest. The application manifest defines the components used by the application. The components can be Helm Charts or other cloud-managed services. JovianX uses the Application Blueprint to create resources and set up services when a new account signs up.

Blueprint Structure

The application blueprint contains the following:

1. Application Manifest - The application manifest is a YAML file named jovianx.yaml. The manifest defines the components that are created for a new SaaS account. For example Kubernetes Helm Charts, DynamoDB, CloudDNS or other cloud managed services.

2. Helm Charts - The blueprint can also include the Helm Charts that are used for creation of application services.

Application Manifest(jovianx.yaml)

The application manifest is a YAML file that describes the application. JovianX uses the manifest to create the needed resources and services when a new account signs-up.

A basic template of an application manifest looks as following:

jovianx.yaml

# v1 - JovainX API Compatability
jovianx_api_version: v1

# string - Name of this SaaS application
application_name: '<APP-NAME>'

# semantic versioning - version of this JovianX blueprint 
version: <SEM-VERSION>

# string - Name of a component to be used a main application entry point 
main_endpoint_component: '<COMPONENT-NAME>'

# Components section defines all application components and their helm chart implementations
components:
  - name: '<COMPONENT-NAME>'
    version: <COMPONENT-SEMVER>
    provider: helm_chart
    helm_chart_name: <PATH/TO/HELM/CHART>
    helm_set:
      # List of key-value pairs to pass to helm on account creation
      - key: '<SET-KEY>'
        value: '<SET-VALUE>'
    endpoints:
      - name: '<ENTRYPOPINT-NAME>'
        type: entry_point
        service_name: '<KUBERNETS-SERVICE-NAME>'
        port: <KUBERNETES-SERVICE-PORT>
        path: '<KUBERNETES-SERVICE-PATH>'

# Settings Descripts define user inputs and 
settings_descriptors:
  # list of descriptos
  - name: <DESCRIPTOR-NAME>
    display: '<A QUESTION TO ASK THE USER ON SIGN-UP>'
    input_type: string
    default: '<DEFAULT ANSWER>'
    components:
      - name: '<COMPONENT-NAME>' # Provide value to this componet 
        helm_set:
          - key: '<SET-KEY>'

Creating Application Blueprint

To create an application blueprint archive the application manifest and helm charts into a blueprint tar.gz

$ tar -cf <BLUEPRINT-NAME> jovianx.yaml <HELM-CHART> ...

Note: The Helm Charts should be open, untar direcotry.

Example: the following directory has an application manifest jovianx.yaml and a Chart my-helm-chart

├── my-helm-chart
│   ├── charts
│   ├── templates
│   ├── Chart.yaml
│   └── values.yaml
└── jovianx.yaml

To create an application blueprint for the directory use the following command:

$ tar -cf blueprint-1.0.0.tar.gz jovianx.yaml my-helm-chart

Upload Application Blueprint

Upload Blueprint via Web UI

To upload your application blueprint to JovianX via the web console:

1. Navigate to Blueprints page

2. Click on Upload a new Blueprint bar

3. Click on Choose blueprint tar.gz file

4. Click on Upload to upload your blueprint

Once the blueprint is upload you will be able to find it in the blueprints list, and view the application manifest.

Upload Blueprint via CURL(CI)

To upload your application blueprint to JovianX via an automated CI process or from command line, you will need to find your API Access Key and API Secret. You can find both in Upload a new Blueprint bar under Blueprints navigation bar.

curl -u '<ACCOUNT-API-ACCESS-KEY>:<API-SECRET>' -F 'file=@<PATH/TO/BLUEPRINT/FILE.TAR.GZ>' 'https://<ACCOUNT-API-PATH>/api/v1/upload_blueprint?make_default=true'

Application Manifest (jovianx.yaml) Reference

Application Manifest Root

Key	Description
jovianx_api_version	Description: Version of the JovianX Manifest API. Parent: Root Type: v1 Required
application_name	Description: Name of the SaaS Application. Parent: Root Type: string Required
version	Description: Version of the JovianX blueprint. Parent: Root Type: semantic version Required
main_endpoint_component	Description: Main application end-point. Parent: Root Type: string Required
components	Description: components section is a list of all components(Helm Charts or Cloud Managed Services) used as part of the application, and their settings. Parent: Root Type: list Required
application_launch_timeout	Description: Application timeout configuration Parent: Root Type: collection Optional
status_check: failure_threshold:	Description: How many status error detection are accepted before changing the app status to error. Parent: Root Type: collection Default: 1 Optional
agents	Description: The list of agents Parent: Root Type: list Optional
settings_descriptors	Description: A list of settings descriptors Parent: Root Type: list Optional
hooks	Description: List of hooks Parent: Root Type: list Optional

Components

Components section is a list of all components used as part of the application, and their settings. Components are Helm Charts or Cloud Managed Services.

Key	Description
name	Description: Name of the component Parent: components Type: string Example: name: 'my-component' Required
version	Description: Version of the component Parent: components Type: semantic_version Example: version: 14.5.2 Required
provider	Description: Provider that implements the component Parent: components Type: Select Options: helm_chart [Additional providers available in private alpha] Example: provider: helm_chart Required
helm_chart_name	Description: Path to unarchived helm chart within the blueprint Parent: components Type: string Example: helm_chart_name: /my-helm-chart/ Required for helm_chart provider
helm_values_file	Description: Path to values.yaml file for the component Parent: components Type: string Example: helm_values_file: /my-helm-chart/my-values.yaml Optional for helm_chart provider
helm_set	Description: List of helm set key and value pairs Parent: components Type: list Example: helm_set: - key: image value: registry.hub.docker.com/my-company/image Optional for helm_chart provider

Settings Descriptors

Key	Description
name	Type: string
display	Type: string
input_type	value: string | number | radio | select
default	Type: string
description_title	Type: string
select_options	Type: list

Hooks

Key	Description
pre_install	Description: List hooks that are executed before app install Parent: hooks Type: list Optional
post_install	Description: List of hooks that are executed after app install Parent: hooks Type: list Optional

Hook

Key	Description
name
on_failure
timeout
provider
image
command
args
env

Variables

Account

{{ account://vendor_company }}

{{ account://end_company }}

{{ account://account_api_key }}

{{ account://admin_email }}

{{ account://admin_password }}

{{ account://api_host }}

{{ account://application_version}}

example

components:
  - name: node-component
    version: 1.0.0
    provider: helm_chart # helm_chart | docker
    helm_chart_name: node-chart
    helm_values_file: values-jovianx.yaml
    helm_set:
      - key: repository
        value: https://gitlab.com/jovianx-saas-platform/hello-world-app.git
      - key: replicas
        value: 1
      - key: vendor_company
        value: '{{ account://vendor_company }}'
      - key: end_company
        value: '{{ account://end_company }}'
      - key: account_api_key
        value: '{{ account://account_api_key }}'
      - key: admin_email
        value: '{{ account://admin_email }}'
      - key: admin_password
        value: '{{ account://admin_password }}'
      - key: api_host
        value: '{{ account://api_host }}'

Application