RUN@cloud » Binding services (resources) to applications

Binding services (resources) to applications

Last modified by Cyrille Le Clerc on 2013/12/30 12:13

Service Management and binding

The CloudBees platform manages several features, like session stores, SSL routers, databases and add ons (like Sendgrid and NewRelic) as platform resources. An application can use resources when they are bound to it. Many of these resources can be bound to an application by selecting them in the RUN Web Console, but they can also be bound using the CloudBees SDK. (To create some of those resources, see the dedicated pages for Session Store and Routers).

Binding services and resources to Applications

Binding a service/resource to an application will establish a relationship between the app and the resource and will typically trigger some interaction that is unique to the type of resource and application container.  Here are some examples:

  • Binding an SSL router will cause the router to route incoming HTTP requests for that router to the application
  • Binding a database will cause the database to be injected into the application as a JNDI DataSource 
  • Binding a session store will cause the application to store its session data in the store

Note that how this works depends on the resource, and also the container (the ClickStack) in use. For example: 

  • For the standard servlet and EE containers, for example, the databases are bound as JNDI datasources. 
  • For JVM type clickstacks - JVM system properties are set containing variables for the resource/service (eg url, password)
  • For other clickstacks - generally environment variables are injected that contain the variables (url, password) etc. 

Variables and properties for bound resources

Bound resources/services produce system properties or environment variables (depending on if it is a JVM environment or not) for applications. Their form depends on the service type, for example, if you were to bind a database service to your app: 

bees app:bind -db spike/spike-db -a spike/snoop -as mydb

Then you will see variables appear (in the form of): 

  • DATABASE_PASSWORD_MYDB
  • DATABASE_URL_MYDB
  • DATABASE_USERNAME_MYDB

Where the MYDB suffixed is the uppercase value of the binding alias "-as"

You can use these to connect to the service appropriately. There is also this app that will snoop/dump your environment: https://github.com/swashbuck1r/snoop (but careful - it will print out everything to screen). 

These properties/environment variables follow the pattern of <servicename>_field_<boundname>.

Application resources

Bind a resource to an application using the CloudBees SDK.

usage: bees app:bind [options]
-a,--appid <arg>        CloudBees application ID
-as,--alias <arg>       Binding alias name
-r,--resourceId <arg>   Resource ID
-db,--database <arg>    Database name.

Example: Bind the application session store "session-store1" to the "acme" "test" application as "store1"
bees app:bind -a acme/test -r session-store1 -as store1

If the alias (-as) is not specified, the alias will be the resource name "session-store1".
Example: Bind the application session store "session-store1" to the "acme" "test" application as "session-store1"
bees app:bind -a acme/test -r session-store1

Databases

Since CloudBees MySQL Databases are platform resources, they can be bound to your applications using the bees app:bind command. This makes the database available to the application in a way that is "native" to the container (system properties/environment variables and, if available in your container, a JNDI datasource).

For Java Web containers, binding a database to an application is the equivalent of adding the jdbc datasource definition into the cloudbees-web.xml, so that the database will be available as a native DataSource object.

Example: Bind the database "mydb" to the "test" Tomcat 7 application of the "acme" account.

bees app:bind -a acme/test -db acme/mydb -as mydb

The following Java System properties will be injected: DATABASE_URL_MYDB, DATABASE_USERNAME_MYDB and DATABASE_PASSWORD_MYDB

And the JNDI datasource jdbc/mydb will be injected with sensible parameters for your environment. You can override these default parameters adding name=value pairs to your binding command (see available parameters on the Tomcat7 ClickStack documentation).

Database binding sample limiting maxActive to 5

bees app:bind -a APP_ID -db DB_ID -as DATASOURCE_NAME maxActive=5

Please note that the way that the database is injected for the application and the parameters it supports is dependent on the ClickStack you are using. Some ClickStacks will use the database binding to setup native DataSources, while other may do nothing more than make the database settings available to you as environment or system property variables.

Unbinding application resources

Unbind a resource from an application

usage: bees app:unbind [options] BINDING_ALIAS
-a,--appid <arg>    CloudBees application ID

Example: Unbind the application session store "store1" (resource alias) from the "acme" "test" application
bees app:unbind -a acme/test store1

Listing application resources

To list the application resources defined in the account

usage: bees app:resource:list [options]
-a,--account <arg>   Account Name
-t,--type <arg>      resource type

Example: List all "acme" account resources
bees app:resource:list -a acme

Listing application bindings

To list the resources bound to an application

usage: bees app:bindings APPLICATION_ID

Example: List resources bound to the application "test"
bees app:resource:bindings test

Deleting application resources

To delete an application resource

usage: bees app:resource:delete [options] RESOURCE_NAME
-a,--account <arg>   Account Name
-f,--force           force delete without prompting

Example: Delete the session store "store1" (resource alias)
bees app:resource:delete store1

Tags:
Created by Fabian Donze on 2012/03/21 18:01