Package Resolution

Use Apcera policy for package management to control what packages are used in the system.

Requirements:

  • Apcera Platform is installed and running (latest version).
  • Platform is bootstrapped with packages for JDK 1.7 and 1.8.
  • Download Apcera sample apps from https://github.com/apcera/sample-apps/archive/master.zip and extract to a known directory.
  • Log in to the web console for your cluster, for example: https://console..apcera-platform.io. (Run apcera-setup info to get the web console URL for your cluster.)

Packages in the Apcera Platform

Packages are compressed archive files (tarballs) that are used to resolve the dependencies of your apps so they can be executed and be managed by the platform. You can use policy to easily automate and control package dependency resolution.

1: View system packages

Log in to the web console for your platform.

Select Packages in the left navigation.

Search for the string jdk.

You see that Apcera provides Java runtime packages for JDK versions 1.7 and 1.8.

Tutorial Image

2: View package resolution policy

Select Policy in the left navigation.

Select the packageresolution policy document from the list.

Reviewing this policy, you see that it provides package resolution rules.

The package allow claim lets you use packages in the package::/apcera namespace.

The package default claim ensures that JDK 1.8 is used by to satisfy apps with the Java runtime dependency.

Tutorial Image

3: Create Java 1.8 app

Target your cluster and log in using APC.

apc target <cluster-name>.apcera-platform.io

apc login --basic

CD to the sample app directory we will use for this tutorial.

cd sample-apps-master/example-java-hello/

Create and run the Java Hello app.

apc app create java18 -dr --start --batch

In the web console, select Apps and select the java18 app.

In the Environment tab, scroll down to the Packages section. You see that the app uses the default JDK 1.8 runtime package (openjdk-1.8).

Tutorial Image

3: Create Java 1.7 app

Create another version of the Java Hello app, this time using the Java 1.7 runtime.

apc app create java17 --depends-on runtime.java-1.7 -dr --batch

You should see that the app is created successfully:

Packaging... done
Creating package "java17"... done
Uploading package contents... 100.0% (533/533 B)
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::java' pipeline, 1 stager(s) defined.
[staging] Launching instance of stager 'java'...
[staging] Downloading package for processing...
[staging] Found JavaSource application
[staging] Stager needs relaunching
[staging] Launching instance of stager 'java'...
[staging] Downloading package for processing...
[staging] Found JavaSource application
[staging] Compiling application source...
[staging] Detected application main as: HelloWorld
[staging] Staging is complete.
Creating app "java17"... done
Start Command: java  HelloWorld
App may be started with:
  > apc app start java17
Success!

Start the app and verify that it runs successfully.

apc app start java17
Starting job... done
Waiting for the job to start...
[stdout][347ae22c] Hello, World
Success!

In the web console, select Apps and select the java17 app.

In the Environment tab, scroll down to the Packages section. You see that the app uses the JDK 1.7 runtime package (openjdk-1.7). In this case, you overrode default package resolution to create the app using the --depends-on flag specifying the JDK 1.7 runtime package.

Tutorial Image

Step 4: Retire JDK 1.7 package

In the web console, select the Policy link from the left navigation.

Select the packageresolution policy document.

Click Edit Policy.

Add the following policy rule to retire the JDK 1.7 package.

{ package.retire "package::/apcera/pkg/runtimes::openjdk-1.7.0-u101-b00" }

Tutorial Image

Click Apply Changes when you are done.

Now try to create another Java app using 1.7.

apc app create java17-retired --depends-on runtime.java-1.7 -dr --batch

Per policy, you are not allowed to use the Java 1.7 package to create a new app because this package is retired.

Packaging... done
Creating package "java17-retired"... done
Uploading package contents... 100.0% (533/533 B)
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::java' pipeline, 1 stager(s) defined.
[staging] Error: no packages satisfy dependency "runtime.java-1.7"
[staging] Error: Failed to clone stager job
[staging] Staging pipeline has been aborted
[staging] "package::/sandbox/admin::java17-retired" has failed to stage
Package "java17-retired" deleted
Error: Staging has failed.
Try `apc help` for more information.

Step 5: Explore package resolution

If you retire a package that an existing app is using, Apcera will not stop that app and you can restart it. However, if you attempt to redeploy the app using the retired package, the deployment will fail.

To demonstrate this, select the existing java17 app in the web console. Note that it continues to run using the Java 1.7 runtime. Click Restart and the app succesfully restarts.

But, if you attempt to redeploy the app, the deployment fails due to the retirement of the JDK 1.7 runtime package.

apc app deploy java17 --depends-on runtime.java­1.7 --batch
Packaging... done
Creating package "java17-1484612639"... done
Uploading package contents... 100.0% (533/533 B)
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::java' pipeline, 1 stager(s) defined.
[staging] Error: no packages satisfy dependency "runtime.java\u00ad1.7"
[staging] Error: Failed to clone stager job
[staging] Staging pipeline has been aborted
[staging] "package::/sandbox/admin::java17-1484612639" has failed to stage
Package "java17-1484612639" deleted
Error: Staging has failed.
Try `apc help` for more information.

To deploy the app, you must use a valid package. In this case, we will use the default JDK runtime (1.8).

Since the runtime package is changing, we need to stop the app first before deploying it.

apc app stop java17
Stopping job... done
Success!

Now deploy and start the app using the default JDK package.

apc app deploy java17 --start --batch
Packaging... done
Creating package "java17-1484612791"... done
Uploading package contents... 100.0% (533/533 B)
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::java' pipeline, 1 stager(s) defined.
[staging] Launching instance of stager 'java'...
[staging] Downloading package for processing...
[staging] Found JavaSource application
[staging] Stager needs relaunching
[staging] Launching instance of stager 'java'...
[staging] Downloading package for processing...
[staging] Found JavaSource application
[staging] Compiling application source...
[staging] Detected application main as: HelloWorld
[staging] Staging is complete.
Updating package name from "java17-1484612791" to "java17"... done
Updating "java17"... done
Start Command: java  HelloWorld

You are attempting to deploy app "java17" without setting a start command or a staging pipeline. This may cause problems if a start command was not already set.

Starting "java17"... done
Waiting for the job to restart...
[stdout][42604e3f] Hello, World
Deleting old package "package::/sandbox/admin::java17-1484612802" [--keep-previous=false]
Package "java17" deleted
Success!

In the web console, select Apps and locate your java17 app.

In the Environment tab, scroll down to the Packages section. You see that the app is using the default JDK 1.8 runtime package (openjdk-1.8).

Tutorial Image