Content Management Guide

Content management is a central feature of orcharhino. Within the context of orcharhino the term content management primarily refers to the provisioning of software beyond the basic operating system on some given host managed through orcharhino. For example, a host that is to be used as a web server, would typically require access to any packages needed by the Apache server (or something equivalent).

orcharhino’s content management offers a highly flexible framework, that can be adapted to a wide variety of use cases. Many operating systems and content types are supported, as well as version control and lifecycle management.

As a result orcharhino’s content management features several interrelated parts and a relatively high degree of conceptual complexity. This guide exists to break down that complexity, so as to provide an accessible introduction.

The content management guide contains the following subsections:

For more information on using orcharhino’s content management via the Management UI see also: The Content Menu.

Key Terminology

To make any progress in understanding orcharhino’s content management we must first introduce the key terminology involved. This subsection of the guide provides background information, and can also serve as a quick reference.

  • Repository: The smallest storage unit for software content in orcharhino. A orcharhino software repository generally needs to be synchronized with some content source outside of orcharhino to obtain content. To be usable in orcharhino a remote repository must be of a supported type. Supported types include: deb, yum, puppet, docker, and file.
  • Product: Simply a named collection of one or more repositories. A single product may contain repositories of different types. Generally, repositories can only ever be added to orcharhino as part of some product. (See also: Products from the Management UI chapter).
  • Subscription: Within the context of Red Hat Enterprise Linux, subscriptions are used to limit how many times some given Red Hat product may be used (depending on how many Red Hat subscriptions were bought). For products not limited in this way, each product simply corresponds to exactly one unlimited subscription.
  • Red Hat Subscription For Red Hat customers orcharhino provides additional features for the management of Red Hat content. (See also: Subscriptions and Red Hat Repositories from the Management UI chapter).
  • SUSE Subscription For SUSE customers orcharhino provides additional features for the management of SUSE content. (See also: SUSE Subscriptions from the Management UI chapter).
  • Content View: A named and versioned collection of repositories. Whenever a new content view version is created (published), the current software content state of the repositories within it is frozen. Any subsequent changes to the underlying repositories will no longer affect the published content view version. (See also: Content Views from the Management UI chapter).
  • Composite Content View: Simply a content view created by combining existing content views. Unless otherwise noted we will use the term “content view” to refer to both content views and composite content views in this guide. (See also: Content Views from the Management UI chapter).
  • Lifecycle Environment: A lifecycle environment exists to restrict host access to content based on the hosts role or affiliation. For example, the classic scenario for lifecycle management is to distinguish between hosts for development, testing, and production. (In this scenario hosts would be assigned to either the development, testing, or production lifecycle environment). It would then be possible to run different versions of the same software in the different environments. This way, new versions of a software can be developed, and then tested before being used in the production environment, greatly reducing the risk of disruption by prematurely rolled out updates. (See also: Lifecycle Environments from the Management UI chapter).
  • Lifecycle Environment Path: Lifecycle environments are organized into directional paths. Content view versions are then “promoted” through the path. Sticking with the previous example, a new content view version would be used in the development environment fist, then be promoted to testing, and only enter production once it has been sufficiently tested. It is possible to create multiple lifecycle environment paths, containing a variable number of lifecycle environments. All paths originate from the “library” environment, which is always present by default. (See also: Lifecycle Environments from the Management UI chapter).
  • Activation Key: Part of the mechanism used for hosts to register with orcharhino’s content management. An activation key is associated with exactly one lifecycle environment and exactly one content view (though this may be a composite content view). An activation key must also be associated with one or more subscriptions (which generally correspond to products). When a host registers using a given key content is made available to the host. The content that is made available is the set theoretic intersection, between the content present in the key’s content view/lifecycle environment combination, and the content present in the key’s subscriptions. (See the below image for a visual representation). (See also: Activation Keys from the Management UI chapter).
Specifying the content host with products, content views and activation keys
  • Subscription Manager: The client side software responsible for registering hosts with orcharhino’s content management (using some activation key), as well as managing the hosts repository access once registered.
  • Katello Agent: The client side software that allows orcharhino users to manage registered hosts (Content Hosts) from the orcharhino server.
  • Content Host: A host managed through orcharhino’s content management. Each content host is always associated with exactly one content view and exactly one lifecycle environment. (See also: Content Hosts from the Management UI chapter).

Note

The Katello agent supports package actions for Red Hat, and SUSE based systems. The remote execution plugin, additionally supports package actions for Debian (and is easy to extend for further operating systems and package managers.) As a result, use of the Katello agent for package actions may be deprecated in favor of the remote execution plugin in the not to distant future. (See also: Remote Execution Guide).

Features

