6.2. Working with Profiles

Changing the profiles in a container

To change the profiles assigned to a Fabric container, invoke the fabric:container-change-profile command as follows:
fabric:container-change-profile mycontainer myprofile
Where the preceding command deploys the myprofile profile to the mycontainer container. All profiles previously assigned to the container are removed. You can also deploy multiple profiles to the container, with the following command:
fabric:container-change-profile mycontainer myprofile myotherprofile

Adding a profile to a container

The fabric:container-add-profile command gives you a simple way to add profiles to a container, without having to list all of the profiles that were already assigned. For example, to add the example-camel profile to the mycontainer container:
fabric:container-add-profile mycontainer example-camel

Listing available profiles

To see the list of available profiles, invoke the fabric:profile-list console command:
fabric:profile-list
The command displays all available profiles, showing their parents and the number of containers each profile is deployed into.

Inspecting profiles

To see exactly what a profile defines, enter the fabric:profile-display command. For example, to display what is defined in the feature-camel profile, enter the following command:
fabric:profile-display feature-camel
Which outputs something like the following to the console window:
Profile id: feature-camel
Version   : 1.0
Attributes: 
    parents: karaf

Containers: 

Container settings
----------------------------
Repositories : 
    mvn:org.apache.camel.karaf/apache-camel/${version:camel}/xml/features

Features : 
    camel-core
    camel-blueprint
    fabric-camel

Configuration details
----------------------------

Other resources
----------------------------
Resource: io.fabric8.insight.metrics.json 
Resource: icon.svg
Resource: Summary.md
The preceding output does not take into account the definitions inherited from any parent profiles, however. To see the effective definitions for the feature-camel profile, taking into account all of its ancestors, you must specify the --overlay switch, as follows:
fabric:profile-display --overlay feature-camel
Resource files stored in the profile are listed under the heading Other resources. If you want to display the contents of these resource files as well, add the --display-resources switch (or -r for short) to the profile-display command, as follows:
fabric:profile-display -r feature-camel

Creating a new profile

To create a new profile for an application, invoke the fabric:profile-create command, as follows:
fabric:profile-create myprofile
To specify one ore more parents for the profile when it is being created, add the --parents option to the command:
fabric:profile-create --parents feature-camel myprofile
After the profile is created, you can start to modify the profile, providing details of what should be deployed in the profile.

Adding or removing features

To edit one of the existing profiles, you can use the fabric:profile-edit command. For example, to add the camel-jclouds feature to the feature-camel profile.
fabric:profile-edit --feature camel-jclouds feature-camel
Now invoke the fabric:profile-display command to see what the camel profile looks like now. You should see that the camel-jclouds feature appears in the list of features for the feature-camel profile.
Features :
        	camel-jclouds
        	camel-blueprint/2.9.0.fuse-7-061
        	camel-core/2.9.0.fuse-7-061
        	fabric-camel/99-master-SNAPSHOT
If you want to remove a feature from the profile, use the --delete option. For example, if you need to remove the camel-jclouds feature, you could use the following command:
fabric:profile-edit --delete --feature camel-jclouds feature-camel

Editing PID properties

An OSGi Config Admin Persistent ID (PID) consists essentially of a list of key-value pairs. You can edit PID properties using either of the following approaches:
  • Edit the PID using the built-in text editor—the Karaf console has a built-in text editor which you can use to edit profile resources such as PID properties. To start editing a PID using the text editor, enter the following console command:
    fabric:profile-edit --pid PID ProfileName
    For more details about the built-in text editor, see Appendix A, Editing Profiles with the Built-In Text Editor.
  • Edit the PID inline, using console commands—alternatively, you can edit PIDs directly from the console, using the appropriate form of the fabric:profile-edit command. This approach is particularly useful for scripting. For example, to set a specific key-value pair, Key=Value, in a PID, enter the following console command:
    fabric:profile-edit --pid PID/Key=Value ProfileName

Editing a PID inline

To edit a PID inline, use the following variants of the fabric:profile-edit command:
  • Assign a value to a PID property, as follows:
    fabric:profile-edit --pid PID/Key=Value ProfileName
  • Append a value to a delimited list (that is, where the property value is a comma-separated list), as follows:
    fabric:profile-edit --append --pid PID/Key=ListItem ProfileName
  • Remove a value from a delimited list, as follows:
    fabric:profile-edit --remove --pid PID/Key=ListItem ProfileName
  • Delete a specific property key, as follows:
    fabric:profile-edit --delete --pid PID/Key ProfileName
  • Delete a complete PID, as follows:
    fabric:profile-edit --delete --pid PID ProfileName

