Understanding Application Configuration YAML File

In TIBCO ActiveMatrix Service Grid, applications are configured from the Administrator UI and all configurations are stored in the Administrator database. ActiveMatrix Service Grid - Container Edition does not have the Administrator database. All configurations are stored in the configuration file.

To create the Docker image of an application, this configuration file is required. The configuration file has a higher priority compared with DAA when creating the Docker image of an application, which means the configuration file overrides the configuration in DAA.

The application configuration file is a text file in YAML format and has the following sections:

Application Basic Information

configVersion: 1.0.0
name: com.tibco.restbt.sample.bookstore
daaName: com.tibco.restbt.sample.bookstore.daa
appTemplate: com.tibco.restbt.sample.bookstore
appTemplateVersion: 1.0.0.v2018-11-06-1349
description: Add description here
environment: AMXCEEnvironment
node: AMXCENode

Here:

• configVersion (optional): Configuration file version. It is 1.0.0 by default.
• name (required): Application name
• daaName (optional): DAA name which is used to create the YAML configuration and Docker image.
• appTemplate (required): Application template name
• appTemplateVersion (optional): Application template version
• description (optional): Description of an application
• environment (optional): Environment name. The default value is AMXCEEnvironment.
• node (optional): Node name. The default value is AMXCENode.

Properties

All properties listed are editable. The properties include application-level properties and resources that are required by binding, and resources that are required by policy. Property can only be updated and cannot be added or removed.

properties:
- name: '[Service]BookStoreResource/RESTService_Binding1/httpConnectorName'
  type: String
  value: httpConnector_bookstore

Properties display a prefix indicating the context as follows:

• Application level properties are displayed with the prefix [Application].
• Binding level properties are displayed with the prefix [Service] or [Reference].
  • The format of the reference binding property name is [Reference]REFERENCE_NAME/REFERENCE_BINDING_NAME/PROPERTY_NAME.
  • The format of service binding property is [Service]SERVICE_NAME/SERVICE_BINDING_NAME/PROPERTY_NAME.

• Properties for certain policy sets such as threading policy display with the preceding prefix [Policy].

  Example: [Policy]POLICY_NAME/PROPERTY_NAME.

Substitution Variables

All substitution variables function at the application level. They are used to resolve substitution variables that are used in the application. Substitution variables can be added, updated, or removed.

Substitution variables types are: String, Integer, Boolean, and Password.

For example, the following substitution variable clientport is of type String with a value of 9000. The operation ADD means this substitution variable is not in DAA and it is added to the application from the YAML file.

- name: clientport
  operation: ADD
  type: String 
  value: ‘9000’

The httpClientPort substitution variable has only the operation attribute with value REMOVE, which means this substitution variable has been defined in DAA, but it is not needed during application deployment and is removed by using the configuration file.

-name: httpClientPort 
operation: REMOVE

Services

Service name and the Service interface (contract) cannot be updated. Bindings are editable. Service describes a "contract" between providers and consumers, therefore it is not editable at deployment time and bindings describe how the communication happens, therefore Service bindings can be updated, added, or removed. Service has three types of bindings: JMS binding, SOAP binding, and REST binding. There are three sections under services: jmsBindings, soapBindings, and restBindings. Each binding is listed in its respective section based on its type.

services:
- name: BookStoreResource
  restBindings:
  - name: RESTService_Binding1
    applicationPath: /bookstore
    interfaceName: '{http://ns.tibco.com/BookStoreResource/}BookStoreResource'
    restServiceOperationConfiguration:
    - httpMethod: GET
      mediaType: STANDARD_JSON
      operationName: getBookList
      path: /books
    - httpMethod: GET
      mediaType: STANDARD_JSON
      operationName: getBookByTitle
      path: /book/{title}
    - httpMethod: POST
      mediaType: STANDARD_JSON
      operationName: addBook
      path: /addbook
    - httpMethod: GET
      mediaType: STANDARD_JSON
      operationName: getBookByTitleCategory
      path: /book/{title}/{category}
    restTransportConfigDesc:
      httpConnectorJNDIName: httpConnector_bookstore
    skipJsonRespNamespace: false

