This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Platform Application Workflows

The first part of this document outlines the steps involved in basic Platform application workflows (application creation, archive upload, promotion, deployment, undeployment, etc.). The second part lists developer and Platform Operator actions that trigger one or more of these workflows.

It should be noted that addition deployment details for each type of application component can be found in the How the Apprenda Platform Deploys Your Application section of the documentation.

Application Workflows

Application Creation

Each application on the Platform must have a unique developer-specified alias. Each version will also be assigned a unique GUID that will be used in some Platform DBs. Each application will also be assigned a unique GUID that will be used in some Platform DBs.

Steps:

  • Metadata is created in the SaaSGrid Core and Developer Portal DBs.
  • Version 1 (versionAlias=v1) is created.

Version Creation

An application may have multiple versions; each must have an alias that is unique in relation to the application’s other versions. Only one version may be published at any given time. Each version will also be assigned a unique GUID that will be used in some Platform DBs.

Steps:

  • Metadata is created in the SaaSGrid Core and Developer Portal DBs.
  • For a patched version: some metadata is copied from the parent version (such as custom properties and log overrides).

Archive Upload

An application is uploaded to the Platform as a specifically-structured ZIP file (an Application Archive). The structure determines the tiers (.NET UI, WCF service, Java Web Application, or database) to which each application component belongs. As needed, a DeploymentManifest.xml file may be included in the archive and may be used to configure a number of settings for the application.

Steps:

  • The Archive’s structure is parsed to extract the various component tiers of the application.
  • Binaries and configuration of each tier are analyzed to discover how the application components are related to one another.
  • Component information, along with any additional valid information included in a DeploymentManifest.xml file, is persisted as an entry for the application version in the DeploymentManifestDocument table in the SaaSGrid Core DB.
  • Additional metadata is recorded in the Developer Portal DB (such as application settings).
  • The Platform runs a series of rules to determine whether or not the application archive and its components are valid.
  • All files that make up your archive are copied to the Applications folder in the Platform Repository. The Platform Repository is a centralized location (typically configured during installation as a network path or share) that the Platform uses to manage both application and node file assets. 
    • For the initial version of your application, application binaries will be copied to Applications\tenantAlias\appAlias\versionAlias\base.
    • Binaries for all subsequent versions will be copied to Application\tenantAlias\appAlias\versionAlias\patch
    • During/after promotion: Patched versions may also include a base directory copied from the parent version if required by the type of patch that is performed (database patching, for instance, will result in a version with both a base and patch folder).

Promotion to Sandbox

An application version must be promoted to the Sandbox or Published stage before any of its components can be deployed. The Sandbox stage allows developers to test the application before it is made available to end users.

Steps:

  • Metadata for Individual components is created in the SaaSGrid Core DB (e.g., the Artifacts table, as well as a table for each component type).  Until this point, individual components exist only as binaries in the repository and information in the stored Deployment Manifest.  Component information is gathered by inspecting the binaries and Deployment Manifest.
  • Version stage and other relevant metadata is updated.
  • The Platform performs service staging for all WCF services (i.e., temporarily deploys then undeploys them).
  • If scaling settings have been configured for the version, the Platform will deploy component workloads to meet the settings. Otherwise, at promotion the Platform will configure components to use a Manual Scaling setting of "1" (except for any Windows Service components, which will be set to "0"); this will result in the deployment of a single instance of each .NET UI, WCF service and Java Web Application component.
  • For single-tenant applications, the development team that owns the application will be used as the application tenant; as needed, test subscriptions will be created and assigned to (authz) to person who hit promote
  • Dev team is onboarded as the application as a tenant. Test subscriptions will be created, and a subscription to the first plan listed in the entitlement definition will be assigned to the user that promoted the application.
  • If the application includes a database tier, the database will be created using the application provisioning script.
  • Generate commingled patch scripts if needed.

Demotion from Sandbox to Definition

An application version may be demoted to the Definition stage from the Sandbox stage only. Steps:

  • Version stage and other relevant metadata is updated.                
  • Workloads are undeployed.
  • Application databases are deleted.
  • Test subscriptions are deleted.
  • Component metadata is removed from the SaaSGrid Core DB.

Promotion from Sandbox to Published (v1)

