Closed brailsmt closed 3 years ago
I don't think its within the scope of this (or any of our cookbooks) to cleanup artifacts between versions. Ideally, this should be done within a wrapper cookbook by a user. If we handled that for every version of our cookbook, when would we be OK to remove code that would clean up older versions of the cookbook? We're a small volunteer team so we try to minimize the amount of code we maintain.
However, we have in some cases at least documented changes between major versions in an UPGRADING.md
doc to help users (see an example in the apache2 cookbook). Perhaps this might be a good place to put such document for other users encountering the issues you're running into.
Would you be interested in creating a PR for such a doc?
From my perspective, as a consumer of the community java cookbook, these issues have made the experience of using the cookbook painful. I think it is a reasonable expectation that when I consume a cookbook, upgrades between versions are facilitated, in some way, by the cookbook itself. At the very least, I would expect documentation and a failure mechanism that looks for old artifacts and fails fast, rather than succeed in a state that is potentially harmful. In our case, we were surprised several times that a successful chef-client run did not result in the correct installation of java using the java install resources provided in sous-chef/java. This was especially surprising since we were upgrading from a previous version. The implementation of the cookbook changed significantly between v4.0.0 and v8.4.0. The effort to troubleshoot these issues was significant, and I think it is worthwhile addressing them here to prevent all consumers from encountering the same issues in practice. As our efforts to uplift to chef 16 wraps up, I will see if I can create some PRs based on our work that we can contribute back to the community and which will address the issues we found.
While there is an expectation of compatibility within a major version of a cookbook the act of incrementing that major version is to indicate a breaking change and it is the responsibility of the consumer to ensure compatibility in its usage.
So to echo @ramereth, ideally an UPGRADING.md
would be maintained to highlight what those breaking changes are and how to address them as you progress through the major versions. Expecting that the codebase handles the configuration of all previous versions is unrealistic.
I apologise for the delay in responding, I've been quite busy with uplifting all our cookbooks and environments to chef 16. I feel that it is worthwhile to ensure that a consumer upgrading versions does not result in inconsistent states on the node, even if it is a major version upgrade. However, if the maintainers have decided that the cookbook will take a hands off approach to consumers upgrading and will only provide documentation, then I'm not sure there is a point to submitting a pull request with proposed changes. If you are interested, let me know and I will see what I can do to contribute the work we did back to the community so others may benefit.
@brailsmt the introduction of an UPGRADING.md would be really helpful and greatly received.
In your case you went up 4 major versions, which has it's own problems. If you're able pin down changes to needed to make for each major and document that in the UPGRADING doc that would be great!
Closing as I'm now considering this resolved.
I view this as a much larger issue than just documentation. As the maintainers don't share the same view, I don't feel that contributions to resolve the issues would be well received, so I have moved on to other issues/tasks.
@brailsmt I think I'm missing something here, what else apart from docs do you think we're missing here? The feedback will most likely help us guide how we upgrade cookbooks in the future šš¼
:speaking_head: Foreword
We are uplifting all our cookbooks to chef 16. As part of that effort, we have upgraded from the v4.0.0 version of the cookbook to the v8.4.0 version. When doing this uplift we encountered several issues described below.
:ghost: Brief Description
When uplifting to chef 16 from chef 14, we upgraded from v4.0.0 to v8.4.0 we experienced the following issues after uplifting nodes to chef 16 and re-running chef-client:
649 The cookbook failed to install an upgraded version of java due to the symlink created with v4.0.0
node['java']['jdk_version']
.:pancakes: Cookbook version
We were upgrading from v4.0.0 to v8.4.0.
:woman_cook: Chef-Infra Version
:tophat: Platform details
Steps To Reproduce
A lot of steps involved in uplifting nodes from chef 14 to 16. The relevant, high level changes are:
create a new java recipe that is a thin wrapper around the adoptopenjdk_install resource to install java, since there is no longer a recipe included in v8.4.0. The recipe for the thin wrapper was initially, naively implemented as:
:police_car: Expected behavior
The v8.4.0 recipe should account for the workflow of upgrading from older versions of the java cookbook. This includes clean-up of artifacts from previous installations that would cause issues, allow java version upgrades similar to previous versions, and providing like for like features such as notifications when the jdk version changes.
:heavy_plus_sign: Additional context
Add any other context about the problem here. e.g. related issues or existing pull requests.