References

Reference name cannot be updated. Reference bindings can be updated, added, or removed. Reference describes a "contract" between providers and consumers, therefore it is not editable at deployment time and bindings describe how the communication happens, therefore bindings can be updated, added, or removed. Only SOAP reference binding is supported for editing in ActiveMatrix Service Grid - Container Edition. Because reference has only one binding, there is only one section under each reference based on the binding type.

references:
- name:NewReference 
  soapBindings:
  - name:SOAPReference_Binding1
    operation: REMOVE 
  - name:SoapBinding
    operation: ADD 
    encoding : LITERAL
    httpOutboundConnectionJNDIName: httpClient 
    httpTransportConfig:
      endpointURI : /test/ 
      httpOutboundConnectionJNDIName: httpClient 
      overrideHttpClientTimout: false
    soapVersion : '1.1' 
    style: DOCUMENT
    transportBindingType: HTTP 
    validateRequest: 'false' 
    validateResponse: 'false'

Resources

In the resources section, resource templates are listed by type. Each type can have multiple resources with the same type. A resource can be updated, added, or removed.

resources:
  httpConnectors:
  - name: httpConnector_bookstore
    operation: ADD
    description: This is created using Application Configurator (1.0.0.000)
    acceptQueueSize: '50'
    acceptors: '20'
    host: 0.0.0.0
    idleTimeout: '200000'
    lingerTime: '-1'
    lowResourceMaxIdleTime: '-1'
    outputBufferSize: '24576'
    port: '7777'
    requestHeaderSize: '4096'
    responseHeaderSize: '4096'
    sslEnabled: false
    useDirectBuffers: 'false'
    useNonBlockingIOSockets: 'false'

Operation Property

In the YAML file, you can see the operation property for some entities which specifies actions to be performed on the DAA for the entity. Operations can be ADD, UPDATE, and REMOVE. When unspecified, the default operation is UPDATE.

• ADD: For the ADD operation, the entity is added to the application during deployment. If the entity already exists in DAA, then this entity in the configuration file is ignored.
• UPDATE: For the UPDATE operation, the entity in the configuration file overwrites the entity in DAA. If the entity does not exist in DAA, then this entity in configuration file is ignored during deployment.
• REMOVE: For the REMOVE operation, the entity with the same type and name in DAA is removed if it exists. If the entity doesn't exist in DAA, then this entity in configuration file is ignored during deployment.

In the following example, the svar clientport is of type String with a value of 9000. The operation ADD means this svar does not exist in the DAA and it is added to application from the YAML file.

- name: clientport
  operation: ADD
  type: String 
  value: ‘9000’

In the following example, the first reference binding SOAPReference_Binding1 has REMOVE operation. This binding is removed from the application during deployment, although it is specified in the DAA. The second reference binding SoapBinding has ADD operation; it is added to the application during deployment.

references:
- name:NewReference 
  soapBindings:
  - name:SOAPReference_Binding1
    operation: REMOVE 
  - name:SoapBinding
    operation: ADD 
    encoding : LITERAL
    httpOutboundConnectionJNDIName: httpClient 
    httpTransportConfig:
      endpointURI : /test/ 
      httpOutboundConnectionJNDIName: httpClient 
      overrideHttpClientTimout: false
    soapVersion : '1.1' 
    style: DOCUMENT
    transportBindingType: HTTP 
    validateRequest: 'false' 
    validateResponse: 'false'

Brief or Full Format

Format of the generated YAML file can be full or brief. You can specify the format by using the -format parameter when running DAA2Config command. You can also specify the format when downloading configuration from Application Configurator. When unspecified, the default value is full.

• In the full format, all available fields of each entity are generated in the configuration file, though the values of some of the fields are null.

• In the brief format, only the required fields and the fields which are updated are generated in the configuration file.

Following is the resources section of a sample YAML file with the full format.

When generating the application configuration, if you specify the format as full, fields with null values are also generated in the YAML file as shown in the following example:

