Cartridge Resource Definition

A cartridge is a container for a framework, load balancer or data management system. You can add a cartridge in a platform as a service (PaaS) for scalability. A sample cartridge definition, together with information on all the properties that can be added in a cartridge definition JSON are as follows:

Sample cartridge definition JSON

The following are sample configurations that can be used in a JSON to define a cartridge:

Property definitions

All the properties that correspond to the cartridge parameter resource are explained as follows:

type
provider
category
host
displayName
description
version
multiTenant
deployment
- baseDir
- dir
portMapping
- protocol
- port
- proxyPort
- kubernetesPortType
iaasProvider
- type
- name
- className
- imageId
- provider
- identity
- credential
- property
- networkInterfaces
  - networkUuid
  - fixedIp
  - portUuid
  - floatingNetworks
    - name
    - networkUuid
    - floatingIP
persistence
- isRequired
- volumes
  - id
  - size
  - device
  - removeOnTermination
  - mappingPath
  - snapshotId
  - volumeId
loadBalancingIPType
metadataKeys
property
- name
- value

W = Writable

R = Readable

U = Updatable

M = Mandatory (Required)

DV = Default Value

property definitions

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`type`	Type	√	√		Type of the cartridge.	Yes	N/A	String	php, tomcat
`category`	Category	√	√		Category that the cartridge belong to. The possible categorizes are as follows: data, lb and framework For more information, see Customizing Cartridges.	Yes	N/A	String	framework, application, data, lb
`provider`	Provider	√	√		Provider of the cartridge.	Yes	N/A	String	apache, php.net, wso2
`host`	Host	√	√		Domain where the cartridge will be hosted.	Yes	N/A	String	stratos.org
`displayName`	Display Name	√	√		The name in which the cartridge will be displayed.	Yes	N/A	String	PHP
`description`	Description	√	√		A short description about the cartridge.	No	N/A	String	PHP Cartridge
`version`	Version	√	√		The version of the cartridge application.	Yes	N/A	String	7
`loadBalancingIPType`	Load Balancing IP Type	√	√		Determines whether the members IP is private or public. If this property is set to 'private', the load balancer delegates requests to member's private IP address. If it is set to 'public', requests are delegated to the member's public IP address.			String	public, private
`multiTenant`	Multi Tenant	√	√		Whether the cartridge supports multi tenancy. For more information, see Customizing Cartridges.	Yes	false	Boolean	true/false
`portMapping`	Port Mapping	√	√		Details of the port mapped to the cartridge. For more information on the sub-properties, see portMapping. Add parameter definitions on multiple port mappings if required.	Yes	N/A	portMapping array	N/A
`deployment`	-	√	√		The deployment details need to be specified when working with Kubernetes. For more information on the sub-properties, see deployment.	No	N/A	deployment
`iaasProvider`	iaas Provider	√	√		Details of the IaaS provider that is used for the cartridge. For more information on the sub-properties, see iaasProvider. If required, add parameter definitions on multiple IaaS providers. These values will override the values in the cloud-controller.xml file, which is in the `<PRIVATE_PAAS_HOME>/repository/conf/` directory. Where `<PRIVATE_PAAS_HOME>` is the location of the unzipped PPaaS binary package.	Yes	N/A	iaasProvider array	N/A
`persistence`	Persistence		√	√	Details of the persistence volume that should be attached to the cartridge. For more information on the sub-properties, see persistence. For more information, see Customizing Cartridges.	No	N/A	persistence	N/A
`metadataKeys`		√	√		List down the meta data keys used by the cartridge.			String
`property`		√	√		Cartridge related properties are listed as name value pairs. Payload parameters and Iaas specific parameters can be defined as follows. `{"name":"payload_parameter.CONFIG_PARAM_CLUSTERING","value":"true"}, {"name":"KUBERNETES_CONTAINER_CPU","value":"0"}` Administrators can use this property parameter to define other dynamic parameters and their corresponding values that need to be set when an instance is spawned.			property array

Sub-property definitions