This subsection of the guide answers the question what one can do using orcharhino’s content management. The following list can also be read as a feature set:

  • Gaining access to SUSE and Red Hat Enterprise content. (Only relevant to SUSE and Red Hat customers).
  • Adding content sources (repositories) to orcharhino (organized into products) and synchronizing orcharhino with those (remote) repositories.
  • Creating orcharhino content views (and/or composite content views) to create useful collections of repositories. (For example: All the repositories needed by a particular type of database server.)
  • Publishing content views for version control. This action will freeze the current state of all repositories in the content view, to create a stable software source (referred to as a version of the content view).
  • Creating lifecycle paths and lifecycle environments to restrict content access to a particular content view version based on role.
  • Promoting particular versions of content views through a lifecycle path (into the next lifecycle environment) to upgrade content in a careful and controlled way.
  • Creating activation keys to register hosts (or entire Host Groups) to a particular content view and lifecycle environment (further restricted using subscriptions).
  • Managing registered content hosts (through the Content Hosts page, from The Hosts Menu in the Management UI).

For more information on how to do the above things, see Setup below.

Supported Content Types

orcharhino supports several different content types, and each of these types is given it’s own page in The Content Menu section of the Management UI chapter:

These content types are related to the various repository types supported by orcharhino. (See also: Products). However, a repository of a given type, might contain content of several different types. For example, repositories of type yum may contain content of type errata, as well as content of type RPM package. (Repository types include: deb, yum, puppet, docker, and file).

Setup

When confronted by the various menu items in The Content Menu it is not immediately clear where to begin. However, the relations between the various parts of orcharhino’s content management do imply a logical order. For example, it makes little sense to create content views before importing the relevant content (in the form of products).

This subsection of the guide introduces a natural order in which to approach orcharhino’s content management, providing a kind of step-by-step setup guide. It should be of particular interest to first time users and orcharhino administrators.

Before you actually start creating the various content management entities, you may also want to check the Strategy and Best Practices section under Usage below.

To avoid duplicate documentation we will make frequent reference to the relevant subsections from The Content Menu section of the Management UI chapter. Follow these references for detailed documentation on how to perform each step described.

SUSE and Red Hat Enterprise Content

This subsubsection includes step-by-step instructions on how to add SUSE and/or Red Hat Enterprise Linux (RHEL) content to orcharhino. If you are neither a SUSE, nor a RHEL customer, skip this section (continue with Products, Repositories, and Synchronization).

For RHEL customers:

  1. Import a Red Hat manifest file (can be obtained from Red Hat). (See Subscriptions). Once you have imported your manifest file any associated Red Hat content will automatically appear on the Red Hat repositories page.
  2. Select Red Hat content for inclusion in orcharhino. (See Red Hat Repositories). Once RHEL content has been selected, it will automatically appear in the form of orcharhino products.
  3. Synchronize your new Red Hat products (continue with Products, Repositories, and Synchronization below).

For SUSE customers:

  1. Add your SUSE Customer Center (SCC) accounts to orcharhino. (See SUSE Subscriptions). Any number of SCC accounts can be added to orcharhino. Once a SCC account has been added (and synced) any associated SUSE products can be selected for inclusion in orcharhino.
  2. Select SUSE content for inclusion in orcharhino. (See SUSE Subscriptions). Once SUSE content has been selected, it will automatically appear in the form of orcharhino products.
  3. Synchronize your new SUSE products (continue with Products, Repositories, and Synchronization below).

Products, Repositories, and Synchronization

This subsubsection includes step-by-step instructions on how to add arbitrary content to the orcharhino server. If you are a SUSE or RHEL customer, and followed the steps for SUSE and Red Hat Enterprise Content above you will already have some orcharhino products. In addition it is possible to add your own products with your own (or publicly available) repositories (for example via a link to a public mirror):

  1. (Optional) Add GPG keys and/or SSL certificates to orcharhino. (See Content Credentials and Products).
  2. (Optional) Create any sync plans you may want for your products. (See Sync Plans).
  3. Create and synchronize any desired products (with repositories). (See Products).
    1. Create the empty product.
    2. Add any desired (remote) repositories to your product.
    3. Manually synchronize your new product, or wait for your sync plan to take effect.
  4. (Optional) Check on the synchronization status of your products. (See Sync Status).

Important

Depending on your download policy (set for individual repositories) synchronization will create a local copy (on the orcharhino server) of all repositories contained in each product being synchronized. Depending on the size of the repositories involved, and the speed of the internet connection to them, this can take a significant amount of time. Many hours are not uncommon and should be planned for accordingly.

Once your products are synchronized continue with Content Views and Lifecycle Environments/Paths.

Content Views and Lifecycle Environments/Paths

This subsubsection includes step-by-step instructions on how to manage content on the orcharhino server once it has been successfully synchronized. These steps are necessary to provide version control and lifecycle management for this content.

  1. (Optional, best practice) Create any lifecycle environment paths as desired. (See Lifecycle Environments)
    1. Create new environment paths by appending a single new lifecycle environment to Library.
    2. Complete your new environment paths, by appending additional new lifecycle environments to the ends of existing paths.
  2. Create any desired content views. (See Content Views).
    1. Create the empty content view.
    2. Add any desired (local) repositories to your content view.
    3. Publish a new version of your new content view (version 1.0)
    4. (In the future) Publish additional major versions of the content view once the underlying repositories have changed (2.0, 3.0, etc.) or
    5. (Optional) Apply Errata to a major version of the content view to create minor versions (like 1.1, 1.2, 2.1, etc.)
    6. Promote relevant versions of your content view through your lifecycle environment paths. (Different versions can be assigned to different environments in a path).
  3. (Optional) Create any desired composite content views. (See Content Views).
    1. Create the empty composite content view.
    2. Add any desired (existing) content views to your composite content view.
    3. Select which version of the added content views should be used.
    4. Publish a new version of your new composite content view (version 1.0)
    5. (In the future) Publish additional major versions (2.0, 3.0, etc.) of the composite content view once additional content views have been added or if new versions of the underlying content views should be used.
    6. Promote relevant versions of your content view through your lifecycle environment paths. (Different versions can be assigned to different environments in a path).