Publishing an application version makes it available to end users. Steps:

  • Any Sandbox workloads are undeployed.
  • Sandbox application databases are deleted.
  • Test subscriptions are deleted.
  • Component metadata is removed from the SaaSGrid Core DB.
  • Version stage and other relevant metadata is updated.
  • Component metadata is recreated in the SaaSGrid Core DB.
  • If scaling settings have been configured for the version, the Platform will deploy component workloads to meet the settings. Otherwise, at promotion the Platform will configure components to use a Manual Scaling setting of "1" (except for any Windows Service components, which will be set to "0"); this will result in the deployment of a single instance of each .NET UI, WCF service and Java Web Application component.
  • For single-tenant applications, a “virtual” tenant is created for the application. No test subscriptions are created or assigned.
  • If the application includes a database tier, the database will be created using the application provisioning script (for commingled or single tenant apps; isolated multi-tenant apps will happen at onboarding).

Promotion from Sandbox to Published (patched versions)

Promoting a patched version of an application to the Published stage will automatically promote the previously published version (that the new version is displacing) to the Archive stage.

Steps for the formerly Published version (which is then promoted to the Archive stage):

  • Version stage and other relevant metadata is updated.
  • All workloads are undeployed.
  • Component metadata is removed from the SaaSGrid Core DB.
  • Most version metadata is deleted; exceptions (for recording purposes) include information in the Artifacts and DeployedArtifacts, Application, and Version tables in the SaaSGrid Core DB.

Steps for the version that is promoted from Sandbox to Published:

  • Any Sandbox workloads are undeployed.
  • Sandbox application databases are deleted.
  • Test subscriptions are deleted.
  • Component metadata is removed from the SaaSGrid Core DB.
  • Version stage and other relevant metadata is updated.
  • Component metadata is recreated in the SaaSGrid Core DB.
  • The Platform will prompt the developer to choose one of the following scaling options for the newly Published version:
    • inherit Scaling settings and component instance counts (number of workloads) from the previously Published version.
    • use Scaling settings and component instance counts (number of workloads) defined for the newly Published version.
  • Any subscriptions are migrated from the previously Published version to the newly Published version.
  • If the application includes a database tier, any database patch scripts will be applied.

Workload Deployment

When an application version is in the Sandbox or Published stage, its components may be deployed onto the various servers making up the Platform. The deployment process occurs in a matter of minutes, but the workflow that results in the safe and successful deployment of your application is quite complex.  For this workflow, the Platform performs the following:

  • Retrieves metadata from the SaaSGrid Core and Developer Portal DBs.
  • Confirms scaling settings will not be violated by deploying the workload.
  • A deployment target is selected (see the How Apprenda Chooses a Server for Workload Deployment section of our documentation).
  • Copies component binaries to a temp folder on a server that hosts the Apprenda Extensibility Services.
  • Executes any customer-defined Application Bootstrap Policies
  • Performs any token switching defined by the developer in the Deployment Manifest.
  • Copies the modified binaries to a temp folder in the Platform Repository.
  • Creates an entry in the Deployed Artifacts table in the SaaSGrid Core DB.
  • For workloads hosted on Windows servers:
    • Copies the modified binaries to the selected deployment target.

      • For WCF services, binaries will be copied to ApprendaPlatform\Container\Launchpads\{GUID unique to workload}
      • For .NET UIs for Published versions, binaries will be copied to
        ApprendaPlatform\SiteData\appAlias
      • For .NET UIs for Sandbox versions, binaries will be copied to
        ApprendaPlatform\SiteData\appAlias--versionAlias
         
    • Performs Platform-defined bootstrapping
    • Executes any config mods
    • Performs any Platform-defined token switching
    • For WCF services, will create the WCF service host process (which will register with ZooKeeper)
    • For .NET UIs: will create the website; the related process will not start until a request is made for the UI (i.e., if the application version is launched), at which point it will register with ZooKeeper.
    • For .NET UIs: Load Managers updated.
  • For Java workloads hosted on Linux:       
    • The windows container posts a deploy message to a ZooKeeper queue that the Linux container listens to; the Linux on the deployment target reads the queued message and initiates the deployment action
    • Copies the modified binaries to the selected deployment target /apprenda/instances/{GUID unique to workload}
    • Executes any Platform mods defined by the Platform Operator through a Bootstrap Policy
    • Performs Platform-defined bootstrapping
    • Performs any Platform-defined token switching
    • Merges in any included custom Tomcat configuration.
    • Starts the container (which will register with ZK)
    • The Linux Container then posts a message that the action was completed  to a Redis pub/sub channel that a few different .net components watch. One of those subscribers is the Windows Container that made the initial request, which is watching and waiting for the Linux Container to complete the action. 
    • Load Managers updated.

