A package is a collection of YAML files that are zipped up into a file with the following naming convention: [PackageName]-[PackageVersion].zip (for example: mypackage-1.0.0.zip).

A package can define a single application or a group of applications.

The single application package file, mypackage-1.0.0.zip, when unzipped, should have the following directory structure:

mypackage-1.0.0
├── package.yml
├── templates
│   └── template.yml
└── values.yml

The package.yml file contains metadata about the package and is used to support Skipper’s search functionality. The template.yml file contains placeholders for values that are specified in the values.yml file. When installing a package, placeholder values can also be specified, and they would override the values in the values.yml file. The templating engine that Skipper uses is JMustache. The YAML files can have either .yml or .yaml extensions.

The helloworld-1.0.0.zip or helloworld-docker-1.0.0.zip files are good examples to use as a basis to create your own package "'by hand'".

The source code for the helloworld sample can be found here.

A package can contain a group of applications bundled in it. In those cases, the structure of the package would resemble the following:

mypackagegroup-1.0.0
├── package.yml
├── packages
│   ├── app1
│   │   ├── package.yml
│   │   ├── templates
│   │   │   └── log.yml
│   │   └── values.yml
│   └── app2
│       ├── package.yml
│       ├── templates
│       │   └── time.yml
│       └── values.yml
└── values.yml

In the preceding example, the mypackagegroup still has its own package.yml and values.yml to specify the package metadata and the values to override. All the applications inside the mypackagegroup are considered to be sub-packages and follow a package structure similar to the individual packages. These sub packages need to be specified inside the packages directory of the root package, mypackagegroup.

The ticktock-1.0.0.zip file is a good example to use as a basis for creating your own package 'by-hand'.

The package.yml file specifies the package metadata. A sample package metadata would resemble the following:

# Required Fields
apiVersion: skipper.spring.io/v1
kind: SkipperPackageMetadata
name: mypackage
version: 1.0.0

# Optional Fields
packageSourceUrl: https://github.com/some-mypackage-project/v1.0.0.RELEASE
packageHomeUrl: http://some-mypackage-project/
tags: skipper, mypackage, sample
maintainer: https://github.com/maintainer
description: This is a mypackage sample.

Required Fields:

Optional Fields:

	Note
	Currently, the package search functionality is only a wildcard match against the name of the package.

A Package Repository exposes an index.yml file that contains multiple metadata documents and that uses the standard three dash notation --- to separate the documents — for example, index.yml.

The template.yml file has a package structure similar to that of the following example:

mypackage-1.0.0
├── package.yml
├── templates
│   └── template.yml
└── values.yml

template.yml commonly has content similar to the following:

# template.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: mypackage
  type: sample