Example of editing a PID inline

In the following example, we modify the io.fabric8.agent PID, changing the Maven repository list setting. The default profile contains a section like this:
Agent Properties :
        org.ops4j.pax.url.mvn.repositories=
            http://repo1.maven.org/maven2@id=maven.central.repo,
            https://maven.repository.redhat.com/ga@id=redhat.ga.repo,
            https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo,
            https://repository.jboss.org/nexus/content/groups/ea@id=fuseearlyaccess
The agent properties section is represented by the io.fabric8.agent PID. So, by modifying the io.fabric8.agent PID, we effectively change the agent properties. You can modify the list of Maven repositories in the agent properties PID as follows:
fabric:profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories=http://repositorymanager.mylocalnetwork.net default
Now when you invoke fabric:profile-display on the default profile, you should see agent properties similar to the following:
Agent Properties :
        org.ops4j.pax.url.mvn.repositories = http://repositorymanager.mylocalnetwork.net

Setting encrypted PID property values

In some cases, you might prefer to store PID property values in encrypted format instead of plain text. For example, passwords and other sensitive data should usually be stored in encrypted form. To store a property value in encrypted form, perform the following steps:
  1. Use the fabric:encrypt-message command to encrypt the property value, as follows:
    fabric:encrypt-message PropValue
    This command returns the encrypted property value, EncryptedValue.
    Note
    The default encryption algorithm used by Fabric is PBEWithMD5AndDES.
  2. You can now set the property to the encrypted value, EncryptedValue, using the following syntax:
    my.sensitive.property = ${crypt:EncryptedValue}
    For example, using the fabric:profile-edit command, you can set an encrypted value as follows:
    fabric:profile-edit --pid com.example.my.pid/my.sensitive.property=${crypt:EncryptedValue} Profile
Important
These encrypted values are protected by the master password, which is accessible to anyone who can log on to a Fabric container. To keep these encrypted values safe, you must restrict access to the containers in the fabric.
When using encrypted property values in Blueprint, the property-placeholder element must depend on the Fabric service as shown in the following example:
<reference id="fabricService" interface="io.fabric8.api.FabricService" availability="mandatory"/>
<cm:property-placeholder id="properties" persistent-id="encrypted.properties" depends-on="fabricService"/>

Alternative method for encrypting PID property values

The underlying encryption mechanism for PID properties is based on the Jasypt encryption toolkit. Consequently, it is also possible to encrypt PID properties directly, using the Jasypt toolkit, as follows:
  1. Download and install Jasypt, to gain access to the Jasypt encrypt and decrypt command-line tools.
  2. Use the Jasypt encrypt command-line tool to encrypt the property value, as follows:
    ./encrypt.sh input="Property value to be encrypted" password=ZooPass verbose=false
    This command returns the encrypted property value, EncryptedValue.
    Note
    The default encryption algorithm used by Fabric is PBEWithMD5AndDES. You must ensure that the encrypt.sh utility is using the same algorithm as Fabric.

Customizing the PID property encryption mechanism

You can customize the PID property encryption mechanism, as follows:
  • Customize the master password for encryption—using the following console command:
    fabric:crypt-password-set MasterPassword
    You can retrieve the current master password by entering the fabric:crypt-password-get command. The default value is the ensemble password (as returned by fabric:ensemble-password).
  • Customize the encryption algorithm—using the following console command:
    fabric:crypt-algorithm-set Algorithm
    Where the encryption algorithm must be one of the algorithms supported by the underlying Jasypt encryption toolkit. You can retrieve the current encryption algorithm by entering the fabric:crypt-algorithm-get command. The default is PBEWithMD5AndDES.

Profile editor

If you want to make extensive edits to a profile, it is not very convenient to make changes one setting at a time. There is a more convenient approach for making extensive profile edits, and that is to use the console's built-in profile editor, which is a simple screen-based text editor.
For example, to open the agent properties resource for editing, simply invoke the fabric:profile-edit command without any options, as follows:
fabric:profile-edit Profile [Version]
A simple text editor opens, enabling to edit the configuration settings in the agent properties.
For full details of how to edit profiles using the built-in text editor, see Appendix A, Editing Profiles with the Built-In Text Editor.

Editing resources with the profile editor

A practical way to edit a general profile resource (such as an XML configuration resource) is to use the built-in text editor. For example, to start editing the broker.xml file in the mq-amq profile, enter the following console command:
fabric:profile-edit --resource broker.xml mq-amq