Workload Undeployment

Workloads are undeployed as part of various other Platform workflows such as application demotion, certain promotion scenarios, and version or application deletion.

  • The Platform confirms that the workload undeployment will not violate Scaling settings.
  • For .NET UIs and Java Web Application workloads, the Load Managers are updated.
  • For Java Web Application workloads, the Windows Container posts an undeploy message to a ZK queue that the Linux Container listens to; the Linux Container reads the queued message and performs the undeployment.
  • The workload targeted for undeployment is stopped (as part of this process it de-registers with ZooKeeper). If the workload cannot be stopped gracefully, the process is killed (and ZooKeeper will recognize when it is gone through what is effectively heatbeating).
  • Binaries are deleted from the runtime location.
  • For Java Web Application workloads, the Linux Container then posts a message that the action was completed  to a Redis pub/sub channel that a few different .net components watch. One of those subscribers is the Windows Container that made the initial request, which is watching and waiting for the Linux Container to complete the action. 
  • The workload’s entry in the DeployedArtifacts table is updated.

Workload Stop

Stopping a workload (not to be confused with Stopping an Application, which is documented in the Actions that Trigger Application Workflows section below) can be done  from the SOC only and entails the following:

  • Load Managers are updated (for .NET UI and Java Web Application workloads)
  • The process is stopped, but binaries are not removed from the node

Workload Start

Starting a workload (not to be confused with Starting an Application, which is documented in the Actions that Trigger Application Workflows section below) can be done  from the SOC only and entails the following:

  • The process is started using the existing binaries on the server.
  • Load Managers are updated (for .NET UI and Java Web Application workloads).

Version Deletion

Deleting a version will remove it from the Platform. If a version is Published or is the only version that has been created for an application, it can be deleted only by deleting the entire application.

  • Most version metadata is deleted; exceptions (for recording purposes) include information in the Artifacts and DeployedArtifacts, Application, and Version tables in the SaaSGrid Core DB.
  • All workloads are undeployed.
  • All application DBs deleted.
  • Repository folders are deleted.

Application Deletion

Deleting an application will remove it and all its versions from the Platform.

  • Most application and version metadata is deleted; exceptions (for recording purposes) include information in the Artifacts and DeployedArtifacts, Application, and Version tables in the SaaSGrid Core DB.
  • All workloads are undeployed.
  • All application DBs deleted.
  • Repository folders are deleted.

Actions that Trigger Application Workflows

Developer Portal Actions

Creating a New Application

  • Application creation
  • Archive upload

Promoting a Version through the Dashboard Tab

Depending on the stage the version is in, the Promote button will trigger one of the following:

  • Promotion from Definition to Sandbox
  • Promotion from Sandbox to Published (v1)
  • Promotion from Sandbox to Published (patched version)

Demoting a Version through the Dashboard Tab

The Demote button will appear only for an application version that is in the Sandbox stage; it will trigger the following:

  • Demotion from Sandbox to Definition

Patching in the Definition Stage

When a version is in the Definition stage, the Patch tab can be used to upload a new archive for the version (either to replace what was already uploaded or to remedy the situation if archive upload failed when the application or version was created). The developer may also specify a target stage for the version (Definition, Sandbox, or Published). The target stage selected will determine which workflows are triggered.

Target stage of Definition:

  • Archive upload

Target stage of Sandbox:

  • Archive upload
  • Promotion from Definition to Sandbox

Target stage of Published:

  • Archive upload
  • Promotion from Definition to Sandbox
  • Promotion from Sandbox to Published (v1 or patched versions as determined by the current version)

Patching in the Sandbox Stage

