Ben Spead · Oct 8

Best practice for CPF Merge and version control

I have been reviewing the details on the CPF Merge functionality offered in IRIS:

I love the frequent mentions of versioning the CPF merge files in Source control.  One thing that is not yet clear to me is how this would work for rolling back a change:

"That way, assuming you version and store the merge files you employ, you can maintain a record of the configuration of each instance through time, enabling rollback if required, and avoid the possibility of configuration merge overwriting changes made by other means"

As I understand it, the CPF Merge file contains the changes from the default CFP file, so it you change the routine buffers in version one of the file, you could then change gmheap in version #2 by adding a new line to what was in #1.  If you change the Web Application Security in #3 and then realize that it was a mistake and need to roll it back quickly, if you roll back in Source control to #2, I believe that would just take the lines changing the security out of the CPF Merge file, but would applying that merge change it back to the prior setting?  Since that change is already merged into the main CPF file wouldn't the user have to be versioning the resulting CPF file following each merge in order to be able to do a rollback to a prior configuration?  Or am I missing something?

Note- this is specially for updating running instances and not for spinning up new instances (obviously the rollback would work in that case as the new instance would have never received the change).

cc: @Luca Ravazzolo 

Product version: IRIS 2021.1
2 0 3 116
Log in or sign up to continue

Hi Ben,

Thanks for the pertinent question.

First of all the CPF merge feature is available for containerized and traditional tarball-based installations and configuration. I want to call that out as at times that is unclear in people's mind.

The CPF merge feature allows you to define and apply a delta to your present instance configuration (initial from an install or otherwise from day2). As we know, an instance configuration is described in the Configuration Parameter File or CPF that show us (output mainly) the parameters with which the instance is running.

The CPF merge feature supports CRUD operations and is idempotent. That is useful for three reasons IMO

  1. I can Delete or Update resource settings from the outset (day1). There might be settings that are not desired in a new installation
  2. I can Update a single property from day2. All I would need to do is simply add the modification to the same declaration and stamping it as v2.0
  3. It maps directly to InterSystems IRIS internal operational classes so we know the API is robust

Therefore, if a specific property or resource is not desired anymore, your #3 in your example, by modifying the Web Application Security with an Update/Modify operation or deleting it completely, you would return to your latest state of #2. IOW other settings are not affected.

Your single-instance, single source of truth is still the CPF file.

For an initial list of the CRUD operations see the [Actions] page. Please note how the official list will grow as we will be able to run more tests. 

Let me know if this is helpful.

thanks @Luca Ravazzolo  ... so in the case of day2 operations you really can't take the source control rollback approach to back out the change to default behavior... unless you are versioning you CPF files post CPF Merge, you must do another CPF Merge change, and know what the prior values were in order to actually revert the change in the environmental, correct?

Hi Ben,

The short answer is yes, you are correct.

The longer one :-)
Stating the obvious, from a tool point of view, to be able to rollback operations means understanding the present state of an instance and of course have a record of all the previous states. In order to be able to do that one needs the concept of a "release state". As soon as you get into maintaining state you quickly escalate the complexity of a solution. See Terraform for example and ICM itself that supports the replication of its state via Consul.

There are tools like Helm, ArgoCd, etc. that help in that, however that is left to the user. Enhancing InterSystems IRIS is an option but that is not available now. At present we rely on a GitOps approach. 

GitOps is a paradigm that incorporates best practices applied to the application development workflow all the way to the operating infrastructure of a system.

Embracing GitOps give us some benefits like:

  • Deploying faster and more often (with a DB we could argue those adjectives, nevertheless we can still appreciate the benefits)
  • Easier and quicker error handling and recovery
  • Self documenting deployments
  • Increased developer productivity and an enhanced experience for teams
  • Greater visibility on the lifecycle of developed features

However, GitOps itself is not the delivery & deployment panacea of this complex area. GitOps has issues too. There are shortcomings when auto-scaling and dynamic resources are implemented; there is no standard for managing secrets; observability is immature; rollbacks don't have a standard practice, etc.

The powerful CRUD operations that we can run with the CPF merge feature adds to the complexity. A solution needs to be implemented that may leverage one or more tools that organizations use in their automated provisioning pipeline, just like you would do when embracing the GitOps paradigm.

I think there are two ways to solve our rollback issue, at present.
The first one would be a programmatic approach, maybe a diff operation on the git hash declarations of (last_op_def) vs (last_op_def  -  1)
If last_op_def contains a Create-resource I then need to rollback that with a Delete-resource or Modify-resource. And even in this simple case how do you determine that? Human intervention is probably needed.

The second option, simpler and safer, would be to simply re-run the container, the base state we know, and apply configuration settings #1 and #2 only.

There are probably other options involving verifying the CPF file. However, the present CPF file does not hold all of an instance settings.
There are also other issues to these type of automations, like: what if you want to rollback after the creation of a database and data was written to it?

It's complex.