portMapping

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`protocol`	Protocol	√	√		The protocol that is used to map the ports	Yes	N/A	String	http
`port`	Port	√	√		The port to which the cartridge is mapped	Yes	N/A	Int	80
`proxyPort`	Proxy Port	√	√		The proxy port to which the cartridge is mapped	Yes	N/A	Int	8280
`kubernetesPortType`	Kubernetes Port Type	√	√		The Kubernetes port type to which the cartridge is mapped The following can be assigned for the Kubernetes port type: `NodePort` - If this value is used, it will create a service which can be accessed from the outside with port range of 30,000 to 32,767. `ClusterIP` - If this value is used, the service that gets created will not be exposed to the outside. This is useful if you don't want to expose a service to outside, but need to maintain internal communication within Docker containers. Access URLs are generated only for the NodePort service type.	No	N/A	String	NodePort

deployment

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`baseDir`	-	√	√		Base directory of the cartridge where artifacts should be deployed. The Cartridge Agent will deploy the artifacts that are checked out from the Git repository to this location. It is recommended to only set the base directory when working with Kubernetes, as it generally needs to be set in the Puppet Master configurations when working with VM scenarios (i.e., EC2, OpenStack)	No	N/A	String	/var/www
`dir`	-	√	√					dir array

iaasProvider

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`type`	Type	√	√		Type of the IaaS provider	Yes	N/A	String	ec2, mock, openstack, kubernetes
`name`	-	√	√		Name of the IaaS provider.	No	N/A	String
`className`	-	√	√		Class name of the Iaas Provider	No		String
`imageId`	Image ID	√	√		The unique ID of the IaaS image.	Yes	N/A	String	ap-southeast-1/ami-2e0d5a7c
`provider`	-	√	√		The name of the IaaS provider.			String
`identity`	-	√			Identity key of the Iaas Provider			String
`credential`	-	√			Secret key used of the Iaas Provider			String
`networkInterfaces`	Network Interfaces	√	√		The list of network configuration tuples attached when launching cartridges. The possible values for networkInterfaces tuples are as follows: OpenStack: `{"networkUuid","fixedIp","portUuid"}` AWS EC2: `{"networkUuid"}` For more information on how multiple network interfaces are used in PPaaS, see Multiple Network Interfaces. For more information on the sub-properties, see networkInterfaces.	No	N/A	networkInterfaces array	fb9c21f4-0672-48b2-8279-77334bb63a53
`property`	Property	√	√		The IaaS provider properties are listed as name value pairs. It is mandatory that IaaS provider definitions include the following property configurations: `{"name":"instanceType","value":"m1.medium"},{"name":"keyPair","value":"xxxxxx"}` Administrators can use this property parameter to define other dynamic parameters and their corresponding values that need to be set when an instance is spawned. For more information, see IaaS provider properties. For more information on the sub-properties, see property.	Yes	N/A	property array	N/A

networkInterfaces

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
networkUuid	Network UUID	√	√		The universal unique identifier (UUID) that corresponds to the network.			String	ba667f72-7ba8-4b24-b360-b74a0211c83c
fixedIp	-	√	√		The fixed IP that corresponds to the network.			String
portUuid	-	√			The universal unique identifier (UUID) that corresponds to the port.			String
`floatingNetworks`	-	√	√		For more information on the sub-properties, see floatingNetworks.	No		floatingNetworks array

floatingNetworks

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`name`	-	√	√		The name assigned to the floating network.	No	N/A	String	externalThree
`networkUuid`	-	√	√		The universal unique identifier (UUID) that corresponds to the floating network .	No	N/A	String	ba667f72-7ba8-4b24-b360-b74a0211c83c
`floatingIP`	-	√	√		The IP that corresponds to the floating network.	No	N/A	String	192.168.17.227

property

The IaaS provider properties will override the cartridge level properties that are defined in the <PRIVATE_PAAS_HOME>/repository/conf/cloud-controller.xml.

These abbreviations are used in the following table to specify the names of the IaaS:

E = EC2

O = OpenStack

Kub = Kubernetes

Property Name Relevant IaaS Description Default Value Example Values

E O K

associatePublicIpAddress √ X X When using virtual private cloud (VPC) this property needs to be assigned to true, so that your cartridge instance will be assigned a public IP. true true, false

autoAssignIp √ √ X This is used to determine whether your cartridge will be assigned a public IP or private IP. If this property, is true a public IP will be assigned to your cartridge. If this property is false the IP will be assigned manually. true true, false

availabilityZone

√

X

The name of the availability zone.

If you are using more than one partition, define the availability zone only in the cartridge definition and make sure not to define the availability zone in the cloud-controller.xml. This will enable the Autoscaler to dynamically select availability zone based on the partition.

