3. Managing Resource-Level Content Updates

JBoss Operations Network can be used to store and deploy content to resources. This can be done to apply updates and patches (as with JBoss AS servers) or to set up repositories used for provisioning applications and deploying custom software.

3.1. About Content

Content for a resource can be almost anything, such as WAR and EAR files, configuration files, or scripts. JBoss ON provides a central framework to associate content, repositories, and resources in the inventory.

3.1.1. What Content Is: Packages

A package is anything that is installed on a platform or for a server or application. This can be an RPM, a JAR file, or even just a configuration file. A package simply provides some form of content for a resource. Packages can be sent to a resource through a JBoss ON-recognized repository or simply by uploading the package to the JBoss ON server and then sending it to the resource.
A resource can only be associated with or manage content if the resource plug-in identifies that content is available and the type of content that is supported. For example, application and web servers like JBoss AS/EAP and Tomcat support EAR, WAR, and JAR files as content; platforms support content like RPMs; but a database like PostgreSQL does not support any content types.
In a sense, content is both the software bits, scripts, or configuration files associated with a resource and also a resource itself. When content is added to a resource, it becomes a child resource in the JBoss ON hierarchy — but it can be managed, reverted, updated, or replaced by uploading new software bits. The parent resource (such as the application server) supports content; the child resource is a content backed resource.
Content can be added to a resource either by manually creating a child resource (and uploading the packages) or by adding the package to a content source and deploying it to the parent resource. The agent can also actively check for new content as part of its discovery scan and add any discovered content to its inventory. The agent's recurring package discovery scan has a default interval of 24 hours, as with the services scan.

3.1.2. Where Content Comes From: Providers and Repositories

Content sources are developers and distributors of content. Sources can be external third party software developers or internal development teams that create custom content. The type of content available from sources includes both software packages (such as RPMs or configuration scripts) and updates (version upgrades, patches, and errata).
A repository is a user-defined collection of software packages, which can come from one or multiple content sources. A repository may contain packages for an application or family of applications or for a specific purpose, like repositories for laptop configuration and repositories for installing web servers.
Repositories aren't siloed, separate containers for packages; they are essentially views that show a subset of available packages. All packages are stored in the JBoss ON database. A JBoss ON repository is a way of grouping those packages, both to make it easier to administer with resources and to provide a mechanism of access control for users (Section 3.1.4, “Authorization to Repositories and Packages”).
Resources can be subscribed to content repositories that are configured in JBoss ON, which provides a smooth and reliable mechanism for delivering consistent, administrator-configured content to resources.

3.1.3. Package Versions and History

Packages are versioned within JBoss ON itself. When a package is added to a resource or content source, the installer prompts for a version number; this is used as the UI display number.
This display version number is not required; if it is not given, then the JBoss ON server derives a number based on a calculated SHA-256 checksum for the package and the specification version and the implementation version in the META-INF/MANIFEST.MF file (for EARs and WARs).
SPEC(IMPLMENTATION)[sha256=abcd1234]
Package Version Numbers

Figure 7. Package Version Numbers


For example, for a META-INF/MANIFEST.MF file with these version numbers:
Manifest-Version: 1.0
Created-By: Apache Maven
Specification-Title: My Example App
Specification-Version: 1.0.0-GA
Specification-Vendor: Example, Corp.
Implementation-Title: My Example App
Implementation-Version: 1.x
Implementation-Vendor-Id: org.example
Implementation-Vendor: Example, Corp.
...
This creates a version number for the package like this:
1.0.0-GA(1.x)[sha256=abcd1234]
If the META-INF/MANIFEST.MF file does not contain one of the specification version or the implementation version, then only one is used. For example, if only the implementation version is given:
(1.x)[sha256=abcd1234]
If no version number is given, then the SHA is used as the identifier. (The SHA is used as the identifier internally, anyway.)
[sha256=abcd1234]
For exploded WARs and EARs, the calculated SHA-256 checksum is added to the MANIFEST.MF file. This allows the agent to check the file during discovery scans to verify the version of the package quickly.
Manifest-Version: 1.0
Created-By: Apache Maven
RHQ-Sha256: 570f196c4a1025a717269d16d11d6f37
...
For unexploded (archived) content, the checksum is recalculated with every package discovery scan and compared to the checksum in inventory.

NOTE

Exploded WARs and EARs can be deployed on JBoss and Tomcat servers. Because the content deployment process edits the META-INF/MANIFEST.MF file, the deployed content is not exactly identical to the content packages that were uploaded.
A clear versioning system makes it possible to handle package lifecycles in a clear and effective way. Updated content can be tracked as it is deployed, updates can be applied consistently, and packages can be reverted to a previous version. The same repository can also contain different versions of the same package, making it possible to apply different versions to different resources.

TIP

Package versions from different content sources can be associated with the same repository.
Whenever a package is installed on a resource, it is recorded in the content history for the resource and the package. Since there can be multiple files associated with a single package, then there can be multiple files recorded in the content history, all associated with that package version.

NOTE

Versioning only matters to content knit with a resource, like EARs and WARs. Other types of content stored in content sources (like CLI scripts used for alerting) do not track versions. Content deployed in bundles handles versioning through the bundle definition, not the content system.

3.1.4. Authorization to Repositories and Packages

There are a lot of reasons that users need to be able to access content in repositories. The most common is to manage packages on resources, but there are other reasons, too, like using the server CLI scripts in a repository to respond to alerts.
JBoss ON provides a way to balance the need for clear and simple access to content with the need to protect private or sensitive information. JBoss ON defines clear authorization rules for content repositories.
Every user has the ability to create repositories and to upload packages to them — regardless of the permissions for that user.
When a repository is created, there are settings which control access to them:
  • Owner sets write access to a repository. It assigns the repository to belong to a specific user. If no user is specified, then only users with the manage repositories permission have the right to access those repositories.
  • Private sets read (download) access to the repository. It sets whether the repository can be viewed by anyone or only by the owner and users with the manage repositories permission. Public repositories are viewable by everyone, regardless of the owner.
Repository Ownership and Access Settings

Figure 8. Repository Ownership and Access Settings


Repo managers (users with the manage repositories permission) can change the ownership and privacy settings of a repository. Users without the manage repositories permission can change the privacy settings but they cannot change the ownership; the repository is always owned by them or managed by the repo manager.

NOTE

Be very careful when switching public repositories to private. Any operations which relied on those repositories, such as running server CLI scripts in response to alerts, will no longer work if the privileges of the user are insufficient to access the repository.
JBoss ON uses the repositories access control permission to define users with administrative access to repositories. Any user with that permission can manage any configured repository, regardless of who the repository's owner is. Repositories without an owner can only be managed by users with the repositories permission. Lastly, only users with this permission can associate a content source with a repository; all other users must add packages to the repository manually.