This documentation is for WSO2 Private PaaS 4.1.0. View documentation for the latest release.
Cartridge Resource Definition - WSO2 Private PaaS 4.1.0 - WSO2 Documentation
||
Skip to end of metadata
Go to start of metadata

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:

It is not required for you to define the name and value parameters under the property field in the cartridge definition, If you are running Private PaaS on the mock IaaS.

{
  "type": "wso2am-190",
  "category": "framework",
  "provider": "wso2",
  "host": "am.wso2.org",
  "displayName": "WSO2 AM 1.9.0",
  "description": "WSO2 AM 1.9.0 Cartridge",
  "version": "1.9.0",
  "multiTenant": true,
  "loadBalancingIPType": "public",
  "portMapping": [
    {
      "name": "mgt-https",
      "protocol": "https",
      "port": 9443,
      "proxyPort": 0,
      "kubernetesPortType": "NodePort"
    }
  ],
  "iaasProvider": [
    {
      "type": "mock",
      "imageId": "wso2/am:1.9.0",
      "networkInterfaces": [
        
      ]
    }
  ],
  "property": [
    
  ]
}

Define the values under the property field of the cartridge definition, if you are running Private PaaS on the EC2, Kubernetes or OpenStack IaaS

{
  "type": "wso2am-190",
  "category": "framework",
  "provider": "wso2",
  "host": "am.wso2.org",
  "displayName": "WSO2 AM 1.9.0",
  "description": "WSO2 AM 1.9.0 Cartridge",
  "version": "1.9.0",
  "multiTenant": true,
  "loadBalancingIPType": "public",
  "portMapping": [
    {
      "name": "mgt-https",
      "protocol": "https",
      "port": 9443,
      "proxyPort": 0,
      "kubernetesPortType": "NodePort"
    },
    {
      "name": "mgt-http",
      "protocol": "http",
      "port": 9763,
      "proxyPort": 0,
      "kubernetesPortType": "NodePort"
    },
    {
      "name": "pt-http",
      "protocol": "http",
      "port": 8280,
      "proxyPort": 0,
      "kubernetesPortType": "NodePort"
    },
    {
      "name": "pt-https",
      "protocol": "https",
      "port": 8243,
      "proxyPort": 0,
      "kubernetesPortType": "NodePort"
    }
  ],
  "iaasProvider": [
    {
      "type": "kubernetes",
      "imageId": "wso2/am:1.9.0",
      "networkInterfaces": [
        
      ]
    }
  ],
  "property": [
    {
      "name": "KUBERNETES_CONTAINER_CPU",
      "value": "0"
    },
    {
      "name": "KUBERNETES_CONTAINER_MEMORY",
      "value": "0"
    },
    {
      "name": "KUBERNETES_SERVICE_SESSION_AFFINITY",
      "value": "ClientIP"
    },
    {
      "name": "payload_parameter.START_CMD",
      "value": "PCA"
    },
    {
      "name": "payload_parameter.CONFIG_PARAM_PROFILE",
      "value": "Default"
    },
    {
      "name": "payload_parameter.CONFIG_PARAM_APIMGT_DB_URL",
      "value": "jdbc:mysql://192.168.30.7:3306/apim_db"
    },
    {
      "name": "payload_parameter.CONFIG_PARAM_DB_USER_NAME",
      "value": "root"
    },
    {
      "name": "payload_parameter.CONFIG_PARAM_DB_PASSWORD",
      "value": "root"
    },
    {
      "name": "payload_parameter.CONFIG_PARAM_LB_IP",
      "value": "127.0.0.1"
    }
  ]
}

Property definitions

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

  • W = Writable
  • R = Readable
  • U = Updatable
  • M = Mandatory (Required)
  • DV = Default Value

property definitions

PropertyWRUDescriptionMDVData
Type 
Example
JSONUI
typeType Type of the cartridge.YesN/AStringphp, 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.

YesN/A

String

framework, application, data, lb

provider

Provider Provider of the cartridge.YesN/A

String

apache, php.net, wso2

host

Host Domain where the cartridge will be hosted.YesN/A

String

stratos.org

displayName

Display Name The name in which the cartridge will be displayed.YesN/A

String

PHP

description

Description A short description about the cartridge.NoN/A

String

PHP Cartridge

version

Version The version of the cartridge application.YesN/A

String

7
loadBalancingIPTypeLoad 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.

  Stringpublic, private

multiTenant

Multi Tenant 

Whether the cartridge supports multi tenancy.

For more information, see Customizing Cartridges.

YesfalseBooleantrue/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.

YesN/AportMapping arrayN/A

deployment

- The deployment details need to be specified when working with Kubernetes. For more information on the sub-properties, see deployment.NoN/Adeployment 

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.

YesN/AiaasProvider arrayN/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.

NoN/ApersistenceN/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
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI
protocolProtocol The protocol that is used to map the portsYesN/AString