When a version is in the Sandbox stage, the Patch tab can be used to upload a new archive for the version (to replace what was already uploaded). The developer may also specify a target stage for the version (Definition, Sandbox, or Published). The target stage selected will determine which workflows are triggered.

Target stage of Definition:

  • Demotion from Sandbox to Definition
  • Archive upload

Target stage of Sandbox:

  • Demotion from Sandbox to Definition
  • Archive upload
  • Promotion from Definition to Sandbox

Target stage of Published:

  • Demotion from Sandbox to Definition
  • Archive upload
  • Promotion from Definition to Sandbox
  • Promotion from Sandbox to Published (v1 or patched versions as determined by the current version)

Patching in the Published Stage

When a version is in the Published stage, the Patch tab can be used to create a new version of the application and upload an archive for the new version (to upgrade the application to include new functionality or patch bugs). The developer may also specify a target stage for the version (Definition, Sandbox, or Published). The target stage selected will determine which workflows are triggered.

Target stage of Definition:

  • Version creation
  • Archive upload

Target stage of Sandbox:

  • Version creation
  • Archive upload
  • Promotion from Definition to Sandbox

Target stage of Published:

  • Version creation
  • Archive upload
  • Promotion from Definition to Sandbox
  • Promotion from Sandbox to Published (v1 or patched versions as determined by the current version)

Scaling

Different types of Scaling settings can be configured in the Scale tab for .NET UIs, WCF services, and Java Web Application workloads:

  • Manual: an instance count can be set; the Platform will maintain the a number of workloads for a component equal to the instance count specified. Configurable Platform settings determine how often the Platform will run a “sweep” to enforce this count.
  • Scheduled: instance counts can be set according to a weekly schedule.
  • Automatic (available if Resource Throttling is Enabled and the component is assigned a Resource Policy that limits CPU usage): a minimum and maximum instance count can be set; the Platform will scale the number of workloads deployed depending the aggregate CPU usage of all deployed workloads. The number of deployed instance will stay within the specified minimum and maximum instance counts.

As needed, the Platform will perform the following to meet Scaling setting requirements:

  • Workload deployment
  • Workload undeployment

It should be noted that when a workload is undeployed due to Scaling settings, the workload will be chosen at random.

Stopping/Starting an Application from the Dashboard Tab

Stopping an application in the Developer Portal will result in the following for all workloads (excluding DBs):

  • Workload undeployment

Starting an application in the Developer Portal will result in the following until the number of workloads for each component equals what was deployed when the application was stopped:

  • Workload deployment

Start/Stop Debug (Java only) in the Dashboard Tab

As needed a developer may use the Start Debug option, which will result in the following:

  • Workload undeployment for all Java Web Application workloads
  • Workload deployment of a single instance of the version’s Java Web Application component in debug mode. Connection information for the workload will be displayed in the Developer Portal so that the developer can hook into the instance with their debugger of choice.

The Stop Debug button will result in the following:

  • Workload undeployment for the single debug instance.
  • Workload deployment until the number of workloads for the Java Web Application component equals what was deployed when the application was put into debug mode.

Application-triggered Actions

When a .NET application is launched, the following may occur:

  • If the application contains a .NET UI and has not recently been used (so that the process for the workload is stopped), a request will be made to start the process.

System Operations Center Actions

Deploying a workload in the SOC

Platform Operators may deploy workloads in one of two ways.

  • Deploy without selecting a server: a workload will be deployed to a server determined by the Platform as outlined in the How Apprenda Chooses a Server for Workload Deployment section of the documentation.
  • Deploy to a selected server: a workload will be deployed to the targeted server.

Undeploying a Workload in the SOC

Platform Operators may undeploy a specific instance of a workload through the SOC, which will trigger the following:

  • Workload undeployment for the selected workload

Starting/Stopping a Workload in SOC

Platform Operators may stop a workload in the  SOC, which will result in the following workflow:

  • Workload stop for the selected workload.

Starting a stopped workload will result in the following workload:

  • Workload start for the selected workload.

Configuring Service Level Options

Different types of components have controls that allow Platform Operators to modify Service Level Options (such as setting an instance count). Depending on how Service Level Options are configured for a component, the Platform may, as a result, perform any of the following:

  • Workload deployment
  • Workload undeployment