[Hawkular-dev] deploy / undeploy / remove

[John Mazzitelli]

(This is a long email - it is for people involved in deploying applications via the Hawkular WildFly Agent. If you are writing UI code to deploy/undeploy, I suggest you read it. Send questions/comments - because I'm not even sure if I understand everything 100%)

I just realized why there is confusion regarding how to tell the agent to deploy/undeploy/remove applications.

There are different operations on different resources that do apparently the same thing. But I think this is mainly due to the fact the agent is trying to support both standalone and domain modes and to make it easier on the clients.

On the "WildFly Server" resource (which is the standalone server), these operations are defined by the agent:

   <operation-dmr name="Deploy"   internal-name="deploy"/>
   <operation-dmr name="Undeploy" internal-name="undeploy"/>

On the "Host Controller" resource (which is only in domain mode), there are these same two operations defined.

So, you can deploy an application through the "WildFly Server" (standalone mode) and "Host Controller" (domain mode) - you need to pass in content when you do this, hence why DeployApplicationRequest JSON has to be used.

But notice you can also undeploy an application through those top level resources as well. You do this via UndeployApplicationRequest JSON.

Why don't we use ExecuteOperationRequest JSON here but instead require these two special JSON commands? Because there is no "deploy" or "undeploy" DMR operations on those wildfly resources (i.e. the top level server or host controller). However, there are several deploy/undeploy related DMR operations - like full-replace-deployment, upload-deployment-bytes, replace-deployment, etc. But rather than force the UI clients to have to know about all of these, the agent provides just the simple "Deploy" and "Undeploy" which do what you'd expect them to do. We make it easy by providing some flags in the DeployApplicationRequest JSON to let you say if you want it enabled or not and the agent will always force the deployment (that means, if there was already a deployment, the new deployment replaces the old). So the client doesn't have to fool around with the different combinations ("does this deployment already exist? No? Then just send in the content. Do you want it enabled? Deploy it, too. Yes, deployment already exists? Then send a undeploy command first, then send a remove command, then send a deploy command - or whatever WildFly wants you to do, I'm not even sure").

The agent is using the new wildfly maven core API to do the deploy and undeploy - so its very easy to wrap that stuff around our Deploy/Undeploy stuff - we let that library deal with all the details on how to do this. This, again, is why we don't use ExecuteOperationRequest - because if we did, the CLIENT would have to do all the stuff this wildfly maven core API does to get content to be deployed.

OK, but it gets more confusing because now if you look at the deployment resources, there are ANOTHER set of operations dealing with deploy/undeploy and these DO USE ExecuteOperationRequest JSON to invoke them (because these really do just pass through to the WildFly management controller and execute as is).

For example, on any deployment inside a standalone server you will see these:

/deployment=hawkular-rest-api.war/:read-operation-names
{
   "deploy",
   "redeploy",
   "remove",
   "undeploy",
}

Very confusing to have "deploy" on an deployment!! It is already deployed! I don't fully understand this, but I think this is to deploy an application whose content is uploaded but is NOT enabled. You'll see that deployment resource exists in the server but its not "enabled" because it isn't deployed. You "enable" it by deploying it.

And you'll see here you can redeploy the app, remove it (that removes the content entirely I believe - I think the entire deployment resource goes away when you do this), and undeploy (which to me means "disable").

This is why you will see a separate set of deployment related operations defined in the agent's "Deployment" resource type:

    <operation-dmr name="Redeploy" internal-name="redeploy"/>
    <operation-dmr name="Remove"   internal-name="remove"/>
    <operation-dmr name="Undeploy" internal-name="undeploy"/>

Very confusing indeed, but these are meant to be executed via the ExecuteOperationRequest JSON and they map one-to-one to the WildFly's operations that I showed above. Note there is no "Deploy" that we map - there is no reason for that other than it probably didn't make sense to us to add it. And I'm not even sure if the client should be executing these operations IF IN DOMAIN MODE! You should be going through the host controller to deploy and undeploy applications when in domain mode.

Clear as mud?

So the next question is - which ones should we be using? Send ExecuteOperationRequest JSON to the "Deployment" resource itself? Or (Un)DeployApplicationRequest JSON to the top level Server/HostController?

To my mind, we should be using the (Un)DeployApplicationRequest JSON on the top level servers. I am almost thinking we should remove the <operation-dmr> definitions for the Redeploy/Remove/Undeploy on the Deployment resources themselves - you really should only be using those when in standalone mode (so your client now has to know to only call them if the server is in standalone mode) and it just adds a second way to do something which makes it confusing to know which to use.

I think there should be a design meeting with all the involved parties (developers, UI design, requirement authors) so we can figure out what we really need. I know this is in the PRD but quite honestly that's like reading the fine print of a legal document and my eyes glaze over before I finish the first paragraph.