http

portPort The port to which the cartridge is mappedYesN/AInt80
proxyPortProxy Port The proxy port to which the cartridge is mappedYesN/AInt8280

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.

NoN/AStringNodePort

deployment
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI
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)NoN/AString/var/www

dir

-    dir array 

iaasProvider
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI
typeType Type of the IaaS providerYesN/AStringec2, mock, openstack, kubernetes

name

- Name of the IaaS provider.NoN/AString 

className

- Class name of the Iaas ProviderNo String 
imageIdImage ID The unique ID of the IaaS image.YesN/AString

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.

NoN/AnetworkInterfaces 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.

YesN/Aproperty arrayN/A

networkInterfaces
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI
networkUuid            
Network UUID The universal unique identifier (UUID) that corresponds to the network.  Stringba667f72-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
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI

name

- The name assigned to the floating network.NoN/AStringexternalThree

networkUuid

- The universal unique identifier (UUID) that corresponds to the floating network .NoN/AStringba667f72-7ba8-4b24-b360-b74a0211c83c

floatingIP

- The IP that corresponds to the floating network.NoN/AString192.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 NameRelevant IaaS   DescriptionDefault ValueExample Values
EOK
associatePublicIpAddressXXWhen using virtual private cloud (VPC) this property needs to be assigned to true, so that your cartridge instance will be assigned a public IP.truetrue, false
autoAssignIpXThis 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.truetrue, false
availabilityZoneX

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/Aap-southeast-1a
blockUntilRunningXX

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.

falsetrue, false
defaultFloatingIpPoolX XIf 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/APublicPool1

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:

IaaSValue Format
EC2N/A
OpenStack<REGION>/<ID>
N/A

EC2

m1.small

OpenStack

RegionOne/2

keyPairXThe name of the private key that corresponds to the key pair used to connect to the instance.N/Aapache-stratos-key1
securityGroupIds XWhen defining a security group in a VPC scenario, this property should be used instead of the securityGroups property.N/Asg-c999f7a6
securityGroupsXThe name of the security group that is used to define the IP filter rules for the instance.N/Asg-c999f7a6
shellTypeX X XThe 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/Abash, sh, cmd
subnetIdX XID used to identify the virtual private cloud (VPC). For more information, go to Amazon VPC.N/Asubnet-3b8a7d2g
tagX 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/Aa
tagsXXDefines the names of multiple tags. For example: <property name="tags" value="a,b,c,d" /> N/Aa,b,c,d
KUBERNETES_CONTAINER_CPUXX

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.

00, 0.3, 1, 300m
KUBERNETES_CONTAINER_MEMORYXXMemory 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.00, 40Mi
KUBERNETES_SERVICE_SESSION_AFFINITYXXDefines the session affinity that can be used with Kubernetes.NoneClientIP
IaaS specific payload parameter
Property NameRelevant IaaS   DescriptionExample Values
EOK
START_CMDXX PCA
Cartridge Payload Property Definitions 

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

General payload property definitions

Property NameClustered SetupStandalone
Setup 
DescriptionExample Values
ManagerWorker
COMMIT_ENABLEDYesNoNoThis 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_CLUSTERINGYesYesYesTo enable clustering in WSO2 products.true - for a clustered setup
false - for a standalone setup 
CONFIG_PARAM_LB_IP, LB_IP
YesYesNoDefines the Load Balancer IP which is fronted by the cartridge.127.0.0.1
CONFIG_PARAM_REGISTRY_DB_URL,
CONFIG_PARAM_REG_DB_URL 
YesYesNoURL of registry database.jdbc:mysql://172.17.8.1:3306/registry_44x
CONFIG_PARAM_REGISTRY_DB_USER_NAMEYesYesNoUsername of registry database.root
CONFIG_PARAM_REGISTRY_DB_PASSWORDYesYesNoPassword of registry database.root
CONFIG_PARAM_REGISTRY_DB_DRIVERYesYesNoDriver class name used in the data source.com.mysql.jdbc.Driver
CONFIG_PARAM_CONFIG_DB_URLYesYesNoURL of the config database.jdbc:mysql://172.17.8.1:3306/config_db_as_530
CONFIG_PARAM_CONFIG_DB_USER_NAMEYesYesNoUsername of the config database.root
CONFIG_PARAM_CONFIG_DB_PASSWORDYesYesNoPassword of the config database.root
CONFIG_PARAM_CONFIG_DB_DRIVERYesYesNoDriver class name used in the data source.
com.mysql.jdbc.Driver
CONFIG_PARAM_USER_MGT_DB_URL, CONFIG_PARAM_UM_DB_URL YesYesNoURL of the user management database.jdbc:mysql://172.17.8.1:3306/userstore_44x
CONFIG_PARAM_USER_MGT_DB_USER_NAMEYesYesNoUsername of the user management database.root
CONFIG_PARAM_USER_MGT_DB_PASSWORDYesYesNoPassword of the user management database.root
CONFIG_PARAM_USER_MGT_DB_DRIVERYesYesNoDriver class name used in the data source.com.mysql.jdbc.Driver
CONFIG_PARAM_PROFILEYesYesYes

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
NoNoYes