N/A

ap-southeast-1a

blockUntilRunning

X

√

X

This will determine whether or not the instance spawning call to the IaaS will be blocked, in order to retrieve IP addresses. If you wish to auto assign IPs, the instance spawning call should be blocking, but if you wish to assign IPs manually, it can be non-blocking.

false

true, false

defaultFloatingIpPool X √ X If the floating IPs have not been pre-allocated for the respective tenant, when launching a cartridge, the floating IP allocation will fail. This property is used to specify the name of the floating IP pool that needs to be used. N/A PublicPool1

instanceType

√

X

The type of instance that determines the instance size, which needs to be used. In OpenStack this is referred to as flavor.

The instance type value needs to be specified differently based on the IaaS.
For example:

IaaS	Value Format
EC2	N/A
OpenStack	`<REGION>/<ID>`

N/A

EC2

m1.small

OpenStack

RegionOne/2

keyPair √ √ X The name of the private key that corresponds to the key pair used to connect to the instance. N/A apache-stratos-key1

securityGroupIds √ √ X When defining a security group in a VPC scenario, this property should be used instead of the securityGroups property. N/A sg-c999f7a6

securityGroups √ √ X The name of the security group that is used to define the IP filter rules for the instance. N/A sg-c999f7a6

shellType X X X The type of shell scripting language being used in the cartridge. This property is used to identify the correct customization script to use when passing the payload to the cartridge. N/A bash, sh, cmd

subnetId √ X X ID used to identify the virtual private cloud (VPC). For more information, go to Amazon VPC. N/A subnet-3b8a7d2g

tag

√

X

A tag is a name value pair used to filter instances. For more information, go to Using Tags.
For example: <property name="tag.a" value="x" />

N/A

a

tags √ X X Defines the names of multiple tags. For example: <property name="tags" value="a,b,c,d" /> N/A a,b,c,d

KUBERNETES_CONTAINER_CPU

X

√

Number of CPU cores used in a pod. With the value following suffices (E, P, T, G, M, K, m) or their power-of-two equivalents (Ei, Pi, Ti, Gi, Mi, Ki) can be used. If value is defined as zero, it will allow to use indefinite resources in the Kubernetes node. For more information, go to Kubernetes resource model.

0

0, 0.3, 1, 300m

KUBERNETES_CONTAINER_MEMORY X X √ Memory usage of the pod. With the value following suffices (E, P, T, G, M, K, m) or their power-of-two equivalents (Ei, Pi, Ti, Gi, Mi, Ki) can be used. If value is defined as zero, it will allow to use indefinite resources in the Kubernetes node. For more information, go to Kubernetes resource model. 0 0, 40Mi

KUBERNETES_SERVICE_SESSION_AFFINITY X X √ Defines the session affinity that can be used with Kubernetes. None ClientIP

IaaS specific payload parameter

Property Name	Relevant IaaS			Description	Example Values
Property Name	E	O	K	Description	Example Values
`START_CMD`	`X`	`X`	√		PCA

Cartridge Payload Property Definitions

The following are the definitions of the payload parameters passed the cartridge JSON:

General payload property definitions
AM specific payload properties
DAS cartridge specific payload properties
MB cartridge specific payload properties
CEP cartridge specific payload properties

General payload property definitions

