Suggestion: versioning the schema for Configuration as Code

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
22 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Suggestion: versioning the schema for Configuration as Code

R. Tyler Croy
I was thinking about this last week when I was working with Configuration as
Code[0] and thinking about some of the concerns which I've seen voiced about
the "right API for 1.0", especially around Credentials and some other
(currently) gnarly syntax use-cases.

As a user of docker-compose, I find their approach for handling
the changes of their docker-compose.yml format to be quite elegant[1]. They
include a `version: 3` key at the root level of the YAML and then make it
clear in their documentation which versions of docker-compose can make use of
which versions of their schema.

I think this could be helpful for avoiding concerns about the "finality" of a
1.0 release. If the syntax needs to change in the future, just creating a
schema version 2, which can be consumed from a 1.1, or 1.2 release of plugin
would be very reasonable IMHO.



Thought I would share the idea.




[0] https://github.com/jenkinsci/configuration-as-code-plugin
[1] https://docs.docker.com/compose/compose-file/compose-versioning/

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/20180510201923.GF2935%40grape.lasagna.io.
For more options, visit https://groups.google.com/d/optout.

signature.asc (201 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Jesse Glick-4
I had the same comment about Declarative Pipeline before it went
1.0—that every script should start with

pipeline(1) {

But to no avail. :-(

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr1ARV%2Br1u98umpjCZBvd2%3Dh7msQ1TQFTUvbhpoGPc%3Dz6g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
not so simple :

configuration-as-code schema depends on jenkins-core version and all plugins version being installed. So generating a "version" would be hard.
Credentials syntax used in alpha is here for demonstration purpose, with minimal lines of code to provide this feature, I expect we remove this code from CasC as we release 1.0 so it can be implemented by credentials plugin its own way.

2018-05-10 22:30 GMT+02:00 Jesse Glick <[hidden email]>:
I had the same comment about Declarative Pipeline before it went
1.0—that every script should start with

pipeline(1) {

But to no avail. :-(

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr1ARV%2Br1u98umpjCZBvd2%3Dh7msQ1TQFTUvbhpoGPc%3Dz6g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJzm8Ff02gutr69y9eyUxu1%3D01J6LhhBozKnhPC6ytbhNwA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
To get more into details :

docker-compose has it's own data model and translates into docker API calls. Doing so it can support model versions for config file, as well as adapt when required to underlying docker API Changes

configuration-as-code has been designed as a "no glue code" model : we don't write a single line of code for configuration attribute of plugin X to be supported, everything is based on runtime discovery by reflexion. This design allows to support (mostly) all plugins out-of-the-box, but the price to pay is that there's no "model" but the one discovered at runtime : if you upgrade a plugin which refactored it's databound "API" then the configuraiton schema will change as well.

In some "as-code" process we expect such upgrade would be tested before being pushed to production master, so that model changes would be detected before. CasC do already report unknown attributes and fail fast. But afaik there's nothing much we can offer here.

2018-05-11 9:29 GMT+02:00 nicolas de loof <[hidden email]>:
not so simple :

configuration-as-code schema depends on jenkins-core version and all plugins version being installed. So generating a "version" would be hard.
Credentials syntax used in alpha is here for demonstration purpose, with minimal lines of code to provide this feature, I expect we remove this code from CasC as we release 1.0 so it can be implemented by credentials plugin its own way.

2018-05-10 22:30 GMT+02:00 Jesse Glick <[hidden email]>:
I had the same comment about Declarative Pipeline before it went
1.0—that every script should start with

pipeline(1) {

But to no avail. :-(

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr1ARV%2Br1u98umpjCZBvd2%3Dh7msQ1TQFTUvbhpoGPc%3Dz6g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJz%3DOUswr3u4U07zQeFQn6fTJXPUn9A17fdGyV4dE4whQTg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Jesse Glick-4
In reply to this post by nicolas de loof-2
On Fri, May 11, 2018 at 3:29 AM, nicolas de loof
<[hidden email]> wrote:
> configuration-as-code schema depends on jenkins-core version and all plugins
> version being installed. So generating a "version" would be hard.

I think you are mixing up two things. One is the physical layout of
the config file and how various YAML attributes are mapped to
`Describable`s and that sort of thing, which is not likely to change
frequently, but might. That deserves a version number.

The other thing is the concrete list of identifiers available in your
system, which of course will vary depending on the versions of
components.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr111z%2BNFBAnHQFT%2BFELRsNWU5-j2OB1XemUwu6JpLVjKA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
I don't get your point

the physical layout of the yaml file is directly built based on component discovery
YAML attributes are mapped to `Describable`s and other components based on how we can access them from root "jenkins" object (and other root elements). This mapping is not defined by CasC but by discovery from live jenkins instance model. 

i.e we discover "jenkins" has a "securityRealm" attribute and some implementation can be used to set this attribute. This directly defines the yaml tree. But the codebase has no reference to this structure.

2018-05-11 17:05 GMT+02:00 Jesse Glick <[hidden email]>:
On Fri, May 11, 2018 at 3:29 AM, nicolas de loof
<[hidden email]> wrote:
> configuration-as-code schema depends on jenkins-core version and all plugins
> version being installed. So generating a "version" would be hard.

I think you are mixing up two things. One is the physical layout of
the config file and how various YAML attributes are mapped to
`Describable`s and that sort of thing, which is not likely to change
frequently, but might. That deserves a version number.

The other thing is the concrete list of identifiers available in your
system, which of course will vary depending on the versions of
components.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr111z%2BNFBAnHQFT%2BFELRsNWU5-j2OB1XemUwu6JpLVjKA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJznEOzzj6AGwuCiud_BsiFeEKuJDMDwjzentdT9zmkNDdw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Jesse Glick-4
On Fri, May 11, 2018 at 11:14 AM, nicolas de loof
<[hidden email]> wrote:
> we discover "jenkins" has a "securityRealm" attribute and some
> implementation can be used to set this attribute. This directly defines the
> yaml tree. But the codebase has no reference to this structure.

Right. So, again, the version would not be referring to the existence
or semantics of a `securityRealm` attribute. It would be referring to
the logic that governs how the `Jenkins.getSecurityRealm()` method is
mapped to a YAML attribute of that name, and how a particular
`SecurityRealm` subtype is identified in its value. Now the case of
the attribute name is pretty simple, of course—JavaBeans naming
convention—but there can be more subtle cases: handling of symbol
annotations or lack of them (which already comes up in the handling of
`ldap` in this example!), collection types, getter/setter/constructor
type mismatches, handling of secrets¹, convenience aliases, deprecated
members, and so on.

Experience with the `structs` plugin and its binding to Pipeline
Script in `workflow-cps` indicates that there are plenty of hard
problems to solve and it is not uncommon for the surface syntax to
need to be changed in response. For Pipeline (talking about Scripted
now) we never had a formal “language version” or anything like that,
which has caused plenty of headaches trying to maintain compatibility
with old scripts. I think JCasC will hit analogous issues.


¹Whenever that is actually formalized. As it needs to be, IMO, for
1.0—you cannot just say that the Credentials plugin maintainer is
going to solve this for you.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr23zwVvy3RQxD7F_POsgDZxMtSt2vgM%3DGugGF913RTS%2Bw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

stephenconnolly

On Fri 11 May 2018 at 17:32, Jesse Glick <[hidden email]> wrote:
On Fri, May 11, 2018 at 11:14 AM, nicolas de loof
<[hidden email]> wrote:
> we discover "jenkins" has a "securityRealm" attribute and some
> implementation can be used to set this attribute. This directly defines the
> yaml tree. But the codebase has no reference to this structure.

Right. So, again, the version would not be referring to the existence
or semantics of a `securityRealm` attribute. It would be referring to
the logic that governs how the `Jenkins.getSecurityRealm()` method is
mapped to a YAML attribute of that name, and how a particular
`SecurityRealm` subtype is identified in its value. Now the case of
the attribute name is pretty simple, of course—JavaBeans naming
convention—but there can be more subtle cases: handling of symbol
annotations or lack of them (which already comes up in the handling of
`ldap` in this example!), collection types, getter/setter/constructor
type mismatches, handling of secrets¹, convenience aliases, deprecated
members, and so on.

Experience with the `structs` plugin and its binding to Pipeline
Script in `workflow-cps` indicates that there are plenty of hard
problems to solve and it is not uncommon for the surface syntax to
need to be changed in response. For Pipeline (talking about Scripted
now) we never had a formal “language version” or anything like that,
which has caused plenty of headaches trying to maintain compatibility
with old scripts. I think JCasC will hit analogous issues.


¹Whenever that is actually formalized. As it needs to be, IMO, for
1.0—you cannot just say that the Credentials plugin maintainer is
going to solve this for you.

Yeah, I advise against relying on me to fix schema version problems for you :-P


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr23zwVvy3RQxD7F_POsgDZxMtSt2vgM%3DGugGF913RTS%2Bw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
--
Sent from my phone

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CA%2BnPnMwB%2BBCH2M5GiyfLiudpx%2Biaxchq7ZzbFi5hCeGccKuPBA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
you get it wrong : what I'm saying is that the exposed yaml model to configure credentials should be defined as part of credential plugin, not by me within configuration-as-code. The existing code is there to demonstrate we _can_ support credentials despite it's weird design (!) with some reasonable code, but actual credentials support is under credentials-plugin responsibility (also to consider this should follow credentials-plugin version, not configuration-as-code release cycles)

2018-05-11 21:23 GMT+02:00 Stephen Connolly <[hidden email]>:

On Fri 11 May 2018 at 17:32, Jesse Glick <[hidden email]> wrote:
On Fri, May 11, 2018 at 11:14 AM, nicolas de loof
<[hidden email]> wrote:
> we discover "jenkins" has a "securityRealm" attribute and some
> implementation can be used to set this attribute. This directly defines the
> yaml tree. But the codebase has no reference to this structure.

Right. So, again, the version would not be referring to the existence
or semantics of a `securityRealm` attribute. It would be referring to
the logic that governs how the `Jenkins.getSecurityRealm()` method is
mapped to a YAML attribute of that name, and how a particular
`SecurityRealm` subtype is identified in its value. Now the case of
the attribute name is pretty simple, of course—JavaBeans naming
convention—but there can be more subtle cases: handling of symbol
annotations or lack of them (which already comes up in the handling of
`ldap` in this example!), collection types, getter/setter/constructor
type mismatches, handling of secrets¹, convenience aliases, deprecated
members, and so on.

Experience with the `structs` plugin and its binding to Pipeline
Script in `workflow-cps` indicates that there are plenty of hard
problems to solve and it is not uncommon for the surface syntax to
need to be changed in response. For Pipeline (talking about Scripted
now) we never had a formal “language version” or anything like that,
which has caused plenty of headaches trying to maintain compatibility
with old scripts. I think JCasC will hit analogous issues.


¹Whenever that is actually formalized. As it needs to be, IMO, for
1.0—you cannot just say that the Credentials plugin maintainer is
going to solve this for you.

Yeah, I advise against relying on me to fix schema version problems for you :-P


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr23zwVvy3RQxD7F_POsgDZxMtSt2vgM%3DGugGF913RTS%2Bw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
--
Sent from my phone

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CA%2BnPnMwB%2BBCH2M5GiyfLiudpx%2Biaxchq7ZzbFi5hCeGccKuPBA%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJz%3DfvStFRYJVGJYF19J56BYF2GQhDVfmXbtxz26qi40H1A%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Jesse Glick-4
On Fri, May 11, 2018 at 3:33 PM, nicolas de loof
<[hidden email]> wrote:
> the exposed yaml model to
> configure credentials should be defined as part of credential plugin, not by
> me within configuration-as-code.

Well. JCasC likely needs some special handling for `Secret`, which
`credentials` uses for the actual secrets inside. Beyond that, I agree
that it makes sense for the specialized binding to ultimately live in
`credentials-plugin`.

But I take issue with two ways this was framed. First of all, there is
nothing wrong with the design of credentials storage; it is sensible
given the expected usage model. JCasC makes it easy to autobind
configuration that lives all in one configuration screen. In this
case, the UI is divided into different screens with a specialized UI,
so specialized binding would be needed.

Second, yes it needs to be defined “by you” (well, by whomever is
striving to get JEP-201 accepted). Credentials are central to Jenkins
setup and a critical use case for JEP-201. And JEP-201 is a new
feature, so its developers are responsible for designing and
implementing appropriate integrations with existing foundational
components of Jenkins.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr0eorvLJovVf9Fbut-zt0F9zDSvF_v0qa0ZsUrrz%2BoNAg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2


2018-05-11 23:02 GMT+02:00 Jesse Glick <[hidden email]>:
On Fri, May 11, 2018 at 3:33 PM, nicolas de loof
<[hidden email]> wrote:
> the exposed yaml model to
> configure credentials should be defined as part of credential plugin, not by
> me within configuration-as-code.

Well. JCasC likely needs some special handling for `Secret`, which
`credentials` uses for the actual secrets inside. Beyond that, I agree
that it makes sense for the specialized binding to ultimately live in
`credentials-plugin`.

Secret is already supported based on jenkins-core registered stapler converters.
 

But I take issue with two ways this was framed. First of all, there is
nothing wrong with the design of credentials storage; it is sensible
given the expected usage model. JCasC makes it easy to autobind
configuration that lives all in one configuration screen. In this
case, the UI is divided into different screens with a specialized UI,
so specialized binding would be needed.

CasC is designed to manage data as a tree, which jenkins UI use to adopt. But not credentials-plugin relying on Maps and singletons.
 

Second, yes it needs to be defined “by you” (well, by whomever is
striving to get JEP-201 accepted). Credentials are central to Jenkins
setup and a critical use case for JEP-201. And JEP-201 is a new
feature, so its developers are responsible for designing and
implementing appropriate integrations with existing foundational
components of Jenkins.

I strongly disagree with this. From my perspective JEP-201 is about generic mechanism to support configuration-as-code without glue code and option for custom adapters where required. Credentials is for sure a central piece of Jenkins, like pipeline is, or arguably many other plugins. But it's not JEP-201 to define how those should be exposed as a configurable data model. Maybe this should be discussed in a subsequent JEP if you consider this _that_ important. From my point of view this could be addressed within credentials plugin taking the decision on the model it want to expose and provide the required glue-code. 
 

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr0eorvLJovVf9Fbut-zt0F9zDSvF_v0qa0ZsUrrz%2BoNAg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJzk5ZoqFYbV4HgK1k5FahDUe9EHF3V2wQODtQKfEOZ33CQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
Let me try to convince you with a comparison :

Pipeline is a central piece of Jenkins, and support for Git SCM in this context is a MUST HAVE. In early days "git" DSL step was actually implemented in pipeline plugin, but this later has been moved to git-plugin, where it perfectly make sense, so that design changes in git-plugin can be applied to "git" step in sync, and pipeline plugin just becomes a backbone for other steps (so the large amount of pipeline-*-steps plugins.

I'd like configuration-as-code to use the same approach : only provide the backbone for configuration support, then have everything specific to a plugin moved to target codebase, where it can be managed in sync.  

2018-05-11 23:44 GMT+02:00 nicolas de loof <[hidden email]>:


2018-05-11 23:02 GMT+02:00 Jesse Glick <[hidden email]>:
On Fri, May 11, 2018 at 3:33 PM, nicolas de loof
<[hidden email]> wrote:
> the exposed yaml model to
> configure credentials should be defined as part of credential plugin, not by
> me within configuration-as-code.

Well. JCasC likely needs some special handling for `Secret`, which
`credentials` uses for the actual secrets inside. Beyond that, I agree
that it makes sense for the specialized binding to ultimately live in
`credentials-plugin`.

Secret is already supported based on jenkins-core registered stapler converters.
 

But I take issue with two ways this was framed. First of all, there is
nothing wrong with the design of credentials storage; it is sensible
given the expected usage model. JCasC makes it easy to autobind
configuration that lives all in one configuration screen. In this
case, the UI is divided into different screens with a specialized UI,
so specialized binding would be needed.

CasC is designed to manage data as a tree, which jenkins UI use to adopt. But not credentials-plugin relying on Maps and singletons.
 

Second, yes it needs to be defined “by you” (well, by whomever is
striving to get JEP-201 accepted). Credentials are central to Jenkins
setup and a critical use case for JEP-201. And JEP-201 is a new
feature, so its developers are responsible for designing and
implementing appropriate integrations with existing foundational
components of Jenkins.

I strongly disagree with this. From my perspective JEP-201 is about generic mechanism to support configuration-as-code without glue code and option for custom adapters where required. Credentials is for sure a central piece of Jenkins, like pipeline is, or arguably many other plugins. But it's not JEP-201 to define how those should be exposed as a configurable data model. Maybe this should be discussed in a subsequent JEP if you consider this _that_ important. From my point of view this could be addressed within credentials plugin taking the decision on the model it want to expose and provide the required glue-code. 
 

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr0eorvLJovVf9Fbut-zt0F9zDSvF_v0qa0ZsUrrz%2BoNAg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJzm%3DYi3t%3DauTxD076fuqGJBzndf6ZCYnvz_bP-rkZFntgA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Daniel Beck
In reply to this post by nicolas de loof-2

> On 11. May 2018, at 17:14, nicolas de loof <[hidden email]> wrote:
>
> I don't get your point
>
> the physical layout of the yaml file is directly built based on component discovery
> YAML attributes are mapped to `Describable`s and other components based on how we can access them from root "jenkins" object (and other root elements). This mapping is not defined by CasC but by discovery from live jenkins instance model.
>
> i.e we discover "jenkins" has a "securityRealm" attribute and some implementation can be used to set this attribute. This directly defines the yaml tree. But the codebase has no reference to this structure.

Some stuff is still defined by CasC, otherwise https://github.com/jenkinsci/configuration-as-code-plugin/pull/62 wouldn't exist.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/38388CD1-DF9E-4DB9-B22E-B4A0F47ACC8D%40beckweb.net.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
yes indeed.
But I also would like this specific seed-job support to move to job-dsl plugin, so the way this configuration element is used is directly managed by job-dsl plugin version
 

2018-05-13 1:36 GMT+02:00 Daniel Beck <[hidden email]>:

> On 11. May 2018, at 17:14, nicolas de loof <[hidden email]> wrote:
>
> I don't get your point
>
> the physical layout of the yaml file is directly built based on component discovery
> YAML attributes are mapped to `Describable`s and other components based on how we can access them from root "jenkins" object (and other root elements). This mapping is not defined by CasC but by discovery from live jenkins instance model.
>
> i.e we discover "jenkins" has a "securityRealm" attribute and some implementation can be used to set this attribute. This directly defines the yaml tree. But the codebase has no reference to this structure.

Some stuff is still defined by CasC, otherwise https://github.com/jenkinsci/configuration-as-code-plugin/pull/62 wouldn't exist.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/38388CD1-DF9E-4DB9-B22E-B4A0F47ACC8D%40beckweb.net.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJz%3D6kGMkft8KUUp9d9t2zL%3DbArQkfFJgdSz25-d0VWfODw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Jesse Glick-4
In reply to this post by nicolas de loof-2
On Fri, May 11, 2018 at 5:44 PM, nicolas de loof
<[hidden email]> wrote:
> Secret is already supported based on jenkins-core registered stapler
> converters.

Yes; my point was only that due to the nature of secrets, JCasC needs
to support keeping the actual values separate from the main YAML file
somehow—whether via a generic variable interpolation system, or
symmetric encryption, etc. This is already part of the reference
implementation, which is good.

>> JEP-201 is a new
>> feature, so its developers are responsible for designing and
>> implementing appropriate integrations with existing foundational
>> components of Jenkins.
>
> I strongly disagree with this. From my perspective JEP-201 is about generic
> mechanism to support configuration-as-code without glue code and option for
> custom adapters where required.

Yes, that is fine.

> Maybe this should be discussed in a subsequent JEP if you consider this
> _that_ important.

Perhaps, but my perspective is that a JEP should be reasonably
self-contained and define enough detail to implement an MVP, which
would certainly include support for credentials. If you defer this
aspect to an unspecified future JEP then there is a risk that this
planning either gets dropped, or that the integration turns out to
require fundamental design changes which are difficult to retrofit. In
other words, a JEP should describe a complete user story.

Obviously there are plenty of plugins which should just have routine
integration with JCasC—fully automatic or with minor changes. But we
can reasonably expect that the endpoint configuration for the Aqua
Security Scanner plugin (whatever that is) could be managed without
“interesting” issues arising, and anyway most users of JCasC would not
be using this plugin.

The Pipeline comparison is a little tough, since the core design there
long preceded the JEP process and was not formalized well, but the
analogy works so far as we are discussing modularity of code. For
example, the `withCredentials` step is indeed implemented in a
distinct credentials-related plugin, but there were some subtle
aspects that mandated special treatment elsewhere: the environment
variables in a block in `program.dat` needed to be kept encrypted,
which required API changes; and Blue Ocean needs to know to hide
secrets from step summaries, which also required special consideration
in other components.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr2Rck8R9gqd6Dw8v30NsumqM6dTe-ui%2BmvnrXnpe_SVOw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

Liam Newman
Nicolas, 

Moving things to a separate JEP makes sense is some cases but it doesn't sound like the works here.  The design choices that need to be made in relation to credentials CasC will effect the design of the JEP-201.  Many plugins could be done in later JEPs, but for concepts as key as Credentials they would at least need to be concurrent JEPs and would need to be owned 

Putting all that aside (as that is not the original point of this thread), the original suggestion was to include a version field in the CasC YAML.  You said it would not work because the version would have to take into account the core version and versions of all plugins, otherwise it might break. Does that mean the CasC YAML could break _any time_  I upgrade any component? Doesn't that rather defeats the purpose of CasC?  

If anything all this strengthens the argument for having at least a top-level version field that guarantees some level of compatibility (perhaps at Jenkins Core API level).  It further suggests that the CasC needs to include some guidance/structure for talking about CasC YAML changes.  "No glue code" sounds great from a code/plugin-developer perspective, but it is sounding more and more like a anti-feature from user perspective.  

For v1.0, I suppose one could argue that this is a needed design choice to ship in non-infinite time, but that doesn't mean it can be completely ignored.  Some thought will still need to be given to how to ease this pain or at least measure and clearly communicate how often breaks would have occurred in the last year if CasC had been around.

-L. 








On Monday, May 14, 2018 at 8:22:53 AM UTC-7, Jesse Glick wrote:
On Fri, May 11, 2018 at 5:44 PM, nicolas de loof
<<a href="javascript:" target="_blank" gdf-obfuscated-mailto="4_3skfJ2BwAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">nicolas...@...> wrote:
> Secret is already supported based on jenkins-core registered stapler
> converters.

Yes; my point was only that due to the nature of secrets, JCasC needs
to support keeping the actual values separate from the main YAML file
somehow—whether via a generic variable interpolation system, or
symmetric encryption, etc. This is already part of the reference
implementation, which is good.

>> JEP-201 is a new
>> feature, so its developers are responsible for designing and
>> implementing appropriate integrations with existing foundational
>> components of Jenkins.
>
> I strongly disagree with this. From my perspective JEP-201 is about generic
> mechanism to support configuration-as-code without glue code and option for
> custom adapters where required.

Yes, that is fine.

> Maybe this should be discussed in a subsequent JEP if you consider this
> _that_ important.

Perhaps, but my perspective is that a JEP should be reasonably
self-contained and define enough detail to implement an MVP, which
would certainly include support for credentials. If you defer this
aspect to an unspecified future JEP then there is a risk that this
planning either gets dropped, or that the integration turns out to
require fundamental design changes which are difficult to retrofit. In
other words, a JEP should describe a complete user story.

Obviously there are plenty of plugins which should just have routine
integration with JCasC—fully automatic or with minor changes. But we
can reasonably expect that the endpoint configuration for the Aqua
Security Scanner plugin (whatever that is) could be managed without
“interesting” issues arising, and anyway most users of JCasC would not
be using this plugin.

The Pipeline comparison is a little tough, since the core design there
long preceded the JEP process and was not formalized well, but the
analogy works so far as we are discussing modularity of code. For
example, the `withCredentials` step is indeed implemented in a
distinct credentials-related plugin, but there were some subtle
aspects that mandated special treatment elsewhere: the environment
variables in a block in `program.dat` needed to be kept encrypted,
which required API changes; and Blue Ocean needs to know to hide
secrets from step summaries, which also required special consideration
in other components.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/f10a6015-ddd6-476d-bddb-c9c4e7658329%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2


2018-05-15 0:20 GMT+02:00 Liam Newman <[hidden email]>:
Nicolas, 

Moving things to a separate JEP makes sense is some cases but it doesn't sound like the works here.  The design choices that need to be made in relation to credentials CasC will effect the design of the JEP-201.  Many plugins could be done in later JEPs, but for concepts as key as Credentials they would at least need to be concurrent JEPs and would need to be owned 

As I tried to explain, credentials-plugin support is already there, just the syntax used by the configurator has been debated and this is really an implementation detail. I would have a strong -1 to define the adopted syntax in JEP-201. JEP-201 is here to define how we ensure this is feasible (like for any other component) and for this purpose we don't need anything special to be said about credentials plugin.

About "Credentials" in the sense of "secrets" we already have external secret source support. This is a topic we could add some informations about.
 

Putting all that aside (as that is not the original point of this thread), the original suggestion was to include a version field in the CasC YAML.  You said it would not work because the version would have to take into account the core version and versions of all plugins, otherwise it might break. Does that mean the CasC YAML could break _any time_  I upgrade any component? Doesn't that rather defeats the purpose of CasC?  

Yes indeed. CasC doesn't have it's own model, everything is based on actual java code discovery at runtime. So upgrading core or any plugin is changing this model. CasC targets reproducibility and immutability use-cases. If you want to upgrade anything you need to test it before.
 

If anything all this strengthens the argument for having at least a top-level version field that guarantees some level of compatibility (perhaps at Jenkins Core API level).  It further suggests that the CasC needs to include some guidance/structure for talking about CasC YAML changes.  "No glue code" sounds great from a code/plugin-developer perspective, but it is sounding more and more like a anti-feature from user perspective.  

Sure, but then you need to write and maintain 1500 glue-code adapters. This is something we don't want to. This always has been a key topic to drive this effort. I'm sorry to ear this drawback wasn't clearer to you, was pretty obvious to me. There's nothing like free lunch; and no model / glue code means there's nothing we can parse as "v1.0" while we try to configure "v2.0", so a version number wouldn't help here.

 

For v1.0, I suppose one could argue that this is a needed design choice to ship in non-infinite time, but that doesn't mean it can be completely ignored.  Some thought will still need to be given to how to ease this pain or at least measure and clearly communicate how often breaks would have occurred in the last year if CasC had been around.

Hard to tell, but probably on a regular basis. At least any time a major plugin did changed it's UI binding (DataBoundConstructor).
 

-L. 








On Monday, May 14, 2018 at 8:22:53 AM UTC-7, Jesse Glick wrote:
On Fri, May 11, 2018 at 5:44 PM, nicolas de loof
<[hidden email]> wrote:
> Secret is already supported based on jenkins-core registered stapler
> converters.

Yes; my point was only that due to the nature of secrets, JCasC needs
to support keeping the actual values separate from the main YAML file
somehow—whether via a generic variable interpolation system, or
symmetric encryption, etc. This is already part of the reference
implementation, which is good.

>> JEP-201 is a new
>> feature, so its developers are responsible for designing and
>> implementing appropriate integrations with existing foundational
>> components of Jenkins.
>
> I strongly disagree with this. From my perspective JEP-201 is about generic
> mechanism to support configuration-as-code without glue code and option for
> custom adapters where required.

Yes, that is fine.

> Maybe this should be discussed in a subsequent JEP if you consider this
> _that_ important.

Perhaps, but my perspective is that a JEP should be reasonably
self-contained and define enough detail to implement an MVP, which
would certainly include support for credentials. If you defer this
aspect to an unspecified future JEP then there is a risk that this
planning either gets dropped, or that the integration turns out to
require fundamental design changes which are difficult to retrofit. In
other words, a JEP should describe a complete user story.

Obviously there are plenty of plugins which should just have routine
integration with JCasC—fully automatic or with minor changes. But we
can reasonably expect that the endpoint configuration for the Aqua
Security Scanner plugin (whatever that is) could be managed without
“interesting” issues arising, and anyway most users of JCasC would not
be using this plugin.

The Pipeline comparison is a little tough, since the core design there
long preceded the JEP process and was not formalized well, but the
analogy works so far as we are discussing modularity of code. For
example, the `withCredentials` step is indeed implemented in a
distinct credentials-related plugin, but there were some subtle
aspects that mandated special treatment elsewhere: the environment
variables in a block in `program.dat` needed to be kept encrypted,
which required API changes; and Blue Ocean needs to know to hide
secrets from step summaries, which also required special consideration
in other components.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/f10a6015-ddd6-476d-bddb-c9c4e7658329%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJzmGeVxVOYspPfejQ%2BxgWUFuTFdbObeU%2BTMZGZU_KJUCrQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

R. Tyler Croy
(replies inline)

On Tue, 15 May 2018, nicolas de loof wrote:

> 2018-05-15 0:20 GMT+02:00 Liam Newman <[hidden email]>:
>
> >
> > Putting all that aside (as that is not the original point of this thread),
> > the original suggestion was to include a version field in the CasC YAML.
> > You said it would not work because the version would have to take into
> > account the core version and versions of all plugins, otherwise it might
> > break. Does that mean the CasC YAML could break _any time_  I upgrade any
> > component? Doesn't that rather defeats the purpose of CasC?
> >
>
> Yes indeed. CasC doesn't have it's own model, everything is based on actual
> java code discovery at runtime. So upgrading core or any plugin is changing
> this model. CasC targets reproducibility and immutability use-cases. If you
> want to upgrade anything you need to test it before.

Testing of changes between plugin versions was something I had great difficulty
with for Groovy-scripting-based configuration, which was much more common prior
to Configuration as Code. Do you have suggestions for administrators such as
myself on how I might validate that my configuration YAML is correct/applies
between any core or plugin upgrades?

This gets to the underlying concern I had in mind when starting this thread, as
an administrator, how will I know that my configuration applies correctly
between any core or plugin upgrades? My initial thought was schema-versioning,
but I'm certainly open to other suggestions.



Cheers


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/20180515181926.GB3395%40grape.lasagna.io.
For more options, visit https://groups.google.com/d/optout.

signature.asc (201 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

nicolas de loof-2
I've added a section on this topic in JEP-201: https://github.com/jenkinsci/jep/tree/master/jep/201#versioning

We can already generate a json-schema you can use to validate your yaml file(s) before applying configuration.
What you miss is a tool to convert jenkins-core + plugins.spec -> json schema. 
This is something we could package as well (something comparable to jenkinsfile-runner) or even provide "as a service".

We could also get such a tool both generate a schema and validate your config, as it seems there's not  (yet) so much text editors to support json schema validation in yaml

Would this help ?

2018-05-15 20:19 GMT+02:00 R. Tyler Croy <[hidden email]>:
(replies inline)

On Tue, 15 May 2018, nicolas de loof wrote:

> 2018-05-15 0:20 GMT+02:00 Liam Newman <[hidden email]>:
>
> >
> > Putting all that aside (as that is not the original point of this thread),
> > the original suggestion was to include a version field in the CasC YAML.
> > You said it would not work because the version would have to take into
> > account the core version and versions of all plugins, otherwise it might
> > break. Does that mean the CasC YAML could break _any time_  I upgrade any
> > component? Doesn't that rather defeats the purpose of CasC?
> >
>
> Yes indeed. CasC doesn't have it's own model, everything is based on actual
> java code discovery at runtime. So upgrading core or any plugin is changing
> this model. CasC targets reproducibility and immutability use-cases. If you
> want to upgrade anything you need to test it before.


Testing of changes between plugin versions was something I had great difficulty
with for Groovy-scripting-based configuration, which was much more common prior
to Configuration as Code. Do you have suggestions for administrators such as
myself on how I might validate that my configuration YAML is correct/applies
between any core or plugin upgrades?

This gets to the underlying concern I had in mind when starting this thread, as
an administrator, how will I know that my configuration applies correctly
between any core or plugin upgrades? My initial thought was schema-versioning,
but I'm certainly open to other suggestions.



Cheers


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/20180515181926.GB3395%40grape.lasagna.io.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJz%3D9BjgA8OA%2B0Sg9HfToF2v5rueuVjHR128o41%3D3cU056g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Suggestion: versioning the schema for Configuration as Code

stephenconnolly
But I still think you should include the (let’s invent a different name to show the purpose) meta-schema version

Most likely the meta-schema version will always be 1, but if you ever need to revise then you will thank Jesse and I for suggesting it.

CaaC has a schema for generating the schema at runtime... this is the meta-schema... it says things like: Java Maps are represented by ____, use the @Symbol as a ____, etc

That is what the meta-schema version represents. If it changes then you are saying the way of binding between yaml and runtime (in the general sense) has changed.

On Tue 15 May 2018 at 19:30, nicolas de loof <[hidden email]> wrote:
I've added a section on this topic in JEP-201: https://github.com/jenkinsci/jep/tree/master/jep/201#versioning

We can already generate a json-schema you can use to validate your yaml file(s) before applying configuration.
What you miss is a tool to convert jenkins-core + plugins.spec -> json schema. 
This is something we could package as well (something comparable to jenkinsfile-runner) or even provide "as a service".

We could also get such a tool both generate a schema and validate your config, as it seems there's not  (yet) so much text editors to support json schema validation in yaml

Would this help ?

2018-05-15 20:19 GMT+02:00 R. Tyler Croy <[hidden email]>:
(replies inline)

On Tue, 15 May 2018, nicolas de loof wrote:

> 2018-05-15 0:20 GMT+02:00 Liam Newman <[hidden email]>:
>
> >
> > Putting all that aside (as that is not the original point of this thread),
> > the original suggestion was to include a version field in the CasC YAML.
> > You said it would not work because the version would have to take into
> > account the core version and versions of all plugins, otherwise it might
> > break. Does that mean the CasC YAML could break _any time_  I upgrade any
> > component? Doesn't that rather defeats the purpose of CasC?
> >
>
> Yes indeed. CasC doesn't have it's own model, everything is based on actual
> java code discovery at runtime. So upgrading core or any plugin is changing
> this model. CasC targets reproducibility and immutability use-cases. If you
> want to upgrade anything you need to test it before.


Testing of changes between plugin versions was something I had great difficulty
with for Groovy-scripting-based configuration, which was much more common prior
to Configuration as Code. Do you have suggestions for administrators such as
myself on how I might validate that my configuration YAML is correct/applies
between any core or plugin upgrades?

This gets to the underlying concern I had in mind when starting this thread, as
an administrator, how will I know that my configuration applies correctly
between any core or plugin upgrades? My initial thought was schema-versioning,
but I'm certainly open to other suggestions.



Cheers


--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/20180515181926.GB3395%40grape.lasagna.io.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CANMVJz%3D9BjgA8OA%2B0Sg9HfToF2v5rueuVjHR128o41%3D3cU056g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
--
Sent from my phone

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CA%2BnPnMzTWPTBy7QJ5jJkf6r3Jqd0Wc1vocoY_uP-kB6eUCnwPw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
12