Membership scheme name used for cluster discovery.

private-paas, wka
CONFIG_PARAM_WORKER_HOST_NAMENoNoYes

Hostname of the worker node or default node.

as.wso2.com
APPLICATION_PATHNoNoYes

The application path that is used to clone the Git artifacts.

/var/www
CONFIG_PARAM_PORT_OFFSETYesYesYesThis 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 NameClustered
Setup
Standalone
Setup 
DescriptionExample Values
CONFIG_PARAM_APIMGT_DB_URLYesYesURL of the API_Mgt related database.jdbc:mysql://172.17.42.1:3306/apimgtdb
CONFIG_PARAM_APIMGT_DB_USER_NAMENoYesUsername of the API_Mgt database.root
CONFIG_PARAM_APIMGT_DB_PASSWORDNoYesPassword of the API_Mgt database.root
CONFIG_PARAM_KEYVALIDATORCLIENTTYPE
YesNoKey validator client type used in API Manager.WSClient
CONFIG_PARAM_DOMAINYesNoDomain name to be used in the deployment.wso2.pub.store.domain

 

DAS cartridge specific payload properties 

Property NameStandalone
Setup 
DescriptionExample Values
CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_URLYesURL 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_NAMEYesUsername of the WSO2_ANALYTICS_FS DB.root
CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_PASSWORDYesPassword of the WSO2_ANALYTICS_FS DB.root
CONFIG_PARAM_WSO2_ANALYTICS_WSO2_ANALYTICS_FS_DB_DRIVERYesDriver class name used in the data source.com.mysql.jdbc.Driver
CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_URLYesURL 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_NAMEYesUsername of the WSO2_ANALYTICS_EVENT_STORE DB.root
CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_PASSWORDYesPassword of the WSO2_ANALYTICS_EVENT_STORE DB.root
CONFIG_PARAM_WSO2_ANALYTICS_EVENT_STORE_DB_DRIVERYesDriver class name used in the data source.com.mysql.jdbc.Driver
CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_URLYesURL 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_NAMEYesUsername of the WSO2_ANALYTICS_PROCESSED_DATA_STORE DB. root
CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_PASSWORDYesPassword of the WSO2_ANALYTICS_PROCESSED_DATA_STORE DB. root
CONFIG_PARAM_WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB_DRIVERYesDriver class name used in the data sourcecom.mysql.jdbc.Driver

 

MB cartridge specific payload properties

Property NameStandalone
Setup 
DescriptionExample Values
CONFIG_PARAM_MB_METRICS_DB_URLYesURL of the MB_METRICS DB.jdbc:mysql://192.168.52.203:3306/MB_METRICS?autoReconnect=true
CONFIG_PARAM_MB_METRICS_DB_USERNAMEYesUsername of the MB_METRICS DB.root
CONFIG_PARAM_MB_METRICS_DB_PASSWORDYesPassword of the MB_METRICS DB.root
CONFIG_PARAM_MB_STORE_DB_URLYesURL of the MB_STORE DB.

jdbc:mysql://192.168.52.203:3306/MB_STORE?autoReconnect=true

CONFIG_PARAM_MB_STORE_DB_USER_NAMEYesUsername of the MB_STORE DB.root
CONFIG_PARAM_MB_STORE_DB_PASSWORDYesPassword of the MB_STORE DB.root
CONFIG_PARAM_MB_STORE_DB_DRIVERYesDriver class name used in the data source.com.mysql.jdbc.Driver

 

CEP cartridge specific payload properties

Property NameClustered
Setup
Standalone
Setup 
DescriptionExample Values
CONFIG_PARAM_PRESENTER_ENABLEYesNoEnable Presenter mode in CEP.true
CONFIG_PARAM_WORKER_ENABLEYesNoEnable 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
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI
isRequiredIs
Required
 Whether an extra volume is required is required to be attached to the cartridge to store contentNoN/ABooleantrue
volumes Volume Details of the persistence volume that should be attached to the cartridge. For more information on the sub-properties, see volumes. NoN/Avolumes arrayN/A

volumes
PropertyWRUDescriptionMDVData
Type 
Example
JSONUI

id

-    String 
deviceDevice Linux device of the volume that will be mounted to the mapping path.NoN/AString/dev/sdc
mappingPathMapping Path Folder path of the directory onto which the Linux device will be mounted.NoN/AString/home/ubuntu/sdc
sizeSize 

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.

YesN/AString11
removeOnTerminationRemove 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.

NoN/ABooleanfalse
snapshotId - The snapshot from which the volume was created, if applicable.  String 
volumeId
- The ID of the volume.  String 
  • No labels