PeterNic
05-28-2008, 11:09 AM
When you use the standard template applications that come with AppLogic, you can configure them without ever going into the editor -- the properties are defined on the application as a whole. This makes it easy to configure the application using 'app config' and 'app provision' (as well as with the GUI from the application list screen).
So, how can you do this for your own apps?
Background
AppLogic supports the notion of assembled appliances (assemblies). These appliances appear as a regular appliance on the outside. Inside, however, they don't have a virtual machine or an OS; instead, they are constructed as a structure of connected appliances. This allows AppLogic users to define various subsystems and clusters and wrap them as virtual appliances.
When defining an assembly, you (the designer, the user) choose what properties of the appliances inside to make available on the assembly boundary for configuration and how to propagate them to the individual appliances. You do this by defining the set of properties using the "Edit Class" context menu for the appliance (right-click on an empty area on the canvas and select Edit Class, then Properties).
AppLogic uses the same assembly mechanism when packaging the infrastructure of an application as a single entity (the application). You may have noticed the pesky "main." in the name of appliances when you do 'comp list'. "Main" is the name of the topmost assembly of the application. The way to define properties on the boundary of the application is to define these properties on the boundary of its MAIN class.
If you want to know more about how assemblies, appliances, catalogs, etc., are defined, read the AppLogic application model (http://doc.3tera.net/AppLogic2/AdvApplicationModel.html) (advanced topic).
Details
Even if the above went completely over your head, you can still add the properties. Here's how:
Open your application in the infrastructure editor (http://doc.3tera.net/AppLogic2/RefEditor.html)
Right-click on the canvas (where there are no appliances or connections) and select "Edit Class". This will allow you to edit the MAIN class of the application
Select the Properties tab (http://doc.3tera.net/AppLogic2/RefEditorClassEditorAssembly.html?#Properties)
Add the properties you want to expose on the boundary of the application (for example, if you have a simple app that has one appliance only, you may expose most or all of its properties). For each property, decide if you want to define a default value or not.
Close the class editor (click OK)
For each appliance whose properties you want to expose, open the property sheet (http://doc.3tera.net/AppLogic2/RefEditorInstanceSettings.html?#Property_Values) for it (right-click on the appliance, select Property Values)
For each property you want to expose, select "Redirect" (a small button with a curved arrow on it), and then from the list select the application-level property you want to redirect to (when a value is configured on the application's boundary, that value will automatically be propagated by AppLogic to this appliance's property).
Repeat for each appliance.
Save the application now.
Verify: open the Application Configuration (http://doc.3tera.net/AppLogic2/RefAppConfig.html?#Properties) for the app inside the editor (right-click on the canvas, select Application Configuraiton); select Properties. Verify that all properties have a type (rather than "unknown") -- if you still have properties with "unknown", you have not yet redirected any appliance's property to them -- go back and complete that (or delete the app-level property). Another way to verify that you have everything in place is to issue the "app config <appname> --boundary (http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorConfig)" command in the shell - it will fail if you have not completed all redirections. (Make sure you save the app before performing the verification, regardless of which method you use.)
This completes the designer work. Now your application is defined. Save the app.
You can now configure the application -- either through 'app config' (http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorConfig) from the shell, or using the "Application Configuration (http://doc.3tera.net/AppLogic2/RefAppConfig.html?#Properties)" menu (from the app list screen or from the canvas menu).
What properties to expose
A good rule of thumb is to expose only properties that will make sense in the scope of the application as a whole.
For example, the WEB appliance has a property in which you define the index pages' name. This makes sense to leave configurable, so, you can for example, set it to index.pl or index.cgi or index.asp or whatever your application requires. Exposing that property, however, on the boundary of the application may be inappropriate -- in this case, just set the explicit value and don't expose/redirect that property.
Another thing to keep in mind is that property names are relative to the entity to which they apply. For example, the IP address property on a gateway appliance class is "ip_addr". It makes sense, since the appliance has a single IP address. However, for an application, you may have multiple IP addresses, so calling that property "ip_addr" makes sense only if you have one IP.
When defining properties on the app boundary, make sure that you expose only properties that need to be changed (rather than the ones that make the app run as designed) and that their names are meaningful to someone who looks at the app as a whole.
References
Here are a few links to the relevant documentation pages:
assembly class editor where properties of the app are to be defined: http://doc.3tera.net/AppLogic2/RefEditorClassEditorAssembly.html?#Properties (note: don't define interfaces on the app as a whole -- the topmost assembly of the app must not have terminals)
instance settings property sheets for redirecting appliance properties to the app boundary: http://doc.3tera.net/AppLogic2/RefEditorInstanceSettings.html?#Property_Values
application configuration screen where you can inspect that all app-level properties are correctly redirected (have known types) and enter values for them: http://doc.3tera.net/AppLogic2/RefAppConfig.html?#Properties
shell commands for configuring and provisioning apps: http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorConfig, http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorProvision
more details on the AppLogic application model and assemblies: http://doc.3tera.net/AppLogic2/AdvApplicationModel.html
If you have any questions or comments, please post here.
Regards,
-- Peter
So, how can you do this for your own apps?
Background
AppLogic supports the notion of assembled appliances (assemblies). These appliances appear as a regular appliance on the outside. Inside, however, they don't have a virtual machine or an OS; instead, they are constructed as a structure of connected appliances. This allows AppLogic users to define various subsystems and clusters and wrap them as virtual appliances.
When defining an assembly, you (the designer, the user) choose what properties of the appliances inside to make available on the assembly boundary for configuration and how to propagate them to the individual appliances. You do this by defining the set of properties using the "Edit Class" context menu for the appliance (right-click on an empty area on the canvas and select Edit Class, then Properties).
AppLogic uses the same assembly mechanism when packaging the infrastructure of an application as a single entity (the application). You may have noticed the pesky "main." in the name of appliances when you do 'comp list'. "Main" is the name of the topmost assembly of the application. The way to define properties on the boundary of the application is to define these properties on the boundary of its MAIN class.
If you want to know more about how assemblies, appliances, catalogs, etc., are defined, read the AppLogic application model (http://doc.3tera.net/AppLogic2/AdvApplicationModel.html) (advanced topic).
Details
Even if the above went completely over your head, you can still add the properties. Here's how:
Open your application in the infrastructure editor (http://doc.3tera.net/AppLogic2/RefEditor.html)
Right-click on the canvas (where there are no appliances or connections) and select "Edit Class". This will allow you to edit the MAIN class of the application
Select the Properties tab (http://doc.3tera.net/AppLogic2/RefEditorClassEditorAssembly.html?#Properties)
Add the properties you want to expose on the boundary of the application (for example, if you have a simple app that has one appliance only, you may expose most or all of its properties). For each property, decide if you want to define a default value or not.
Close the class editor (click OK)
For each appliance whose properties you want to expose, open the property sheet (http://doc.3tera.net/AppLogic2/RefEditorInstanceSettings.html?#Property_Values) for it (right-click on the appliance, select Property Values)
For each property you want to expose, select "Redirect" (a small button with a curved arrow on it), and then from the list select the application-level property you want to redirect to (when a value is configured on the application's boundary, that value will automatically be propagated by AppLogic to this appliance's property).
Repeat for each appliance.
Save the application now.
Verify: open the Application Configuration (http://doc.3tera.net/AppLogic2/RefAppConfig.html?#Properties) for the app inside the editor (right-click on the canvas, select Application Configuraiton); select Properties. Verify that all properties have a type (rather than "unknown") -- if you still have properties with "unknown", you have not yet redirected any appliance's property to them -- go back and complete that (or delete the app-level property). Another way to verify that you have everything in place is to issue the "app config <appname> --boundary (http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorConfig)" command in the shell - it will fail if you have not completed all redirections. (Make sure you save the app before performing the verification, regardless of which method you use.)
This completes the designer work. Now your application is defined. Save the app.
You can now configure the application -- either through 'app config' (http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorConfig) from the shell, or using the "Application Configuration (http://doc.3tera.net/AppLogic2/RefAppConfig.html?#Properties)" menu (from the app list screen or from the canvas menu).
What properties to expose
A good rule of thumb is to expose only properties that will make sense in the scope of the application as a whole.
For example, the WEB appliance has a property in which you define the index pages' name. This makes sense to leave configurable, so, you can for example, set it to index.pl or index.cgi or index.asp or whatever your application requires. Exposing that property, however, on the boundary of the application may be inappropriate -- in this case, just set the explicit value and don't expose/redirect that property.
Another thing to keep in mind is that property names are relative to the entity to which they apply. For example, the IP address property on a gateway appliance class is "ip_addr". It makes sense, since the appliance has a single IP address. However, for an application, you may have multiple IP addresses, so calling that property "ip_addr" makes sense only if you have one IP.
When defining properties on the app boundary, make sure that you expose only properties that need to be changed (rather than the ones that make the app run as designed) and that their names are meaningful to someone who looks at the app as a whole.
References
Here are a few links to the relevant documentation pages:
assembly class editor where properties of the app are to be defined: http://doc.3tera.net/AppLogic2/RefEditorClassEditorAssembly.html?#Properties (note: don't define interfaces on the app as a whole -- the topmost assembly of the app must not have terminals)
instance settings property sheets for redirecting appliance properties to the app boundary: http://doc.3tera.net/AppLogic2/RefEditorInstanceSettings.html?#Property_Values
application configuration screen where you can inspect that all app-level properties are correctly redirected (have known types) and enter values for them: http://doc.3tera.net/AppLogic2/RefAppConfig.html?#Properties
shell commands for configuring and provisioning apps: http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorConfig, http://doc.3tera.net/AppLogic2/CliApplication.html#AnchorProvision
more details on the AppLogic application model and assemblies: http://doc.3tera.net/AppLogic2/AdvApplicationModel.html
If you have any questions or comments, please post here.
Regards,
-- Peter