Property Name	Clustered Setup		Standalone Setup	Description	Example Values
Property Name	Manager	Worker	Standalone Setup	Description	Example Values
`COMMIT_ENABLED`	Yes	No	No	This enables auto commit in Python Cartridge Agent (PCA). Once you define a Git repository when creating an application or when signing up, the PCA will commit the changes.	true - for a manager in a clustered setup false - for a standalone setup
`CONFIG_PARAM_CLUSTERING`	Yes	Yes	Yes	To enable clustering in WSO2 products.	true - for a clustered setup false - for a standalone setup
`CONFIG_PARAM_LB_IP, LB_IP`	Yes	Yes	No	Defines the Load Balancer IP which is fronted by the cartridge.	127.0.0.1
`CONFIG_PARAM_REGISTRY_DB_URL, CONFIG_PARAM_REG_DB_URL`	Yes	Yes	No	URL of registry database.	jdbc:mysql://172.17.8.1:3306/registry_44x
`CONFIG_PARAM_REGISTRY_DB_USER_NAME`	Yes	Yes	No	Username of registry database.	root
`CONFIG_PARAM_REGISTRY_DB_PASSWORD`	Yes	Yes	No	Password of registry database.	root
`CONFIG_PARAM_REGISTRY_DB_DRIVER`	Yes	Yes	No	Driver class name used in the data source.	com.mysql.jdbc.Driver
`CONFIG_PARAM_CONFIG_DB_URL`	Yes	Yes	No	URL of the config database.	jdbc:mysql://172.17.8.1:3306/config_db_as_530
`CONFIG_PARAM_CONFIG_DB_USER_NAME`	Yes	Yes	No	Username of the config database.	root
`CONFIG_PARAM_CONFIG_DB_PASSWORD`	Yes	Yes	No	Password of the config database.	root
`CONFIG_PARAM_CONFIG_DB_DRIVER`	Yes	Yes	No	Driver class name used in the data source.	com.mysql.jdbc.Driver
`CONFIG_PARAM_USER_MGT_DB_URL, CONFIG_PARAM_UM_DB_URL`	Yes	Yes	No	URL of the user management database.	jdbc:mysql://172.17.8.1:3306/userstore_44x
`CONFIG_PARAM_USER_MGT_DB_USER_NAME`	Yes	Yes	No	Username of the user management database.	root
`CONFIG_PARAM_USER_MGT_DB_PASSWORD`	Yes	Yes	No	Password of the user management database.	root
`CONFIG_PARAM_USER_MGT_DB_DRIVER`	Yes	Yes	No	Driver class name used in the data source.	com.mysql.jdbc.Driver
`CONFIG_PARAM_PROFILE`	Yes	Yes	Yes	Defines the profile name used in the WSO2 product. The configurations vary based on this profile name. This payload parameter is only common for the AM and DAS cartridges.	Gateway-Manager, Gateway-Worker, default
`CONFIG_PARAM_MEMBERSHIP_SCHEME`	No	No	Yes	Membership scheme name used for cluster discovery.	private-paas, wka
`CONFIG_PARAM_WORKER_HOST_NAME`	No	No	Yes	Hostname of the worker node or default node.	as.wso2.com
`APPLICATION_PATH`	No	No	Yes	The application path that is used to clone the Git artifacts.	/var/www
`CONFIG_PARAM_PORT_OFFSET`	Yes	Yes	Yes	This allows you to run multiple WSO2 products, multiple instances of a WSO2 product, or multiple WSO2 product clusters on the same server or virtual machine (VM). The port offset defines the number by which all ports defined in the runtime such as the HTTP/S ports will be offset. For example, if the HTTP port is defined as 9763 and the portOffset is 1, the effective HTTP port will be 9764. Therefore, for each additional WSO2 product, instance, or cluster you add to a server, set the port offset to a unique value (the default is 0).	1

AM specific payload properties

Property Name	Clustered Setup	Standalone Setup	Description	Example Values
`CONFIG_PARAM_APIMGT_DB_URL`	Yes	Yes	URL of the API_Mgt related database.	jdbc:mysql://172.17.42.1:3306/apimgtdb
`CONFIG_PARAM_APIMGT_DB_USER_NAME`	No	Yes	Username of the API_Mgt database.	root
`CONFIG_PARAM_APIMGT_DB_PASSWORD`	No	Yes	Password of the API_Mgt database.	root
`CONFIG_PARAM_KEYVALIDATORCLIENTTYPE`	Yes	No	Key validator client type used in API Manager.	WSClient
`CONFIG_PARAM_DOMAIN`	Yes	No	Domain name to be used in the deployment.	wso2.pub.store.domain

DAS cartridge specific payload properties

