Application.json Specification

If you want to view the spec for a specific key, use the Table of Contents on the right 👉

This document defines the specification for application JSON implementation for Facets.Cloud.
For the actual schema, you can refer to the following GitHub pages:

To understand how a complete application specification looks like, check this JSON file in Github for Self-Hosting Kill Bill application.

Spec

The Application Schema has one native key, namely, loadbalancing and 4 sets of keys referenced from the Job Schema, namely, release, runtime, permission, and env.

Let's look at the values that can be used in each of these keywords, their description and usage.

KeyOptionalTypeDescription
loadbalancingNoObjectDefines whether this application is exposed to a load balancer (defined as ingress intent).
releaseNoObjectDefines the release/build related metadata of an application.
runtimeNoObjectAllows the user to manage runtime properties like command and sizing.
permissionNoArray[Object]Allows the user to manage permissions to other resources
envNoObjectAllows the user to manage environment variables.

Load Balancing

KeyOptionalTypeDescription
rulesNoArray[Object]Defines the list of rules for load balancing using the keywords ingress, path, and portName.

Rules

KeyOptionalTypeDescription
ingressNoStringDefines the ingress to which the rules will be added.
pathNoStringDefines the path in which this application is listening. e.g. /api/
portNameNoStringDefines the port where this request is directed.

Example

{ "loadbalancing": {
    "rules": [
     {
      "ingress": "appingress",
      "path": "/",
      "portName" : "port8080"
     }
    ]
   }
}

Release

KeyOptionalTypeDescription
strategyNoStringDefines the strategy to apply when releasing this application. This can take the following two values from an Enum, namely: RollingUpdate and Recreate.
buildYesObjectDefines the artifactory, name, and image for releasing this application.

Build

KeyOptionalTypeDescription
artifactoryYesStringName of the Artifactory registered in Facets Control Plane.
nameYesStringName of the Artifact registered in Facets Control Plane.
imageYesStringImage URL for the docker image. (Note that Facets CP should have access to this repository or it should be public).

Example

{"release": {
    "strategy": "RollingUpdate",
    "build": {
     "image": "exampleImage"
    }
   }
}

Runtime

KeyOptionalTypeDescription
commandYesArray[String]Defines the Command to run this container. This is required only if there is no CMD specified in your docker.
serviceNamesYesArray[String]Defines how other applications will discover this application. Note that the file name is a default service name and you should use this only if you need additional names for your service.
healthCheckYesObjectYou can use this argument to define health checks to determine health of an application. Note that if only a port is specified it will be a port check only.
autoscalingYesObjectDefines the rules for whether this application will auto scale.
sizeNoObjectDefines the size of the application as described in sizing json.
portsYesArray[Object]Defines the ports this application will listen to when running.

Health Check

KeyOptionalTypeDescription
startupTimeYesIntegerTime taken by this application to start and be ready. The health check will start after this duration.
timeoutYesIntegerTimeout duration if the end point does not respond.
periodYesIntegerInterval in which the check has to be repeated.
portNameNoStringName of the port on which healthcheck has to be done. Name as defined in ports section.
livenessUrlYesStringSpecifies the liveness URL.
readinessUrlYesStringSpecifies the readiness URL.
livenessExecCommandYesArrayDefines the command for the liveness URL.
readinessExecCommandYesArrayDefines the command for the readiness URL.

Auto Scaling

KeyOptionalTypeDescription
minNoIntegerMin replicas to run.
maxNoIntegerMax replicas to run.
cpuThresholdNoStringCPU threshold when to trigger autoscaling.

Size

KeyOptionalTypeDescription
namespaceYesStringSpecifies if there are multiple name spaces for sizing.
valueNoStringKey mentioned in Sizing.json

Ports

KeyOptionalTypeDescription
nameNoStringDefines unique name for this port.
portNoIntegerDefines the Port number.

Example

{ "runtime": {
    "size": {
     "value": "small",
     "namespace": "GP"
    },
    "autoscaling": {
     "cpuThreshold": "50",
     "max": 1,
     "min": 1
    },
    "ports": [{
     "name": "port8080",
     "port": 8080
    }]
}

Permission

KeyOptionalTypeDescription
nameYesStringDefines the Unique name to refer to this permission.
resourceTypeNoStringDefines which resourcetype/intent type this permission is used for. e.g. mysql/s3
resourceNameNoStringDefines which resource/intent this permission is used for.
permissionNoStringDefines the Canned ACLs.

Example

{"permission": [
      {
        "name": "app-permissions",
        "resourceType": "mysql",
        "resourceName": "app-db",
        "permission": "READ_WRITE"
      }
]}

Env

KeyOptionalTypeDescription
variableNameYesStaticVariable

DynamicVariable

VariableForCredentials
- Static Variable defines the variables which have a static value. You can override this per environment.

- Defines the variables which contain references to other resources created by Facets.

- Defines the variables which contain a reference to credentials of other resources created by Facets.

StaticVariable

KeyOptionalTypeDescription
typeNoStringDefines the static variable for this environment. It can take only the following value from an enum, namely, static
defaultNoStringDefines the default value for this variable.

DynamicVariable

KeyOptionalTypeDescription
typeNoStringDefines the dynamic variable for this environment. It can take only the following value from an enum, namely, dynamic.
resourceTypeNoStringDefines which resourcetype/intent type this permission is used for. e.g. mysql/s3
resourceNameNoStringDefines which resource/intent this permission is used for.
attributeNoStringDefines the attribute of the resource. e.g. bucket_name.

VariableForCredentials

KeyOptionalTypeDescription
typeNoStringDefines the credential variable. It can take only the following value from an enum, namely, credential
permissionNameNoStringDefines the reference to the permission block
attributeNoStringDefines which credential part to wire. e.g. Username/ Password

Example

{"env": {
      "APP_DAO_PASSWORD": {
        "type": "credential",
        "permissionName": "app-permissions",
        "attribute": "password"
      },
      "APP_DAO_URL": {
        "type": "static",
        "default": "jdbc:mysql://app-db:3306/app?usePipelineAuth=false&useBatchMultiSend=false"
      },
      "APP_DAO_USER": {
        "type": "credential",
        "permissionName": "app-permissions",
        "attribute": "userName"
      }
    }
}