console patching requirements

[emuckenhuber]

In a different thread we had a discussion about the InstalledImage, where especially the requirements for patching were unclear. Here a few points we gathered from a discussion with the console team.

1) AS to fully support applying patches, e.g.

• easily updating jars without needing to delete/backup the old ones
  As mentioned in a different thread, we could simply have overlay directories and having the core module system taking care of using the correct libraries.
  
  In general we currently have - the actual release and the cumulative patches against the original version (as far as i understood that) and one off patches against the actual modules. Where if a CP is a diff zip against the original version, it's mostly an unzip operation into a separate overlay directory per CP version. For one off patches there should most likely be just one directory, in case one-off patches are against a specific module version it is valid as long as there is no newer version of the module.
  
  Although the question is if it should be possibility to rollback arbitrary one-off patches or if we can simply rollback to the CP? Which could only mean removing the one-off patch?
  
  This could also work for having the repository shared across domains, where we would need to also maintain the version a server is running on - but we might need to do that in general?
  
  Additionally what about patching things like "client/", "docs/", "examples/"? I guess this should not be versioned anyway, so a rollback would be harder and we might not need that for docs/ and examples/. For the client i'm not sure, maybe we can use the class-path element in the manifest to point to the actual .jars and have the module system to export that as well?
  
  
• easily update configuration settings
  Updating configuration settings should be easier with the domain model in general. Where i see basically 2 use cases:
  • patching default values:
    Since default values are going to be separate from the actual configuration, this should be coved by a normal module repository update.
  • patching the actual domain configuration values:
    Where the question is if we need this is a patch, or if this is more something like a reference for management clients to check whether components would need to be updated. Since it most likely will require a user interaction.

2) A client for applying patches to AS

The "client" for applying a patch would be the SM? However it most likely should also exist at the domain model level, otherwise this means that there would need to be a jon agent per host?

[brian.stansberry]

For one-off patches I think we need the ability to roll back the latest patch. So that implies two overlay dirs, the latest and the previous. A question is when can the "previous" be overwritten. E.g. assume a monthly outage window where user wishes to apply 3 unrelated patches that have popped up over the month. At the end the "previous" should be the state before the 1st patch was applied, not the state before the 3rd was applied. This implies some mechanism to declare that the "latest" is good and can be used as "previous" if another patch is applied.

Good point on client/docs/examples; we'll have to think that through.

I think of the "client" for applying a patch as JON or the embedded console on the DC.

[emuckenhuber]

Brian Stansberry wrote:

For one-off patches I think we need the ability to roll back the latest patch. So that implies two overlay dirs, the latest and the previous. A question is when can the "previous" be overwritten. E.g. assume a monthly outage window where user wishes to apply 3 unrelated patches that have popped up over the month. At the end the "previous" should be the state before the 1st patch was applied, not the state before the 3rd was applied. This implies some mechanism to declare that the "latest" is good and can be used as "previous" if another patch is applied.

Yeah, i was rather thinking about rolling back per module. It seems that keeping track of (unrelated) patches is the main difficulty. Maybe we can just have a general overlay for CPs shared across domains - since this is not something mutable. Where we keep track of one-off patches as part of the domain and log that as a domain update. Not sure if that would make sense, but this seems to be more than just an unzip operation...

Brian Stansberry wrote:

I think of the "client" for applying a patch as JON or the embedded console on the DC.

Ah, yes that's what charles also wrote, i was mixing that up...

[brian.stansberry]

A general overlay for CPs shared across domains sounds fine, although I don't see sharing an installation across images as a requirement. It's fine to see what it takes to support it, but if it impacts the schedule, it's gotta go.

If we treat one-off patches as domain updates and log them as such, where do we store them? It still seems like some sort of overlay dir is needed.

Ping me in the morning when I come online; we can chat a bit.

[emuckenhuber]

Brian Stansberry wrote:

A general overlay for CPs shared across domains sounds fine, although I don't see sharing an installation across images as a requirement. It's fine to see what it takes to support it, but if it impacts the schedule, it's gotta go.

Hmm, it would be easier to just swap the complete module repository and don't have an overlay directory for CPs. Maybe not that nice and would require more space, however seems easier. So we could just define which module repository to use as part of the host.xml?

Brian Stansberry wrote:

If we treat one-off patches as domain updates and log them as such, where do we store them? It still seems like some sort of overlay dir is needed.

I don't know. Where do we store older versions of deployments? It basically seems to be a similar operation in the end. Yes, here we would definitely need an overlay directory, however we might be able to limit this more - i guess we don't need to replace the module.xml, just have overlay resources?

[brian.stansberry]

Re: clients, docs, examples, David, Emanuel and I were chatting on IRC today.

Didn't really reach a conclusion on client, but the use case for patching it by laying down jars seems far-fetched. People want some mechanism to get an official distribution of client jars; having it sitting in the installed image on their production servers is probably not what they are looking for.

Re: docs and examples, there is the following content in these dirs now:

1) dtds and schemas. These will not be updated via one-off patches.

2) Unusual components, e.g. jts. These should be standard modules and patched as such.

3) Database-specific ds.xml examples. These can be replaced with a README with links to a tamper-proof web repository; folks don't need the file in the installed image. The same is true for dtds and schemas.