Once content views and lifecycle environment paths have been fully created continue with Activation Keys and Content Hosts.

Activation Keys and Content Hosts

This subsubsection includes step-by-step instructions on how to register content hosts with orcharhino (using activation keys). Provisioning cotent hosts with content managed through orcharhino is the ultimate goal of orcharhino’s content management.

  1. Create any desired activation keys. (See Activation Keys).
    1. Create the key using exactly one lifecycle environment and exactly one content view (or composite content view)
    2. Add any desired subscriptions to the key.
    3. (Optional, discouraged) override repository sets as desired.
    4. (Optional) Add any desired Host Collections.
  2. (Optional) associate your host groups with new activation keys as desired. (See Host Groups).
  3. Create any desired content Hosts. (See Content Hosts). Content hosts are created by registering an existing (plain) host with orcharhino’s content management (using an activation key), or by creating new hosts belonging to a host group already associated with some activation key.

Once content hosts have been successfully created, they can be managed through orcharhino. (See Content Hosts).

Usage

This subsection of the content management guide includes instructions on how to make effective use of orcharhino’s content management after it has been set up. As such, this subsection presumes the presence of fully entitled content hosts with access to fully configured content views, lifecycle environments, and subscriptions. If you do not yet have these things set up, see Setup above.

Strategy and Best Practices

This subsubsection provides some examples and best practice guidelines for how orcharhino’s content management could be used. Note that these examples may not be optimal for all use cases, and should be viewed as friendly suggestions.

  • We recommend keeping products as small as possible. For example, one product each for PostgreSQL-7.0, PostgreSQL-7.1, PostgreSQL-8.1, with one repository each, is better than a single PostgreSQL product including multiple repositories for different versions. Likewise, we recommend separate products for things like CentOS-7.1, Apache 2.0, MySQL-5.1 or PostgreSQL 7.1, rather than a single WebServer product. Since products correspond to subscriptions, small products will give you greater control over what subscriptions (and by extension what content) is used (via your activation keys).
  • There are two basic approaches to content views. Either create content views that contain everything needed for a certain type of host. E.g.: WebServer which includes repositories for CentOS-7.1, Apache-2.0, PostgreSQL-7.1 etc. Alternatively create a content view each for CentOS-7.1, Apache-2.0, PostgreSQL-7.1 along with a composite content view WebServer which includes all of these content views.
  • For activation keys the same two basic approaches exist. Either create a single activation key for a specific kind of use-case (like “corporate_webserver_prod”), which uses the WebServer Content View and selects all subscriptions necessary to run the service. Alternatively create separate activation keys like “basic_centos_7_prod”, “webserver_prod”, and “database_mysql_prod”, all using the same content view (WebServer) along with a different set of subscriptions.

Errata Management

Information relevant to errata management is available in various locations around the orcharhino Management UI. This subsubsection exists to collect the entire workflow pertinent to errata management in a single place. As such, it is meant to complement the relevant documentation elsewhere in this document, and will make frequent references.

Important

When dealing with errata, care must be taken to distinguish between applicable and installable errata. An erratum is applicable to a content host if that host has packages affected by an issue that the erratum fixes. An erratum is installable, if it is both applicable, as well as present in the relevant content view version (such that the relevant content host has access to it).

The expected workflow for obtaining and applying errata goes as follows:

  1. New errata are obtained when some relevant repository/product (that provides errata) is synchronized (see also: Products, Repositories, and Synchronization from the Setup section above). Assuming a sync plan (see also Sync Plans) is in use, this process requires no user input.

  2. Any content hosts with any applicable errata (see the info box above), will now display a relevant warning on both the all hosts page, as well as their individual host overview page (see also All Hosts and Viewing a Host). Note that the content hosts page (as well as any content host overview pages) list only installable, but NOT applicable errata (see also Content Hosts and Viewing a Content Host).

  3. Once alerted to the presence of applicable errata, the orcharhino user can review new errata (select them for application) on the errata page (see Errata).

    Note

    To help choose which errata to select for application, each erratum has a detailed description, as well as a list of affected packages on the relevant erratum overview page. (See also Viewing an Erratum).

  4. Detailed documentation on applying any chosen errata can be found in the Applying Errata section of the Errata page. This process generally involves publishing a new minor content view version (see Content Views) to ensure any merely applicable errata also become installable.

  5. Once the desired errata are installable, they can be installed via remote execution, or directly on the host in question. There is a checkbox to do so as part of the previous step.