jenkinsci
/
configuration-as-code-plugin
mirror of https://github.com/jenkinsci/configuration-as-code-plugin.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
configuration-as-code-plugin/docs/DEVELOPER.md

3.0 KiB
Raw Permalink Blame History

Developer documentation

This document describes the JCasC API and design for plugin developers who are interested in extending JCasC by implementing custom Configurators or re-using the configuration mechanism in another context.

Also see the plugin's Javadoc for more information about classes and methods referenced on this page.

Using Configuration as Code

Configurators

Third party code to rely on JCasC has to create a key:value hierarchical representation of the target component and its sub-components. This representation is defined by the io.jenkins.plugins.casc.model package, and does not force use on any specific file format, despite we focus on YAML.

The main API is the Configurator which encapsulates access to the target component data model and how to create/configure it. Such a data model is exposed to external usage as a set of Attributes via the Configurator.describe() method. Each key in the key:value representation used as configuration input, has to match an Attribute.

ConfigurationContext

The configuration process only relies on ConfigurationContext to convert the key:value representation into a live component instance. Third party components to use this mechanism can provide a custom context, while JCasC relies on registered Jenkins components.

ConfigurationContext provides:

  • tweaks support for deprecated and restricted attributes, as well as unknown input elements
  • defines registry to retrieve Configurator for various component and classes to be configured
  • offers option to register Listeners to get notified about the configuration process and react on errors

YAML support

io.jenkins.plugins.casc.yaml package defines the implementation for loading the configuration from YAML sources. YamlUtils.loadFrom encapsulates the YAML parsing and merge process from a set of YAML documents, while YamlSource abstracts the way we load documents from files, URLs, or any other sources.

Extending Configuration as Code

Configurator and Attribute are the core abstraction of Configuration as Code to offer implementation flexibility. JCasC offers an implementation based on introspecting Java classes, relying on web UI data-binding mechanisms for DataBound component, and on JavaBean conventions for others (Descriptors, Extensions).

To implement Configurator for some component which doesn't fit into this model, or to control the exposed data model without relying on introspection, one can extend BaseConfigurator and override the describe() method to control the exposed data model.

Attributes exposed by this data model only have to define how to set value on target component and how to retrieve current value from a live instance (used by export feature). Here again JCasC offers as default implementation a JavaBean compliant implementation, but one could override get and/or set operation with custom code to support alternate mechanisms.

Useful links