4) Database-specific JBM configs. Not relevant any more.

Conclusion was we should not support patching of docs/examples.

[emuckenhuber]

Based on our last conversation we agreed to move forward with overlay directories and patching is going to be kept separate from the actual module contents. Where we are going to keep a history of applied patches based on the modified contents, not on the order when they were applied. This will result in a structure like:

module-repository/ - the module repository root
 
 - base/ - the "base" module repository
 - base-patch/ - overlay patch directory for "base"
 - base-patch/.history/ (or base-patch-history?) - the history of applied patches for "base"
 - 6.0.1/ - cummulative patch release, only containing modifications based on "base"
 - 6.0.1-patch/ - overlay patch directory for "6.0.1"
 - 6.0.1-patch/.history/
 

I guess the CPs will always be based on modifications since "base"? What happens if you download the 6.0.1 bundle - would the changes be part of "base" then? Which means that we would need to expose versions of "base", "6.0.1" ?

Thinking about the actual InstalledImage term, where we started - i think beside the question what we do with client, one thing remains - if we should do "bin/" patching as well?

[emuckenhuber]

Emanuel Muckenhuber wrote:

Thinking about the actual InstalledImage term, where we started - i think beside the question what we do with client, one thing remains - if we should do "bin/" patching as well?

Basically what i mean is that if we don't need to patch "bin/", then we rather should call the InstalledImage - server repository or something. Which is just a part of the AS distribution.

[brian.stansberry]

Tell me what's in /bin. :-)

This is why I want a draft layout, so we can discuss from a common point of reference.

[emuckenhuber]

Hehe, ok - so what i was thinking about so far is something like:

bin/

  - run.sh / run.conf or smth like jbossadmin.sh

  - maybe also jboss-modules.jar

so mostly about scripts to launch ServerManager, maybe standalone.sh and an easy way to access the CLI.

client/ ?

modules/

  - base/

  - base-patch/

  - 6.0.1/

  - 6.0.1-patch/

  - 6.0.2/

  - 6.0.2-patch/

Plus obviously the domain parts - which might should not part of the InstalledImage, since it's managed by the domain. I think we have a couple of options, like:

domain/

  - configuration/

     - domain.xml

     - host.xml

     - standalone.xml  ?

  - servers/

     node1/

        tmp/, data/ log/

     node2/

        tmp/, data/ log/

or have configuration/ and servers/ as part of the root. As we said above is that the common module repository should only be shared within one domain - which would also mean that a standalone.xml and domain.xml should not coexist within the same configuration.

[dmlloyd]

Emanuel Muckenhuber wrote:

Hehe, ok - so what i was thinking about so far is something like:

bin/

  - run.sh / run.conf or smth like jbossadmin.sh

  - maybe also jboss-modules.jar

so mostly about scripts to launch ServerManager, maybe standalone.sh and an easy way to access the CLI.

client/ ?

modules/

  - base/

  - base-patch/

  - 6.0.1/

  - 6.0.1-patch/

  - 6.0.2/

  - 6.0.2-patch/

Plus obviously the domain parts - which might should not part of the InstalledImage, since it's managed by the domain. I think we have a couple of options, like:

domain/

  - configuration/

     - domain.xml

     - host.xml

     - standalone.xml  ?

  - servers/

     node1/

        tmp/, data/ log/

     node2/

        tmp/, data/ log/

or have configuration/ and servers/ as part of the root. As we said above is that the common module repository should only be shared within one domain - which would also mean that a standalone.xml and domain.xml should not coexist within the same configuration.

All looks good.  I agree that standalone.xml and domain.xml should not coexist.  I think also that standalone.xml encompasses host.xml so it would eliminate that too.

Do you think it might be more user-friendly to put domain/host/standalone.xml right into the root distro directory though?  Might make it a bit more obvious.

Also it is very possible that domain.xml is not visible on any node other than the domain controller, which would also have a host.xml file for each known host as well.

[emuckenhuber]

David Lloyd wrote:

Do you think it might be more user-friendly to put domain/host/standalone.xml right into the root distro directory though?  Might make it a bit more obvious.

Hmm i would not put the *.xml in the distro root. Maybe this would make more sense:

bin/

configuration/

servers/

modules/

README.TXT

AFAIK this should be configurable as well? I mean with this you have the 3 things (configuration, server, modules).

For the domain controller you could basically have, where other members of the domain would only have host.xml:

configuration/

- domain.xml

- host.xml

For standalone we might want think about something like:

configuration/

- server1-standalone.xml

- server2-standalone.xml

[brian.stansberry]

This looks good; thanks.

Yes, the location of things needs to be configurable. Location of configuration/ would have to come via command line, the others could then be in host.xml or -standalone.xml.

[emuckenhuber]

Brian Stansberry wrote:

Yes, the location of things needs to be configurable. Location of configuration/ would have to come via command line, the others could then be in host.xml or -standalone.xml.

Are we going to use ServerManager in the standalone use case as well? Or is there going to be one InstalledImage per server then?

Maybe we also need a (optional) module repository root as boot configuration parameter? We would need that to boot the SM, unless it gets bundled differently.

[brian.stansberry]

Not sure if we'll use ServerManager, but we should support multiple standalone servers running off the same installed image.

Good point about needing to specify the module repo root via command line.