Configuration as Code tooling proposal by ndeloof · Pull Request #111 · jenkinsci/jep

ndeloof · 2018-05-30T09:10:49Z

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

ewelinawilkosz · 2018-05-30T09:26:10Z

jep/0000/README.adoc

+
+This includes:
+
+- tooling to validate configuration, sort of a "dry-run" mode, with adequate diagnostic when some


yes please!

ewelinawilkosz · 2018-05-30T10:07:50Z

issue raised some discussions already and we won't find a silver bullet, but if we have a dry run I can live with proposed solution 👍
also once the plugin becomes mature and popular I assume we can hope plugins' maintainers may consider impact on JCasC when implementing changes

bitwiseman · 2018-05-31T20:31:37Z

@ndeloof Are you asking for commentary from me as a JEP editor or as a contributor?

As an editor, I would say theres a bunch of stuff to be cleaned up (the :bulb: entries) and you need to flesh out the "Specification" section more. Some of that would come from parts of your "Reasoning" section. Description of the design that was chosen and is being implemented goes in the "Specification", discussion of alternate designs that were rejected and explanation as to why goes in the "Reasoning" - See the section descriptions for "Specification" and "Reasoning" in JEP-1.

ndeloof · 2018-05-31T20:42:08Z

@bitwiseman your comment is actually useful for me to understand which information are required for such a JEP. I have to admit this highly standardized process is a new way for me to consider software development

jglick

Is there a reason this is not simply part of JEP-201? From my PoV, if a proposed new feature requires new tooling to be practical, then that is all part of the development of that feature.

(If 201 were final, then a follow-up JEP would of course be the only option.)

jglick · 2018-05-31T20:56:41Z

jep/0000/README.adoc

+| Not Submitted :information_source:
+
+| Type
+| :bulb: Informational :bulb:


None of the proposed types do actually match what I try to express in this JEP. Sounds "Standards" is what is used for this purpose, but I'm not defining a standard here, just exploring the concrete tools that would help JEP-201 adoption.

jglick · 2018-05-31T20:56:59Z

jep/0000/README.adoc

+
+== Abstract
+
+Configuration-as-Code (JEP-201) do describe the mechanisms used to configure a Jenkins master based


s/do describe/describes/

jglick · 2018-05-31T20:57:33Z

jep/0000/README.adoc

+for each and every supported plugin.
+
+This approach comes with some drawback: Any update to Jenkins master's core or plugins will change the
+inferred model, and as such a yaml configuration used a t time might not be valid a t+1. This concern


typos; a → at?

jglick · 2018-05-31T20:59:25Z

jep/0000/README.adoc

+Configuration-as-Code tooling is designed to fill the gap between the raw mechanism defined by JEP-201
+to configure a specific jenkins-core + plugins combination, and the need to keep this configuration
+stable during core or plugin upgrades, or at least detect breaking changes and provide hints to manage
+upgreade.


jglick · 2018-05-31T21:01:02Z

jep/0000/README.adoc

+== Motivation
+
+Configuration-as-Code doesn't define a data model to setup jenkins, it's based on inferring a model
+from live jenkins instance from it's Java API, especially UI data-binding mechanisms. Based on this,


jglick · 2018-05-31T21:09:49Z

jep/0000/README.adoc

+instance. This toolkit do parse the yaml configuration, try to apply configuration on the inferred model,
+and will report issue detected during this dry-run configuration process.
+
+It would rely on breaking changes metadata to offer end-user some guidance on way to address repoerted


jglick · 2018-05-31T21:10:25Z

jep/0000/README.adoc

+=== Before applying configuration
+
+On end-user side we want ot offer a validation toolkit to be used when applying configuration on a jenkins
+instance. This toolkit do parse the yaml configuration, try to apply configuration on the inferred model,


BTW please follow the formatting model of one physical (AsciiDoc) text line per sentence or major phrase. Easier to read diffs and so on.

jglick · 2018-05-31T21:11:56Z

jep/0000/README.adoc

+== Infrastructure Requirements
+
+If approved, Configuration-as-Code tooling to check for API backward compatibility will need to be
+included in the CI process, so it can inform plugin developers and contributors on breaking changes


Meaning what, exactly? That an incompatible change to databinding produces a build failure? Even assuming the other pieces have been developed, this is not trivial as you need to determine a baseline to compare against, which presumably means looking up the most recent Maven release older than the current snapshot.

Good point. I expected to compare with previous commit or pull-request baseline, but this assumes some way to store the inferred model between builds.

You need not necessary “store an inferred model between builds”. You can have a build compute the old model almost as easily as it computes the new model. But you need some way to deterministically identify the “old version”.

jglick · 2018-05-31T21:15:36Z

jep/0000/README.adoc

+plugin developers to document required breaking changes, and validate a configuration for a specific
+jenkins instance before it get actually applied.
+
+== Reasoning


Something not addressed in JEP-201 itself is why you chose to use databinding (~ DescribableModel) as the source of truth, when plugins have traditionally maintained settings compatibility via their XStream form (~ fields, readResolve)—we do presume already that a config.xml which worked in an older “version” of Jenkins can be loaded safely in a newer version. Thus JEP-201 is introducing an additional compatibility constraint: plugin developers need to be aware of, and work around, both models when refactoring settings.

