WildFly uses Galleon to provision and update its installation. All concepts related to Galleon are defined in its documentation
It is out of scope of this document to define how WildFly and the components it incorporates are versioned. However, channels are referencing Maven versions. A channel can specify a pattern of version and pick the “latest” version that matches that pattern.
This "latest" version is determined by comparing all the versions and returns the last one using the
org.wildfly.channel.version.VersionMatcher.getLatestVersion(Set<String> versions) method.
|
Note
|
This provides a deterministic way to find the "latest" version. However, it is out of scope of this specification to capture all the
different version patterns. Our recommendation is to specify a pattern in |
Channel combines a Channel Manifest defining content of channel, one or more Repositories from which the content can be resolved and an optional Blocklist Manifest.
A channel is composed of several fields:
-
An optional
namethat is a human-readable one-line description of the channel (Channel for WildFly 27) -
An optional
descriptionthat provides human-readable description of the channel -
An optional
vendorthat defines who provides the channel and their support level. This field is descriptive only and is not used to enforce any mechanism. This field is composed of:-
A required
nameto identify the vendor (egWildFly Community Project) -
A required
supporttype that accepts the following values:-
supported- Components provided by this channel are supported by the vendor. Some features provided by this channel can still be considered as tech-preview. -
tech-preview- Feature provided by this channel are Tech Preview by the vendor -
community- Components provided by this channel are a community effort from the vendor
-
-
-
A collection of
repositoriesthat defines repositories associated with the channel. Only listed repositories are used to resolve channel’s components. Each repository is composed of:-
A required
idthat defines the repository name used in Maven cache -
A required
urlpointing to a default Maven repository
-
-
Optional
manifestcorresponding to the Channel Manifest artifact. Channel Manifest is used to define streams available in the channel.-
One of the following, mutually exclusive fields, used to resolve the Channel Manifest:
-
mavencorresponds to Maven coordinates of the Manifest. It’s composed of:-
Mandatory
groupIdandartifactIdelements that are the Maven coordinates of the manifest. -
Optional
versionto stick to a given manifest version (instead of requiring the latest version of that manifest). In the absence of thisversion, the latest version of the manifest will be determined based on the Maven repository metadata (see Component Version).
-
-
urlcorresponding to a URL where the manifest file can be found. -
signature-urlcorresponding to a URL where the signature of the manifest file can be found.
-
-
-
Optional
blocklistcorresponding to the Blocklist artifact. Blocklist is used to define versions of artifacts excluded from a channel.-
One of the following, mutually exclusive fields, used to resolve the Blocklist:
-
mavencorresponds to Maven coordinates of the Blocklist. It’s composed of:-
Mandatory
groupIdandartifactIdelements that are the Maven coordinates of the blocklist. -
Optional
versionto stick to a given blocklist version (instead of requiring the latest version of that blocklist). In the absence of thisversion, the latest version of the blocklist will be determined based on the Maven repository metadata (see Component Version).
-
-
urlcorresponding to a URL where the blocklist file can be found.
-
-
-
An optional
resolve-if-no-streamthat defines strategy for version resolution if the artifact has not been found in thestreamscollection or if the channel didn’t declare a manifest. Allowed values are:-
latest- use the latest version found in the Maven repositories (using mechanism described in Component Version) -
maven-latest- a version marked aslatestin the Maven metadata -
maven-release- a version marked asreleasein the Maven metadata -
none- do not attempt to resolve versions of artifact not listed in thestreamscollection. Default value if no strategy is provided.
-
-
Optional
gpg-checkboolean indicating that during artifact resolution, this channel will verify a signature of every artifact. If the artifact signature cannot be found, or cannot be validated, the artifact will not be resolved from the channel. The channel repositories must contain a detached GPG signature paired with the artifact as described below. -
Optional
gpg-urlsa list of URLs that the public GPG keys used to validate artifact signatures are resolved from.
A Channel Manifest is composed of following fields:
-
An optional
namethat is a human-readable one-line description of the channel (manifest for WildFly 27) -
An optional
idelement that is used to identify channel. -
An optional
descriptionthat provides human-readable description of the channel -
An optional
logical-versionthat provides a human-readable short description of the version of the manifest. Note this may, but doesn’t need to correspond to the Maven version of the artifact (from Manifest schema 1.1.0). -
A collection of
requires. Each element of that list corresponds to another channel that is required to provision components from this channel. This field can be used for layered products to enforce their dependencies so that the installation only need to update the top level channel to get updates from all required channels. Each element is composed of:-
Mandatory
idelement corresponding to the ID of required manifest. -
Optional
mavenelement representing Maven coordinates the required manifest is published at.-
Mandatory
groupIdandartifactIdelements. -
Optional
versionto stick to a given manifest version (instead of requiring the latest version of that manifest). In the absence of thisversion, the latest version of the manifest will be determined based on the Maven repository metadata.
-
-
-
A collection of
streamsthat defines all the components installable from this channel. Each stream is composed of:-
A required
groupIdthat corresponds to Maven GroupId to pull artifacts (it is not allowed to specify*for the groupId). -
A required
artifactIdthat corresponds to Maven ArtifactId to pull artifacts. Special syntax*can be used to match any artifactId. -
One of the following fields (which are mutually exclusive) that provides rules to resolve the Maven artifacts to provision. At most one field must be present in the stream definition.
-
versionPatterncorresponds to a Pattern through which the available versions are matched (e.g.2\.2\..*) -
versioncorresponds to a single version (e.g.2.2.Final)
-
-
-
A collection of
blocksthat defines all the component versions excluded from version resolution. Each exclusion is composed of:-
A required
groupIdthat corresponds to Maven GroupId of the excluded artifacts (it is not allowed to specify*for the groupId). -
A required
artifactIdthat corresponds to Maven ArtifactId of the excluded artifacts. Special syntax*can be used to match any artifactId. -
A required list of
versionscorresponding to excluded version (e.g.[2.2.Final, 2.2.1.Final])
-
JSON Schemas are provided to validate that channels and manifests comply with the model described above.
A channel is specified in the YAML language with a corresponding JSON schema to validate its structure.
A manifest is specified in the YAML language with a corresponding JSON schema to validate its structure.
A blocklist is specified in the YAML language with a corresponding JSON schema to validate its structure.
A minimal Channel definition is a single file that complies with the channel YAML representation. The Channel definition may reference two additional resources: a Manifest file and a Blocklist file.
Creating a channel corresponds to the creation of the above files.
A channel may be “published” so that it can be read (or downloaded) by WildFly provisioning tooling.
Channels are published as a Maven artifact with the classifier channel and extension/type yaml.
If the Channel uses maven coordinates to reference Manifest and/or Blocklist, those files must be "published" in one of the repositories defined in the Channel so that the Channel is able to resolve them. Otherwise, those files must be made available at the URLs defined by the Channel.
When manifests are published as Maven artifacts, they must use the classifier manifest and extension/type yaml.
When blocklists are published as Maven artifacts, they must use the classifier blocklist and extension/type yaml.
A channel definition and manifest can be updated to add or modify streams, change its requirements, etc. Each of the channel files can be updated independently of each other.
To update a channel file, it needs to be published with a new version.
The main consumers of WildFly Channels are the provisioning tooling provided by the WildFly project.
They consume channels by pulling the channel artifact corresponding to the groupId/artifactId of a channel. If a version is specified, the channel corresponding to that version is pulled. Otherwise, the latest version of the channel is determined based on the Maven metadata from the repository that hosts the channel artifacts.
The manifest is resolved when a channel is initialized. The channel can omit the manifest definition in which case the resolve-if-no-stream strategy will be used to resolve artifacts.
If the channel defines a manifest using URL, the manifest will be read from that location. If instead maven coordinates are used, the specified version of manifest is resolved from the channel’s repositories. If only groupId and artifactId is provided, the latest available version of the channel manifest (as defined in Component Version) will be used.
If the chanel defines a manifest, but no manifest can be resolved (using either URL or GA[V]), an error will be thrown.
Required channels are identified by their manifests' ID. If multiple channels are used in the channel session, the required IDs are first resolved from the list of channels.
If an ID cannot be resolved in this way, and the requirement provides maven element, a resolution will be attempted using provided maven coordinates. The parent channel’s repositories will be used to resolve the new manifest and the created channel will inherit repository settings from the parent channel.
If the resolution cannot be achieved, an error will be thrown.
If the required channels form a cycle, an error will be thrown.
If the set of channels contains non-unique manifest IDs, an error will be thrown.
A Maven artifact can be resolved through a channel.
Such a resolution will use the Maven repositories defined within the channel. If a channel requires a different channel, the required channel will use the repositories from its own definition.
The channels will be searched for a stream that matches the groupId/artifactId of the artifact.
If a channel directly defines a stream that matches the groupId/artifactId of the artifact, the version will be resolved from this stream.
If channel does not directly define a stream, required channels will be searched. The latest version of the stream found in the required channels will be used.
If multiple channels are defined, the latest version from any channel that defines the stream (directly or through required channels) is used. Channel which manifests are required by another channel, are excluded from a direct search.
If no stream that matches the artifact have been found, version is resolved using fallback strategy defined in resolve-if-no-stream for the channel.
An error is returned to the caller if:
-
the fallback strategy is
none -
the fallback strategy is
latest,maven-latestormaven-releasebut underlying Maven repository contains no metadata for artifacts with requiredgroupIdandartifactId
If the stream defines a version, the artifact will be resolved based on this version. If that version of the artifact can not be pulled
from the Maven repositories, an error is returned to the caller.
If the stream defines a versionPattern, the version will be determined by querying the version of the artifacts from the
Maven repositories and use the latest version that matches the pattern. If no version matches the pattern, an error is returned to the caller.
When channel definitions, manifests, or blocklists are hosted on remote servers that require authentication, the WildFly Channel library supports pre-emptive authentication using Bearer tokens.
Authentication can be configured using either a system property or an environment variable:
-
System property:
org.wildfly.channel.http.auth.token -
Environment variable:
WILDFLY_CHANNEL_HTTP_AUTH_TOKEN
The system property takes precedence over the environment variable. If the system property is not set (or is a blank value), the environment variable will be checked as a fallback.
When either configuration is set to a non-blank value, the library will automatically include an Authorization header with the Bearer token in all HTTP and HTTPS requests for channel metadata files.
Pre-emptive authentication is supported for the following resources when accessed via URL:
-
Channel definitions (when using
urlfield in channel resolution) -
Channel manifests (when using
urlfield in manifest coordinate definition) -
Blocklists (when using
urlfield in blocklist coordinate definition) -
Manifest signature files (when using
signature-urlfield)
Authentication is only applied to HTTP and HTTPS URLs. Other protocols (such as file://) do not support authentication and will ignore the configured token.
When the org.wildfly.channel.http.auth.token property is set to a non-blank value, the library sends the following HTTP header:
Authorization: Bearer <token>Where <token> is the value of the system property.
To configure authentication for downloading channel metadata using a system property:
java -Dorg.wildfly.channel.http.auth.token=my-secret-token ...Alternatively, using an environment variable:
export WILDFLY_CHANNEL_HTTP_AUTH_TOKEN=my-secret-token
java ...Or set inline:
WILDFLY_CHANNEL_HTTP_AUTH_TOKEN=my-secret-token java ...Any of these configurations will cause all HTTP/HTTPS requests for channel, manifest, and blocklist files to include the Bearer token in the Authorization header.
|
Note
|
The authentication token is sent with every HTTP/HTTPS request for metadata files. Ensure that:
|
When using an open channel, a situation may arise where certain artifacts are promoted to the channel and later discovered to be invalid. As it’s impossible to remove artifacts already deployed into a repository, those versions have to blocklisted.
The blocklist file contains a list of stream Maven coordinates with multiple versions:
---
blocks:
- groupId: io.undertow
artifactId: undertow-core
versions:
- 2.2.18.Final
- 2.2.17.Final
…The artifactId can use a wildcard syntax to refer to all the artifacts with the same groupId
---
blocks:
- groupId: io.undertow
artifactId: “*”
versions:
- 2.2.18.Final
- 2.2.17.FinalThe blocklist is resolved when a channel is initialized.
If the channel defines a blocklist using URL, the blocklist will be read from that location. If instead maven coordinates are used, the specified version of manifest is resolved from the channel’s repositories. If only groupId and artifactId is provided, the latest available version of the blocklist (as defined in Component Version) will be used.
If no blocklist artifact can be resolved with supplied Maven coordinates, the channel treats it as an empty blocklist.
A blocklist applies only to the channel that defined it, not its required channels.
During artifact version resolution, a stream matching artifact GA is located in the channel. The blocklist is always checked for excluded versions, except when using resolveDirectMavenArtifact method. The excluded versions are removed from the set of available artifact versions before the latest remaining version matching the stream’s pattern is used to resolve the artifact. If the blocklist excludes all available artifact versions, UnresolvedMavenArtifactException is thrown.
If a channel sets value of gpg-check property to true, any artifact resolved from it (including the manifest itself) must have a valid GPG signature.
Maven artifacts are expected to have their detached GPG signatures available in the channel repositories. The detached artifacts must have the same GAV as the artifact, but append ".asc" suffix to the file extension. The signature file must contain an armoured GPG signature.
The signature file is resolved at the same time as the artifact. If the signature is invalid, the public key is not found, the public key is expired or revoked, the artifact must be rejected and a SignatureException must be thrown.
If the manifest of a channel is defined as a Maven GA(V), it is treated as any other maven artifact. If it is defined as an URL, the signature file must be available at the same URL with ".asc" suffix. Alternatively, a signature-url element can be used to provide a location of the signature. If the signature cannot be resolved, the channel creation must fail.
The public keys are identified by the a keyID in hexadecimal form. The public keys required by the channel can be defined using gpg-urls property. Each gpg-urls must be a URL to a downloadable key.
Implementations may provide additional means of providing keys - local stores, remote keyservers, etc.
-
Adding ability to verify artifact signatures
-
Adding
gpg-checkandgpg-urlsfields to the Channel definition. -
Adding
signature-urlfield to the Channel’s manifest coordinate definition.
-