spec:
  resource: maven://org.mysample:mypackage
  resourceMetadata:  maven://org.mysample:mypackage:jar:metadata:{{spec.version}}
  version: {{spec.version}}
  applicationProperties:
    {{#spec.applicationProperties.entrySet}}
    {{key}}: {{value}}
    {{/spec.applicationProperties.entrySet}}
  deploymentProperties:
    {{#spec.deploymentProperties.entrySet}}
    {{key}}: {{value}}
    {{/spec.deploymentProperties.entrySet}}

Skipper knows only how to manage applications defined in this way. A future release will introduce support for different formats — for example supporting the Cloud Foundry manifest format.

The apiVersion, kind, and spec.resource are required.

The spec.resource and spec.version define where the application executable is located. The spec.resourceMetadata field defines where a Spring Boot Configuration metadata jar is located that contains the configuration properties of the application. This is either a Spring Boot uber jar hosted under a HTTP endpoint or a Maven or Docker repository. The template placeholder {{spec.version}} exists so that the version of a specific application can be easily upgraded without having to create a new package .zip file.

The resource is based on http:// or maven:// or docker:. The format for specifying a resource follows:

spec:
  resource: http://example.com/app/hello-world
  version: 1.0.0.RELEASE

spec:
  resource: docker:springcloud/spring-cloud-skipper-samples-helloworld
  version: 1.0.0.RELEASE

spec:
  resource: docker:<user>/<repo>
  version: <tag>

13.4.3 Maven Resources

The following example shows a typical spec for Maven:

spec:
  resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld:1.0.0.RELEASE
  version: 1.0.0.RELEASE

The mapping to Maven artifact names follows

spec:
  resource: maven://<maven-group-name>:<maven-artifact-name>
  version:<maven-version>

There is only one setting to specify with Maven repositories to search. This setting applies across all platform accounts. By default, the following configuration is used:

maven:
  remoteRepositories:
    springRepo: https://repo.spring.io/libs-snapshot

You can specify other entries and also specify proxy properties. This is currently best documented here. Essentially, this needs to be set as a property in your launch properties or manifest.yml (when pushing to PCF), as follows:

# manifest.yml
...
env:
    MAVEN_REMOTE_REPOSITORIES_{{REPOSITORY_NAME}}_URL: https://repo.spring.io
...

The metadata section is used to help search for applications after they have been installed. This feature will be made available in a future release.

Currently, only the SpringCloudDeployerApplication kind is supported, which means the applications can be deployed into the target platforms only by using their corresponding Spring Cloud Deployer implementations (CF, Kubernetes Deployer, and so on).

The spec contains the resource specification and the properties for the package.

The resource represents the resource URI to download the application from. This would typically be a Maven co-ordinate or a Docker image URL.

The SpringCloudDeployerApplication kind of application can have applicationProperties and deploymentProperties as the configuration properties.

The application properties correspond to the properties for the application itself.

The deployment properties correspond to the properties for the deployment operation performed by Spring Cloud Deployer implementations.

	Note
	The name of the template file can be anything, as all the files under templates directory are loaded to apply the template configurations.

The values.yml file contains the default values for any of the keys specified in the template files.

For instance, in a package that defines one application, the format is as follows:

version: 1.0.0.RELEASE
spec:
  applicationProperties:
    server.port: 9090

If the package defines multiple applications, provide the name of the package in the top-level YML section to scope the spec section. Consider the example of a multiple application package with the following layout:

ticktock-1.0.0/
├── packages
│   ├── log
│   │   ├── package.yml
│   │   └── values.yml
│   └── time
│       ├── package.yml
│       └── values.yml
├── package.yml
└── values.yml

The top-level values.yml file might resemble the following:

#values.yml

hello: world

time:
  appVersion: 1.3.0.M1
  deployment:
    applicationProperties:
      log.level: WARN
      trigger.fixed-delay: 1
log:
  deployment:
    count: 2
    applicationProperties:
      log.level: WARN
      log.name: skipperlogger

The preceding values.yml file sets hello as a variable available to be used as a placeholder in the packages\log\values.yml file and the packages\time\values.yml. However, the YML section under time: is applied only to the packages\time\values.yml file and the YML section under log: is applied only to the packages\time\values.yml file.

After creating the package in the structure shown in the previous section, we can compress it in a zip file with the following naming scheme: [PackageName]-[PackageVersion].zip (for example, mypackage-1.0.0.zip).

For instance, the package directory would resemble the following before compression:

mypackage-1.0.0
├── package.yml
├── templates
│   └── template.yml
└── values.yml

The zip file can be uploaded into one of the local repositories of the Skipper server. By default, the Skipper server has a local repository with the name, local.

By using the Skipper shell, we can upload the package zip file into the Skipper server’s local repository, as follows:

skipper:>package upload --path /path-to-package/mypackage-1.0.0.zip
Package uploaded successfully:[mypackage:1.0.0]

If no --repo-name is set, the upload command uses local as the repository to upload.

We can then use the package list or package search command to see that our package has been uploaded, as shown (with its output) in the following example:

skipper:>package list
╔═════════════════╤═══════╤════════════════════════════════════════════════════════════════════════════════╗
║      Name       │Version│                                  Description                                   ║
╠═════════════════╪═══════╪════════════════════════════════════════════════════════════════════════════════╣
║helloworld       │1.0.0  │The app has two endpoints, /about and /greeting in English.  Maven resource.    ║
║helloworld       │1.0.1  │The app has two endpoints, /about and /greeting in Portuguese.  Maven resource. ║
║helloworld-docker│1.0.0  │The app has two endpoints, /about and /greeting in English.  Docker resource.   ║
║helloworld-docker│1.0.1  │The app has two endpoints, /about and /greeting in Portuguese.  Docker resource.║
║mypackage        │1.0.0  │This is a mypackage sample                                                      ║
╚═════════════════╧═══════╧════════════════════════════════════════════════════════════════════════════════╝

In this section, we create a package that can be deployed by using Spring Cloud Deployer implementations.

For this package, we are going to create a simple package and upload it to our local machine.

To get started creating your own package, create a folder following a naming convention of [package-name]-[package-version]. In our case, the folder name is demo-1.0.0. In this directory, create empty files named values.yml and package.yml and create a templates directory. In the templates directory, create an empty file named template.yml.

Go into the package.yml where we are going to specify the package metadata. For this app, we fill only the minimum values possible, as shown in the following example:

# package.yml

apiVersion: skipper.spring.io/v1
kind: SkipperPackageMetadata
name: demo
version: 1.0.0
description: Greets the world!

	Important
	Ensure that your name and version matches the name and version in your folder name, or you get an error.

Next, open up your templates/template.yml file. Here, we are going to specify the actual information about your package and, most importantly, set default values. In the template.yml, copy the template for the kind SpringCloudDeployerApplication from the preceding sample. Your resulting template.yml file should resemble the following:

# templates/template.yml

apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: demo
spec:
  resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld
  version: {{version}}
  applicationProperties:
    {{#spec.applicationProperties.entrySet}}
    {{key}}: {{value}}
    {{/spec.applicationProperties.entrySet}}
  deploymentProperties:
    {{#spec.deploymentProperties.entrySet}}
    {{key}}: {{value}}
    {{/spec.deploymentProperties.entrySet}}

The preceding example file specifies that our application name is demo and finds our package in Maven. Now we can specify the version, applicationProperties, and deploymentProperties in our values.yml, as follows:

# values.yml

# This is a YAML-formatted file.
# Declare variables to be passed into your templates
version: 1.0.0.RELEASE
spec:
  applicationProperties:
    server.port: 8100

The preceding example sets the version to 1.0.0.RELEASE and also sets the server.port=8100 as one of the application properties. When the Skipper Package reader resolves these values by merging the values.yml against the template, the resolved values resemble the following:

# hypothetical template.yml

apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: demo
spec:
  resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld
  version: 1.0.0.RELEASE
  applicationProperties:
    server.port: 8100
  deploymentProperties:

The reason to use values.yml instead of entering the values directly is that it lets you overwrite the values at run time by using the --file or --properties flags.

We have finished making our file. Now we have to zip it up. The easiest way to do is by using the zip -r command on the command line, as follows:

$ zip -r demo-1.0.0.zip demo-1.0.0/
  adding: demo-1.0.0/ (stored 0%)
  adding: demo-1.0.0/package.yml (deflated 14%)
  adding: demo-1.0.0/templates/ (stored 0%)
  adding: demo-1.0.0/templates/template.yml (deflated 55%)
  adding: demo-1.0.0/values.yml (deflated 4%)

Armed with our zipped file and the path to it, we can head to Skipper and use the upload command, as follows:

skipper:>package upload --path /Users/path-to-your-zip/demo-1.0.0.zip
Package uploaded successfully:[demo:1.0.0]

Now you can search for it as shown previously and then install it, as follows

skipper:>package install --package-name demo --package-version 1.0.0 --release-name demo
Released demo. Now at version v1.

Congratulations! You have now created, packaged, uploaded, and installed your own Skipper package!