(Pipeline was already imposing a similar constraint for Steps and those Describables being used inside Steps. OTOH it also allows StepDescriptor.newInstance / .uninstantiate to be overridden to customize the process, as I in fact did recently in jenkinsci/docker-workflow-plugin#138. This is not available when sharing code with freestyle via CoreStep / CoreWrapperStep. I think job-dsl also introduced the ability to introspect stuff and pay attention to @Symbol but AFAIK most bindings are still hand-written.)

see https://github.com/jenkinsci/jep/blob/master/jep/201/README.adoc#mimic-web-ui
As we want to translate web UI into -as-code configuration the source of truth is the web UI, so the databinding it uses to translate into java objects.

If you suggest we rely on xml persistence binding as sours of truth, then we need to fully revisit CasC design so it becomes an xml auto-magic templating engine. Maybe this makes sense.

While I would personally favor XML over UI, especially in the face of the blue-ification of Jenkins, going with XML serialized form has essentially the same objection of being tied to a legacy format we'd like to get rid of.

Its pro remains the lesser need for compatibility (and one that has been well established), although the current approach's need for greater awareness of API compatibility could also address problems we occasionally see related to plugins dependencies.

About this consideration to better rely on XStream serialisation as a proven backward compatible model for jenkins data and build configuration-as-code on it : if this is what you're looking for, then you don't need a plugin for this purpose: just commit all your XML files in SCM and you're done.

jglick · 2018-05-31T21:20:39Z

jep/0000/README.adoc

+
+Configuration-as-Code tooling is defined to workaround this limitation by providing a toolset to
+discover such breaking changes early, before the actual production configuration is updated.
+It will help detect breaking changes during jenkins and plugins developement, offer an option for


actually french

ndeloof · 2018-06-01T07:15:01Z

@jglick I proposed another JEP following Jenkins Essentials model to have smaller JEPs focussed on some aspect of a general topic

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

amuniz · 2018-06-11T09:24:40Z

jep/0000/README.adoc

+== Abstract
+
+Configuration-as-Code (JEP-201) describes the mechanisms used to configure a Jenkins master based
+on yaml file(s), by discovering the data model from Java API, without the need to write any "glue-code"


I might be late here, but asking anyways. Is the no "glue-code" design approach already taken?
I think UX is important in APIs, and having all the internal core & plugins model in this public API is bad IMO.

This deserves a whole JEP, but briefly: what about starting a "Define your public API" campaign? If every Describable had a public data API then Configuration as Code (the REST API also and probably others) would benefit from it. Current approach (introspecting describables) could be used as fallback if Describable#getPublicAPI (or the like) is not implemented.

Having a "Configurable" API implemented by all plugin would indeed ensure the API is well handled by plugin maintainer and that it correctly reflects the configurable elements of a plugin, but doing so would require years before we get good coverage from all major plugins (just see how long it took for pipeline adoption).

By the way, this "no glue code" approach, based on UI databing exposed model, is not as bad as you can expect, and easy for plugin maintainer to improve as it relies on the databinding mechanisms they're used to.

@amuniz
What you suggest is not in opposition to avoiding glue-code. The details of this should be discussed in this upcoming JEP submission for Jenkins CasC Schema.

upcoming JEP submission for Jenkins CasC Schema

Sorry, I might be a bit lost... is not the schema already defined? It is using the existing model with @DataBoundContructor/@DataBoundSetter introspection, isn't it?

This will be presented in more details (reasoning, wroakrounds, etc) in #125

…ission

bitwiseman

@ndeloof @ewelinawilkosz
Will one of you be the sponsor of this JEP? That is the last blocker I see right now to this JEP becoming Draft.

Configuration as Code tooling proposal

cc4791c

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

ndeloof mentioned this pull request May 30, 2018

re-accept JEP-201 #108

Closed

ewelinawilkosz reviewed May 30, 2018

View reviewed changes

ewelinawilkosz approved these changes May 30, 2018

View reviewed changes

jglick reviewed May 31, 2018

View reviewed changes

typos

65506c2

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

amuniz reviewed Jun 11, 2018

View reviewed changes

bitwiseman added 2 commits June 15, 2018 17:47

Tweaks and Cleanup

db4c854

Merge remote-tracking branch 'jenkinsci/master' into ndeloof-jep-subm…

8fbba1f

…ission

bitwiseman requested changes Jun 16, 2018

View reviewed changes

bitwiseman added 3 commits July 18, 2018 11:58

Added sponsor

cfb090b

Merge remote-tracking branch 'jenkinsci/master' into jep-submission

0243fea

Approve JEP-208 Draft

4ddf9da

bitwiseman approved these changes Jul 26, 2018

View reviewed changes

bitwiseman merged commit 65b5eca into jenkinsci:master Jul 26, 2018


		This includes:

		- tooling to validate configuration, sort of a "dry-run" mode, with adequate diagnostic when some


		== Abstract

		Configuration-as-Code (JEP-201) do describe the mechanisms used to configure a Jenkins master based

Uh oh!

Comments

Conversation

ndeloof commented May 30, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ewelinawilkosz commented May 30, 2018

Uh oh!

bitwiseman commented May 31, 2018

Uh oh!

ndeloof commented May 31, 2018

Uh oh!

jglick left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ndeloof commented Jun 1, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bitwiseman left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants