[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Changes to cartridges in master



As part of the long term move towards providing greater flexibility and control of cartridges, the pull https://github.com/openshift/origin-server/pull/4590 contains the initial work to allow the broker to track exact versions of cartridges.  The broker keeps a copy of each "version" of a cartridge it sees, and also allows an administrator to disable or enable a cartridge from showing up in the list of cartridges users see.  You can also import a downloadable cartridge and make it visible to users, although for now it still behaves exactly like a downloadable cartridge.

## What's changed?

Up until today, the broker would make a call to the ApplicationContainerProxy to get the cartridges from a random node, and then cache those in memory (or disk, or in memcached) for a period of time.  Now, a new collection in Mongo has been created called cartridge_types and when the broker needs to lookup a cartridge's definition it checks Mongo for that cartridge.  An application created with a cartridge tracks the exact version that created it.  If an administrator updates that cartridge, only new applications will get the new cartridge.  

Each cartridge document in mongo represents one version of a cartridge:

    {
      _id: <uuid>
      name: "example-cartridge-0.1"
      manifest_text: <manifest stored as JSON>,
      predecessor: <id of earlier version or null>,
      priority: <a date>,

      ... // extra metadata
    }

An administrator starts by importing cartridges from a specific node (or any node) into the broker via the new oo-admin-ctl-cartridge command:

   oo-admin-ctl-cartridge -c import-node [--node <mcollective_identity>]

You can specify a node to read from directly, or let OpenShift choose.  When you run the first time, you should see the following:

    $ oo-admin-ctl-cartridge -c import-node
    Updating 37 cartridges ...
    52ec19078291909962000001 # A 10gen-mms-agent-0.1
    52ec19078291909962000002 # A cron-1.4
    52ec19078291909962000003 # A diy-0.1
    52ec19078291909962000004 # A haproxy-1.4
    52ec19078291909962000005 # A jbossas-7
    52ec19078291909962000006 # A jbosseap-6
    52ec19078291909962000007 # A jbossews-1.0
    52ec19078291909962000008 # A jbossews-2.0
    52ec19078291909962000009 # A jenkins-1
    52ec1907829190996200000a # A jenkins-client-1
    52ec1907829190996200000b # A metrics-0.1
    ....

The broker is informing you that it found 37 unique cartridge versions from the node, and that each of them is "new" (no existing version has been created).  If at this point you ran 'rhc cartridges', you would see nothing.  That's because by default oo-*-cartridge won't make that an imported version visible to a user.  Since the node still tracks the cartridges, most of the time you'll want to use the --activate flag to "activate" the cartridge.

An activated cartridge just means that it's the official "use this version" of a cartridge with that name (there can be only one).  So you could have two versions of a php-5.3 cartridge that the broker knows about, but at most one of them can be active.  If no version of a cartridge named "foo-0.1" is active, users won't see it in the list of cartridges.

We want to activate the new versions, but since we already have the latest versions of the cartridges on the system, another 'import-node' call won't do anything.  So we need to "clean" - remove unused versions of inactive cartridges.

    $ oo-admin-ctl-cartridge -c clean
    Deleting all unused cartridges from the broker ...
    52ec19078291909962000001 # 10gen-mms-agent-0.1
    52ec19078291909962000002 # cron-1.4
    52ec19078291909962000003 # diy-0.1
    52ec19078291909962000004 # haproxy-1.4
    52ec19078291909962000005 # jbossas-7
    ....

Now we can pass activate to import-node and the cartridges will be "added" and set to active (because we cleaned up the unused ones we just added):

    $ oo-admin-ctl-cartridge -c import-node --activate
    Updating 37 cartridges ...
    52ec19078291909962000001 # A 10gen-mms-agent-0.1 (active)
    52ec19078291909962000002 # A cron-1.4 (active)
    52ec19078291909962000003 # A diy-0.1 (active)
    52ec19078291909962000004 # A haproxy-1.4 (active)
    52ec19078291909962000005 # A jbossas-7 (active)
    52ec19078291909962000006 # A jbosseap-6 (active)
    ....

Run 'rhc cartridges' and these will appear instantly.

When an application is created, OpenShift will either select the "active" version of that cartridge or return an error (if you specify the exact ID of a cartridge you want to use, in which case you get the cart you need).  The app will then track the version of the cartridge it was created with until you "migrate" it.

Migration is a very simple operation for now.  It merely updates apps pointing to older cartridges to point to newer versions of cartridges.  In the future it'll become much more powerful as we move into Docker and other capabilities.  To migrate, run:

    $ oo-admin-ctl-migrate -c migrate
    52e5c970829190e3c700000e ! -> 52ebdc958291905410000001 INCOMPLETE       0 /   1 left php-5.3
    Migrated 0/1 cartridges
    Updated 0 applications
    Skipped 1 applications with pending jobs

What you see here is the output of a migration that couldn't be completed because someone else was making changes to the application.  In that case the app is skipped - a subsequent run would finish the migration.  After you migrate, be sure to "clean", which will remove any versions that were completely migrated.

## Changes to the REST API

To enable builders and other consumers to know exactly what version of a cartridge is in use, the following changes have been made to API versions equal to or newer than 1.2:

  GET /application/<id>/cartridges now returns:

    id:                <the unique id of the cartridge installed to this app>
    obsolete:          <true if the cartridge has been marked as obsolete, or nil otherwise>
    added_time:        <the date the cartridge was added to this application>
    activation_time:   <the date the cartridge version was marked active, or nil if it is not active>
    automatic_updates: <true if this cartridge is updated whenever a security update is released>

  GET /cartridge/<name_or_id> now returns:

    id:                <the unique id of the cartridge installed to this app>
    obsolete:          <true if the cartridge has been marked as obsolete, or nil otherwise>
    creation_time:     <the date the cartridge version as imported to the broker>
    activation_time:   <the date the cartridge version was marked active, or nil if it is not active>
    automatic_updates: <true if this cartridge is updated whenever a security update is released>

To see all cartridges with a given category, use:

  GET /cartridges?category=<value>

Use the SHOW_CARTRIDGE link in the API document to fetch a cart by name (replace :name in the link) or use SHOW_CARTRIDGE_BY_ID (replace :id in the link) when doing HATEOS link resolution.

When creating an application, you can now pass the 'id' argument as a hash to the cartridges list to add a cartridge by id:

  POST /domain/<name>/applications

    "cartridges": [{"id": "<unique id of a cartridge>"}]


## For Administrators

When deploying a new version of one or more cartridges, use the following steps:

1) Install the cartridge(s) on an appropriate node (follow node level steps as usual)
2) From a broker system (any), run 

   oo-admin-ctl-cartridge -c import-node --node <identity from #1> --activate
   oo-admin-ctl-cartridge -c migrate
   # if the above command returns a zero exit code, all possible migrations have been completed successfully
   oo-admin-ctl-cartridge -c clean

This does not remove the need for migrations for gears, or for migrations when mongo data structures are changed.  However, in the future those capabilities will become a part of these commands, and this flow will continue.

If you have further questions, please let me know!

Clayton Coleman | OpenShift


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]