In https://issues.apache.org/jira/browse/ACE-372 an extension is proposed that allows you to set certain attributes on the target and propagate them as tags or attributes of the target object in the client API. The use case being that certain attributes can only be determined and set by the target itself (memory size, display resolution, IP address, etc.) but would still be very useful to have and match against in the client. It would allow you to select distributions based on them, or fill out configuration templates.

Note that properties that are very volatile are not a good use case for this. We anticipate that typically you will set them once, when the target is registered, or maybe occasionally afterwards, but not like every day or hour.

Analysis

There are a couple of things we need to do here:

  1. Provide some kind of API on the target to set, modify and delete such attributes.
  2. Find a way to send those attributes to the server (and client).
  3. On the client, retrieve the attributes and set them on the TargetObject.

The API on the target can be pretty straightforward. It needs to be designed, but there's no analysis needed.

Sending the attributes to the server and client can probably best be done by leveraging a feedback channel (or audit log as it used to be called). By doing so we have already arranged a transport of the data to the server. That solves our second point on the list.

Furthermore, the client also already reads this data, as the StatefulTargetObject needs to read it to determine the deployment state of a target (did the last deployment succeed or not). We can either define a new feedback channel for this data, or add it to the existing audit log. The former gives us a cleaner separation between the pure life cycle data that's currently in the audit log and these attributes, that are arguably not exactly life cycle data. The latter gives us an easier and possibly better performing implementation, as the audit log is already being read to determine the deployment state so we could just leverage that code to retrieve and set our attributes.

I would argue that adding this to the audit log is the best solution. It saves us from having to have two feedback channels. I'd rather have one channel (and possibly slightly rename it) than having multiple ones with potentially more code duplication and worse performance. It would still be possible for users of ACE to define new feedback channels for their own purpose, we just want to make sure that ACE itself only uses one.

Naming attributes

On the target, attributes can have simple (string) names. When merging them with the TargetObject we have to decide two things:

  1. Do we store them as attributes or tags?
  2. Do we prefix them to create a certain namespace?

As attributes were designed to be things that fundamentally belong to an object and tags as things that are added by a user, I think we can quickly conclude we want these attributes to be tags.

Creating a namespace has two advantages: First of all, they directly communicate to the end user that this is a tag that was set by the target itself. Secondly, if we reserve a namespace, we can also more easily delete tags that are no longer used. Assuming that every time there is a change, the target sends the full set of tags, our server side logic can simply set all those tags and remove any other tags still in the same namespace.

Usage

To set or update properties, you can simply send a feedback event using the API of the management agent:

AgentControl ac;
Map m = new HashMap();
m.put("mykey", "myvalue");
ac.getFeedbackHandler().getChannel("auditlog").write(AuditEvent.TARGETPROPERTIES_SET, p);

Make sure you always write the full set of properties, as any old ones will be erased. The keys of the properties you set will end up as tags, prefixed with "target." to distinguish them from other tags that might be set manually.

Note that tags will show up as soon as you do a checkout in the ACE client, at which point you will see the repository is in a modified state. Committing such changes will make them take effect. This was done because you don't want to have such changes take effect at any time. Like any other change in the deployment, it must be a deliberate and controllable change.

  • No labels