Candlepin 2.0 will involve a massive data model change affecting how products, subscriptions, and pools are stored. Previously, products were a global entity across the entire Candlepin server, there would be only one record for any given product ID. Custom products would have to be created in this global namespace, which is a bit odd and not desirable in a multi-tenant scenario. On import, one tenant could trigger certificate regenerations for another tenant if an updated version of the product came in.
To facilitate storing products and product content in a per-org manner, several changes to the database and object model have been made. While the normal deployment process will make these changes automatically, any existing tooling and/or scripts will need to be updated in accordance with the changes listed below.
At the time of writing, the deprecated tables, and any data contained therein, are left as-is in the database. While these tables will be entirely unused, they will be retained for a period to ensure a failed or incomplete migration can be manually fixed or completed if necessary. These tables will eventually be dropped in a future update.
POST /owners/:key/products/:product_id instead of POST /products/:product_id). Products and content can still be retrieved without the organization, but only using the product’s or content’s UUID (GET /products/:product_uuid). When fetching content using its UUID, the request must be made with an admin-level account.GET owners/:owner_key/products/:product_id/certificate instead of GET products/:product_id/certificate). The owner may be omitted, but only if the product is referenced by its UUID (GET /products/:product_uuid/certificate).Migrating to Candlepin 2.0 from an earlier version is similar to standard upgrade done with the included deployment scripts. Though, due to the extensive nature of the changes made in this version, it is highly recommended to use additional tooling to ensure the upgrade and migration goes as smoothly as possible.
To begin, make sure the local database is populated by running the “populate DB” task. This is only required in hosted environments and will no-op in standalone environments, so it’s safe to do if you’re unsure whether or not it’s necessary.
curl -k -u admin:admin "https://localhost:8443/candlepin/admin/pophosteddb"
Wait a bit for the task to finish (or periodically check the job status via /jobs/{job_id}), then take a snapshot of the environment with the cmv utility.
cd ~/devel/candlepin/server
./bin/cmv snapshot
Note: The cmv utility operates by caching the received JSON for later comparison. Depending on the size of your data set, it may require a large amount of disk space to snapshot the entire deployment. For comparison, a snapshot of the Candlepin test data is around 900 kib for three organizations with 85 products and 25 contents.
Once the snapshot is finished, a normal upgrade can be done via the deploy script.
./bin/deploy
Finally, the migration can be verified with the cmv tool. While cmv can be run without any parameters, there are several expected changes/warnings that can be safely ignored (more on this below). To exclude all the expected warnings, the following command can be used:
./bin/cmv verify --exclude orgs.pools.providedProducts.id --exclude orgs.pools.providedProducts.created --exclude orgs.pools.providedProducts.updated --exclude orgs.pools.productAttributes.id --exclude orgs.pools.productAttributes.productId --exclude orgs.pools.productAttributes.created --exclude orgs.pools.upstreamPoolId --exclude orgs.pools.upstreamEntitlementId --exclude orgs.pools.upstreamConsumerId --exclude orgs.products.uuid --exclude orgs.products.href --exclude orgs.products.productContent.content.uuid --exclude orgs.pools.derivedProductAttributes --exclude orgs.pools.derivedProductAttributes.id --exclude orgs.pools.derivedProductAttributes.productId --exclude orgs.pools.derivedProductAttributes.created --exclude orgs.pools.derivedProductAttributes.updated --exclude orgs.pools.derivedProvidedProducts.id --exclude orgs.pools.derivedProvidedProducts.created --exclude orgs.pools.derivedProvidedProducts.updated
With this command, the verification should complete without any errors or warnings. If so, the migration was completed successfully. Otherwise, steps may be necessary to manually complete the migration, or it may be necessary to roll back and try again.
As noted above, there are several expected changes that will show up in a vanilla cmv verify during migration to Candlepin 2.0. Most are related to minor changes in the JSON returned by API calls, while a few others relate to precision issues with the migration to new database tables.
The providedProducts and derivedProvidedProducts fields used to be populated directly by Candlepin’s internal model objects, all of which have an ID and created and updated timestamp fields. With the migration to Candlepin 2.0, some collection objects have been converted to DTOs which lack these fields. As a result, the id, created and updated fields are no longer present in the API response.
The product attribute values no longer include internal-use model details such as the ID and raw timestamps for created and updated times. Instead, the timestamps provided are standardized timestamps which no longer include milliseconds.
In the transition to per-organization products and content, both objects received a new identifier to allow multiple organizations to represent different states of the same products.
With products now being per-organization, the URL used to refer back to a given product has been updated to reference the product via UUID rather than just RHID (which is not unique between organizations). This change is now reflected in the product JSON.
In Candlepin 2.0, the subscription object has been relegated to a transient DTO used only during pool refresh and manifest import. These fields, which point back to upstream data sources, have been moved to the pool object.