Propose fix some typos (#117)
This commit is contained in:
John Eismeier
Ewelina Wilkosz
parent
40b2c83fca
commit
771b136ca1
|
|
@ -6,40 +6,40 @@ to apply the adequate configuration on Jenkins live instance.
|
|||
|
||||
## Configurator
|
||||
|
||||
A [`Configurator`](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/Configurator.java)
|
||||
A [`Configurator`](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/Configurator.java)
|
||||
is managing a specific Jenkins Component, and as such knows
|
||||
about data this component exposes to end-user for configuration.
|
||||
about data this component exposes to end-user for configuration.
|
||||
It has:
|
||||
|
||||
|
||||
* a `name` to match a YAML entry,
|
||||
* a `target` component type
|
||||
* a `describe` method to document the attributes the target component exposes to configuraiton
|
||||
* a `configure` method to configure the target component
|
||||
* a `describe` method to document the attributes the target component exposes to configuration
|
||||
* a `configure` method to configure the target component
|
||||
|
||||
From a yaml node with associated `Configurator`, configuration-as-code will handle every
|
||||
child node in YAML structure based on current node's `Attribute`s, as described by the `Configurator`.
|
||||
|
||||
## Root Configurator selection
|
||||
|
||||
Root elements are identified by YAML entry name, and a matching
|
||||
Root elements are identified by YAML entry name, and a matching
|
||||
[`RootElementConfigurator`](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/RootElementConfigurator.java) is selected.
|
||||
|
||||
`RootElementConfigurator` is a special interface used to identify a `Configurator` which manages a top level
|
||||
configuration element in the yaml document.
|
||||
|
||||
configuration-as-code do provide a custom `RootElementConfigurator` for `jenkins` root entry in yaml document,
|
||||
configuration-as-code do provide a custom `RootElementConfigurator` for `jenkins` root entry in yaml document,
|
||||
as well as generic `RootElementConfigurator`s to model [global configuration categories](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/jenkins/model/GlobalConfigurationCategory.java).
|
||||
|
||||
### Attributes
|
||||
|
||||
Configurator do document the target component by implementing `describe` method. This one do returl a set
|
||||
of [`Attribute`](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/Attribute.java)s
|
||||
of [`Attribute`](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/Attribute.java)s
|
||||
to document both name _AND_ type for a configurable attribute.
|
||||
|
||||
We don't want to expose the whole Jenkins Java API to configuration-as-code. Many components do define setter
|
||||
methods for technical reasons or to support backward compatibility. So configuration-as-code do exclude :
|
||||
* setter methods marked as `@Deprecated`
|
||||
* setter methods marked as `@Restricted`
|
||||
* setter methods marked as `@Restricted`
|
||||
|
||||
Attribute also is responsible to document the target component type. We use Java reflexion to extract this
|
||||
information from Java API, including parameterized types.
|
||||
|
|
@ -49,43 +49,43 @@ As a resume, a component which exposes a method like :
|
|||
public void setFoo(List<Foo`> foos) { ... }
|
||||
|
||||
```
|
||||
will be detected as Attribute named `foo` with target type `Foo` with multiple values expected.
|
||||
will be detected as Attribute named `foo` with target type `Foo` with multiple values expected.
|
||||
|
||||
### Configuration
|
||||
|
||||
Configurator also has to implement the `configure` method to process yaml content and instanciate or configure
|
||||
Configurator also has to implement the `configure` method to process yaml content and instantiate or configure
|
||||
target component. The actual mechanism depends on the target. Configuration-as-Code do provide generic
|
||||
mechanisms which cover most Jenkins components.
|
||||
|
||||
This generic mechanism assumes Jenkins core components and plugins do follow some conventions, but
|
||||
custom "glue-code" can also be provided as a (temporary) workaround, or to expose a configuration model
|
||||
which doesn't reflect the internal data model, but better matches the end-user experience.
|
||||
which doesn't reflect the internal data model, but better matches the end-user experience.
|
||||
|
||||
A typical sample for this scenario is credentials-plugin.
|
||||
A typical sample for this scenario is credentials-plugin.
|
||||
[CredentialsRootConfigurator](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/credentials/CredentialsRootConfigurator.java)
|
||||
do expose a simplified configuration API for `system` credentials store, which is hardly configurable
|
||||
using the other general purpose configuration-as-code component due to internal design of this plugin.
|
||||
|
||||
using the other general purpose configuration-as-code component due to internal design of this plugin.
|
||||
|
||||
## General purpose configurators
|
||||
|
||||
### Using Data binding
|
||||
|
||||
As we want to reflect web UI user experience, relying on the same configuration mechanisms as the web
|
||||
As we want to reflect web UI user experience, relying on the same configuration mechanisms as the web
|
||||
UI is a natural approach.
|
||||
|
||||
`org.jenkinsci.plugins.casc.DataBoundConfigurator` can configure arbitrary
|
||||
`org.jenkinsci.plugins.casc.DataBoundConfigurator` can configure arbitrary
|
||||
jenkins component to rely on `DataBoundConstructor`
|
||||
and `DataBoundSetter`s for UI data-binding. It uses same attributes names as
|
||||
the web UI, which are expected to be human friendly.
|
||||
|
||||
When, for some technical or legacy reasons, technical attribute name isn't user friendly, we also support
|
||||
`@Symbol` annotation on setter to offer a better user-experience.
|
||||
|
||||
### Descriptors
|
||||
`@Symbol` annotation on setter to offer a better user-experience.
|
||||
|
||||
### Descriptors
|
||||
|
||||
`org.jenkinsci.plugins.casc.DescriptorRootElementConfigurator` can configure
|
||||
global configuration for Descriptors, to mimic the `global.jelly` UI exposed
|
||||
to end user on the web UI.
|
||||
to end user on the web UI.
|
||||
|
||||
Jenkins has hundreds Descriptors, most of them for internal technical reasons,
|
||||
so only the ones to have a `global` view are accessible from configuration-as-code.
|
||||
|
|
@ -100,4 +100,3 @@ As a short terms workaround, a custom `Configurator` glue-code implementation ca
|
|||
|
||||
Initial secrets are handled by the concrete implementations of the [SecretSource](https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/src/main/java/org/jenkinsci/plugins/casc/SecretSource.java). In order to implement a new
|
||||
secret source, subclass `SecretSource` by extending it, and mark the new class with the `@Extension` annotation.
|
||||
|
||||
|
|
|
|||
12
README.md
12
README.md
|
|
@ -38,7 +38,7 @@ jenkins:
|
|||
ttl: 10
|
||||
userIdStrategy: CaseSensitive
|
||||
groupIdStrategy: CaseSensitive
|
||||
```
|
||||
```
|
||||
|
||||
In addition, we want such a file to have a well documented syntax, and tooling to assist in writing and testing,
|
||||
so end-users have full guidance in using this toolset and don't have to search stackoverflow for samples.
|
||||
|
|
@ -79,7 +79,7 @@ jenkins:
|
|||
|
||||
slaveAgentPort: 50000
|
||||
agentProtocols:
|
||||
- "jnlp2"
|
||||
- "jnlp2"
|
||||
|
||||
tool:
|
||||
git:
|
||||
|
|
@ -101,7 +101,7 @@ credentials:
|
|||
id: ssh_private_key
|
||||
keyStoreSource:
|
||||
fileOnMaster:
|
||||
keyStoreFile: /docker/secret/id_rsa
|
||||
keyStoreFile: /docker/secret/id_rsa
|
||||
```
|
||||
|
||||
Also see [demos](demos) folder with various samples.
|
||||
|
|
@ -119,7 +119,7 @@ For this purpose, we delegate to the popular [job-dsl-plugin](https://wiki.jenki
|
|||
and run a job-dsl script to create an initial set of jobs.
|
||||
|
||||
Typical usage is to rely on a multi-branch, or organization folder job type, so further jobs will be dynamically
|
||||
created. So a multi-branch seed job will prepare a master to be fully configured for CI/CD targetting a repository
|
||||
created. So a multi-branch seed job will prepare a master to be fully configured for CI/CD targeting a repository
|
||||
or organization.
|
||||
|
||||
Job-DSL plugin uses groovy syntax for it's job configuration DSL, so you'll have to mix yaml and groovy within your
|
||||
|
|
@ -135,7 +135,7 @@ jobs:
|
|||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
## How to provide initial secrets for Configuration-as-Code
|
||||
|
||||
|
|
@ -163,7 +163,7 @@ If all those 4 are present, Configuration-as-Code will try to gather initial sec
|
|||
|
||||
## Supported plugins
|
||||
|
||||
Here is a list of plugin we have successfuly tested to support configuration-as-code approach :
|
||||
Here is a list of plugin we have successfully tested to support configuration-as-code approach :
|
||||
|
||||
- [x] active directory plugin ([details](demos/credentials/README.md))
|
||||
- [x] artifactory plugin ([details](demos/artifactory/README.md))
|
||||
|
|
|
|||
Loading…
Reference in New Issue