resources:
  httpClients:
  - name: HttpClient_SampleSOAP
    operation: null
    description: null
    acceptRedirect: 'false'
    basicAuthConfigured: false
    basicAuthPassword: null
    basicAuthUsername: null
    connectionRetrivalTimeout: '0'
    connectionTimeout: '0'
    emptyPwd: false
    enableConnectionPooling: 'true'
    host: www.example.org
    localSocketAddress: null
    maxPoolSize: '20'
    maximumTotalConnections: '20'
    maximumTotalConnectionsPerHost: '2'
    port: '%%httpClientPort%%'
    proxyConfigured: false
    proxyHost: null
    proxyPort: null
    proxyType: null
    soBufferSize: '-1'
    soLinger: '0'
    soReceiveBufferSize: '-1'
    soReuseAddress: 'false'
    soSendBufferSize: '-1'
    soTimeout: '0'
    sslEnabled: false
    sslJndiName: null
    staleCheck: 'false'
    tcpNoDelay: 'true'
  - name: RESTReference_Binding1_HTTPClient
    operation: null
    description: null
    acceptRedirect: 'false'
    basicAuthConfigured: false
    basicAuthPassword: null
    basicAuthUsername: null
    connectionRetrivalTimeout: '0'
    connectionTimeout: '0'
    emptyPwd: false
    enableConnectionPooling: 'true'
    host: www.example.org
    localSocketAddress: null
    maxPoolSize: '20'
    maximumTotalConnections: '20'
    maximumTotalConnectionsPerHost: '2'
    port: '80'
    proxyConfigured: false
    proxyHost: null
    proxyPort: null
    proxyType: null
    soBufferSize: '-1'
    soLinger: '0'
    soReceiveBufferSize: '-1'
    soReuseAddress: 'false'
    soSendBufferSize: '-1'
    soTimeout: '0'
    sslEnabled: false
    sslJndiName: null
    staleCheck: 'false'
    tcpNoDelay: 'true'
  httpConnectors:
  - name: '[httpConnector]'
    operation: ADD
    description: null
    acceptQueueSize: '50'
    acceptors: '20'
    host: 0.0.0.0
    idleTimeout: '200000'
    lingerTime: '-1'
    lowResourceMaxIdleTime: '-1'
    outputBufferSize: '24576'
    port: '7778'
    requestHeaderSize: '4096'
    responseHeaderSize: '4096'
    sslEnabled: false
    sslJNDIName: null
    threadPoolJndiName: null
    useDirectBuffers: 'false'
    useNonBlockingIOSockets: 'false'
  - name: httpConnector
    operation: ADD
    description: null
    acceptQueueSize: '50'
    acceptors: '20'
    host: 0.0.0.0
    idleTimeout: '200000'
    lingerTime: '-1'
    lowResourceMaxIdleTime: '-1'
    outputBufferSize: '24576'
    port: '7777'
    requestHeaderSize: '4096'
    responseHeaderSize: '4096'
    sslEnabled: false
    sslJNDIName: null
    threadPoolJndiName: null
    useDirectBuffers: 'false'
    useNonBlockingIOSockets: 'false'
  jmsConnectionFactories:
  - name: JMSReference_Binding1_ConnectionFactory
    operation: null
    description: null
    enableAuthentication: false
    identityJNDIName: null
    jndiConnectionConfigurationName: JMSReference_Binding1_JNDIConnectionConfiguration
    jndiName: connfactory2
    loginCredUserPwd: false
    maxPoolSize: '20'
    password: null
    sslEnabled: false
    sslJNDIName: null
    username: null
  - name: JMSService_Binding1_ConnectionFactory
    operation: null
    description: null
    enableAuthentication: false
    identityJNDIName: null
    jndiConnectionConfigurationName: JMSService_Binding1_JNDIConnectionConfiguration
    jndiName: connectionFactory
    loginCredUserPwd: false
    maxPoolSize: '20'
    password: null
    sslEnabled: false
    sslJNDIName: null
    username: null
  jndiConnections:
  - name: JMSReference_Binding1_JNDIConnectionConfiguration
    operation: null
    description: null
    emptyPwd: false
    enableAuthentication: false
    identityJNDIName: null
    initialContextFactory: com.tibco.tibjms.naming.TibjmsInitialContextFactory
    loginCredUserPwd: false
    maxPoolSize: '20'
    password: null
    providerUrl: tibjmsnaming://locahost:7222
    sslEnabled: false
    sslJNDIName: null
    username: null
  - name: JMSService_Binding1_JNDIConnectionConfiguration
    operation: null
    description: null
    emptyPwd: false
    enableAuthentication: false
    identityJNDIName: null
    initialContextFactory: com.tibco.tibjms.naming.TibjmsInitialContextFactory
    loginCredUserPwd: false
    maxPoolSize: '20'
    password: null
    providerUrl: tibjmsnaming://locahost:7222
    sslEnabled: false
    sslJNDIName: null
    username: null
  