Property Name	Standalone Setup	Description	Example Values
`CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_URL`	Yes	URL of the `WSO2_ANALYTICS_FS` DB. This is used for the file system.	jdbc:mysql://192.168.52.203:3306/ANALYTICS_FS_DB?autoReconnect=true
`CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_USER_NAME`	Yes	Username of the `WSO2_ANALYTICS_FS` DB.	root
`CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_PASSWORD`	Yes	Password of the `WSO2_ANALYTICS_FS` DB.	root
`CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_DRIVER`	Yes	Driver class name used in the data source.	com.mysql.jdbc.Driver
`CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_URL`	Yes	URL of the `WSO2_ANALYTICS_EVENT_STORE` DB. This is used for event store.	jdbc:mysql://192.168.52.203:3306/ANALYTICS_EVENT_STORE?autoReconnect=true
`CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_USER_NAME`	Yes	Username of the `WSO2_ANALYTICS_EVENT_STORE` DB.	root
`CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_PASSWORD`	Yes	Password of the `WSO2_ANALYTICS_EVENT_STORE` DB.	root
`CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_DRIVER`	Yes	Driver class name used in the data source.	com.mysql.jdbc.Driver
`CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_URL`	Yes	URL of the `WSO2_ANALYTICS_PROCESSED_DATA_STORE` DB. This is used to manage processed data.	jdbc:mysql://192.168.52.203:3306/ANALYTICS_PROCESSED_DATA_STORE?autoReconnect=true
`CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_USER_NAME`	Yes	Username of the `WSO2_ANALYTICS_PROCESSED_DATA_STORE` DB.	root
`CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_PASSWORD`	Yes	Password of the `WSO2_ANALYTICS_PROCESSED_DATA_STORE` DB.	root
`CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_DRIVER`	Yes	Driver class name used in the data source	com.mysql.jdbc.Driver

MB cartridge specific payload properties

Property Name	Standalone Setup	Description	Example Values
`CONFIG_PARAM_MB_METRICS_DB_URL`	Yes	URL of the `MB_METRICS` DB.	jdbc:mysql://192.168.52.203:3306/MB_METRICS?autoReconnect=true
`CONFIG_PARAM_MB_METRICS_DB_USERNAME`	Yes	Username of the `MB_METRICS` DB.	root
`CONFIG_PARAM_MB_METRICS_DB_PASSWORD`	Yes	Password of the `MB_METRICS` DB.	root
`CONFIG_PARAM_MB_STORE_DB_URL`	Yes	URL of the `MB_STORE` DB.	jdbc:mysql://192.168.52.203:3306/MB_STORE?autoReconnect=true
`CONFIG_PARAM_MB_STORE_DB_USER_NAME`	Yes	Username of the `MB_STORE` DB.	root
`CONFIG_PARAM_MB_STORE_DB_PASSWORD`	Yes	Password of the `MB_STORE` DB.	root
`CONFIG_PARAM_MB_STORE_DB_DRIVER`	Yes	Driver class name used in the data source.	com.mysql.jdbc.Driver

CEP cartridge specific payload properties

Property Name	Clustered Setup	Standalone Setup	Description	Example Values
`CONFIG_PARAM_PRESENTER_ENABLE`	Yes	No	Enable Presenter mode in CEP.	true
`CONFIG_PARAM_WORKER_ENABLE`	Yes	No	Enable Worker mode in CEP.	true

There are not cartridge specific payload parameters for the following cartridges:

Application Server (AS)	Business Process Server (BPS)	Business Rules Server (BRS)
Governance Registry (GREG)	Identity Server (IS)

persistence

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`isRequired`	Is Required	√	√		Whether an extra volume is required is required to be attached to the cartridge to store content	No	N/A	Boolean	true
`volumes`	Volume	√	√		Details of the persistence volume that should be attached to the cartridge. For more information on the sub-properties, see volumes.	No	N/A	volumes array	N/A

volumes

Property		W	R	U	Description	M	DV	Data Type	Example
JSON	UI	W	R	U	Description	M	DV	Data Type	Example
`id`	-	√	√					String
`device`	Device	√	√		Linux device of the volume that will be mounted to the mapping path.	No	N/A	String	/dev/sdc
`mappingPath`	Mapping Path	√	√		Folder path of the directory onto which the Linux device will be mounted.	No	N/A	String	/home/ubuntu/sdc
`size`	Size	√	√		Capacity of the persistence volume that should be attached to the cartridge If you provide different value during subscription, the value provided here is overridden.	Yes	N/A	String	11
`removeOnTermination`	Remove on Termination	√	√		Whether the volume should be removed after termination of the instance If the value is set to false, the volume and its data will exist even after the instance is terminated, so that the data will not be deleted.	No	N/A	Boolean	false
`snapshotId`	-	√	√		The snapshot from which the volume was created, if applicable.			String
volumeId	-	√	√		The ID of the volume.			String