Following is the resources section of a sample YAML file with the brief format.

When generating the application configuration, if you specify the format as brief, only the required fields and the fields which are different from the default values are generated in the configuration file.

resources:
  httpClients:
  - name: HttpClient_SampleSOAP
    connectionRetrivalTimeout: '0'
    enableConnectionPooling: 'true'
    host: www.example.org
    maximumTotalConnections: '20'
    maximumTotalConnectionsPerHost: '2'
    port: '%%httpClientPort%%'
  - name: RESTReference_Binding1_HTTPClient
    connectionRetrivalTimeout: '0'
    enableConnectionPooling: 'true'
    host: www.example.org
    maximumTotalConnections: '20'
    maximumTotalConnectionsPerHost: '2'
    port: '80'
  httpConnectors:
  - name: '[httpConnector]'
    operation: ADD
    host: 0.0.0.0
    port: '7778'
  - name: httpConnector
    operation: ADD
    host: 0.0.0.0
    port: '7777'
  jmsConnectionFactories:
  - name: JMSReference_Binding1_ConnectionFactory
    jndiConnectionConfigurationName: JMSReference_Binding1_JNDIConnectionConfiguration
    jndiName: connfactory2
  - name: JMSService_Binding1_ConnectionFactory
    jndiConnectionConfigurationName: JMSService_Binding1_JNDIConnectionConfiguration
    jndiName: connectionFactory
  jndiConnections:
  - name: JMSReference_Binding1_JNDIConnectionConfiguration
    initialContextFactory: com.tibco.tibjms.naming.TibjmsInitialContextFactory
    providerUrl: tibjmsnaming://locahost:7222
  - name: JMSService_Binding1_JNDIConnectionConfiguration
    initialContextFactory: com.tibco.tibjms.naming.TibjmsInitialContextFactory
    providerUrl: tibjmsnaming://locahost:7222

Password Management

When the DAA that contains the JDBC shared resource is provided to the Application Configurator UI or DAA2Config command, it generates the configuration YAML file that contains the username and encrypted password. When you create the Docker image of this application, the JDBC resource password is removed from the configuration YAML file, but keystore password is not removed from the configuration YAML file.

jdbcDataSources:
  - name: NewJDBCResource
    operation: REMOVE
  - name: NewJDBCResource
    operation: ADD
    description: This is created using Application Configurator (1.0.0)
    disableValidateConnectionOnInit: false
    jdbcDriver: com.ibm.db2.jcc.DB2Driver
    loginCredUserPwd: true
    password: 'Password has been removed because of security'
    sslEnabled: true
    sslJndiName: SSLClientProvider
    url: jdbc:db2://10.97.105.79:50443/myssldb2
    username: administrator
  keystores:
  - name: KeystoreProvider
    operation: ADD
    description: This is created using Application Configurator (1.0.0)
    keyStoreLocation: admin-database-2020-11-17-12-16-23.jks
    keyStorePassword: '#!ZwF5d7/jvfu6b+WNyK2JnKD0lO5Ema/9'
    keyStoreRefreshInterval: '3600000'
    keyStoreType: JKS
  - name: NewKeystoreProviderResource
    operation: REMOVE