Version 1.0.0.M3

© 2012-2017 Pivotal Software, Inc.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Preface

1. About the documentation

The Spring Cloud Skipper reference guide is available in html. The latest copy is available at docs.spring.io/spring-cloud-skipper/docs/current-SNAPSHOT/reference/html/.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

2. Getting help

Having trouble with Spring Cloud Skipper, We’d like to help!

All of Spring Cloud Skipper is open source, including the documentation! If you find problems with the docs; or if you just want to improve them, please get involved.

Spring Cloud Skipper Overview

Skipper is a lightweight tool that allows you to discover Spring Boot applications and manage their lifecycle on multiple Cloud Platforms. You can use Skipper standalone or integrate it with Continuous Integration pipelines to help implement the practice of Continuous Deployment.

Skipper consists of a server application that exposes a HTTP API. A shell application provides easy to use commands to interact with the server. The server uses a database to store state. Documentation to call the HTTP API is available in the REST API Guide.

Applications in Skipper are bundled as packages which contain a templated configuration file and a default set of values that are used to fill in the template. You can override these defaults when installing or upgrading a package. Skipper provides a means to orchestrate the upgrade/rollback procedure of applications between different versions, taking the minimal set of actions to bring the system to the desired state.

Skipper’s design is influenced by a large number of projects in the Kubernetes ecosystem that perform resource templating and/or orchestration, hence the nautically inspired project name Skipper. In particular, Helm's approach to present a user with familiar apt-get or brew like installation experience was a big influence.

3. Features

The main features are:

  • Define multiple platform accounts where Spring Boot applications can be deployed.. Supported platforms are Local, Cloud Foundry, and Kubernetes.

  • Substitute variables in Mustache templated files that describe how to deploy applications to a platform.

  • Search Package Repositories for existing applications.

  • Upgrade/Rollback a package based on a simple blue/green workflow.

  • Store the history of resolved template files (aka 'application manifests') which represent the final description of what has been deployed to a platform for a specific release.

  • Use via a standalone interactive shell or web API.

4. Concepts

The main concepts are Platforms, Packages, Repositories, Releases and Release Workflows.

Platforms are where your apps run. For the first release of Skipper, support for deploying applications to platforms is provided by the Spring Cloud Deployer family of libraries. This allows Skipper to deploy Spring Boot applications to Cloud Foundry, Kubernetes and your local machine. You can configure a single Skipper server to deploy to multiple platforms, with each platform account is identified by a unique name.

The Spring Cloud Deployer libraries for Apache YARN, Apache Mesos, Redhat Openshift and Hashicorp Nomad were not bundled with Skipper in 1.0 M2. Skipper 1.0 M2 has only been tested using the local, Cloud Foundry and Kubernetes Deployers.

Packages defines the basic recipe for installing an application. A package can define a single application or it can define a group of applications. It contains descriptive metadata, the location of the Spring Boot uberjar and the default application or deployment properties. The location of the uberjar can be a Maven repository, docker registry, file location, or http location. A package is a collection of Yaml files that are zipped up into a file with a naming convention such as name-version.zip, e.g. myapp-1.0.3.zip.

Repositories are where package metadata and zip files are hosted. Repositories and be 'local' or 'remote'. A remote repository is the one that is only accessible via http. Any arbitrary web app that serves up files off a file system can be used to host a remote repository as long as certain directory and file naming conventions are followed. A local repository is managed by the Skipper server and backed by a database. Skipper lets you search for packages that are hosted in repositories.

Releases are created in Skipper after you install, upgrade or rollback a package. A release has a name and you provide that name to perform operations against the release such as upgrading, rolling back and deleting applications. The release contains the fully resolved template files (aka 'application manifests') that represent the final description of what has been deployed to the platform. You can also query for releases to discover the state of packages that have been installed and retrieve the application manifests for a specific release.

Release Workflows are the steps taken to upgrade or rollback an application from one version to another. In Skipper terms, it is how we go from one Release to another on a Platform. Note, an upgrade may keep the same version, but instead update applications properties.

Getting started

This section describes the minimal steps to install Skipper in addition to installing a sample application. It is the "three second tour". After completing this section, you can move on to the Three minute Tour. When you are ready to dive deeper, head on over to the Using Skipper (well not really three hours…​).

5. System Requirements

The Skipper server is a Spring Boot application. Both the Server and Shell are based on Java 8. The server uses a RDBMS to store state. An embedded H2 database is used if you do not provide a Data Source configuration via Spring Boot configuration properties, find out more here Building. In the 1.0 M2 release the schema is autogenerated from JPA annotations, so a wide range of databases should work out of the box.

6. Installing Skipper

This section will cover installing Skipper on your local machine as it is the easiest way to get started. Installing Skipper on other platforms will be covered separately.

  • Download the Skipper Server and Shell apps:

wget http://repo.spring.io/milestone/org/springframework/cloud/spring-cloud-skipper-server/1.0.0.M3/spring-cloud-skipper-server-1.0.0.M3.jar

wget http://repo.spring.io/milestone/org/springframework/cloud/spring-cloud-skipper-shell/1.0.0.M3/spring-cloud-skipper-shell-1.0.0.M3.jar
  • Launch the Server and Shell apps:

java -jar spring-cloud-skipper-server-1.0.0.M3.jar


java -jar spring-cloud-skipper-shell-1.0.0.M3.jar

The default port that the server listens on is 7577. That is SKPR on a telephone keypad. :)

There is also a docker image hosted on dockerhub

  • Install some apps!

6.1. Using an External Database

By default Skipper uses an embedded H2 database if no spring.datasource property is specified. You can use other external databases by setting various spring.datasource properties. The database drivers for MySQL, Postgres, SQL Server, and HSQLDB are already on the classpath of the server. Here are a few sample commands that start the server using an external database.

# MySQL
java -jar spring-cloud-skipper-server/target/spring-cloud-skipper-server-1.0.0.M3.jar --spring.datasource.url=jdbc:mysql://localhost/skipper --spring.datasource.username=xxx --spring.datasource.password=xxx --spring.datasource.driver-class-name=org.mariadb.jdbc.Driver

# Postgres
java -jar spring-cloud-skipper-server/target/spring-cloud-skipper-server-1.0.0.M3.jar --spring.datasource.url=jdbc:postgresql://localhost:5432/skipper --spring.datasource.username=xxx --spring.datasource.password=xxx --spring.datasource.driver-class-name=org.postgresql.Driver

# MSSQL
java -jar spring-cloud-skipper-server/target/spring-cloud-skipper-server-1.0.0.M3.jar --spring.datasource.url='jdbc:sqlserver://172.16.101.143;databaseName=skipper' --spring.datasource.username=xxx --spring.datasource.password=xxx --spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver

# HSQLDB
java -jar spring-cloud-skipper-server/target/spring-cloud-skipper-server-1.0.0.M3.jar --spring.datasource.url=jdbc:hsqldb:hsql://localhost:9101/xxxx --spring.datasource.username=xxx --spring.datasource.driver-class-name=org.hsqldb.jdbcDriver

7. A three second tour

By default, Skipper will deploy apps to the local machine. The default configuration also has one local repository named local where you can upload packages, and one remote repository named experimental where some sample test packages are located. You can get a list of the package repositories by using the command repo list.

The shell supports tab completion.
skipper:>repo list
╔════════════╤═══════════════════════════════════════════════════════════╤═════╤═════╗
║    Name    │                            URL                            │Local│Order║
╠════════════╪═══════════════════════════════════════════════════════════╪═════╪═════╣
║experimental│http://skipper-repository.cfapps.io/repository/experimental│false│0    ║
║local       │http://10.55.13.45:7577                                    │true │1    ║
╚════════════╧═══════════════════════════════════════════════════════════╧═════╧═════╝

Search for the available packages using the search command.

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

Install the Maven based Hello World application using the install command. Since this application picks a random port for the http server by default, we specify the Spring Boot property server.port, prefixed via spec.applicationProperties.

skipper:>install --release-name helloworld-local --package-name helloworld --package-version 1.0.0 --properties spec.applicationProperties.server.port=8099
Released helloworld-local. Now at version v1.

You can now curl the greeting endpoint.

$ curl http://localhost:8099/greeting
Hello World!

The release name helloworld-local is used for subsequent commands such as status, upgrade or delete.

To see the status of the release, use the status command

skipper:>status --release-name helloworld-local
╔═══════════════╤═════════════════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Fri Oct 27 16:17:53 IST 2017                                                         ║
║Status         │DEPLOYED                                                                             ║
║Platform Status│All applications have been successfully deployed.                                    ║
║               │[helloworld-local.helloworld-v1], State = [helloworld-local.helloworld-v1-0=deployed]║
╚═══════════════╧═════════════════════════════════════════════════════════════════════════════════════╝

Let’s upgrade the release. The 1.0.1 package refers to a newly released application that changed the default value of the greeting to be in Portuguese.

skipper:>upgrade --release-name helloworld-local --package-name helloworld --package-version 1.0.1  --properties spec.applicationProperties.server.port=8100
helloworld-local has been upgraded.  Now at version v2.

This will deploy the new version of the application, wait until it is healthy, and then destroy the old version of the application.

skipper:>status --release-name helloworld-local
╔═══════════════╤═════════════════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Fri Oct 27 16:20:07 IST 2017                                                         ║
║Status         │DEPLOYED                                                                             ║
║Platform Status│All applications have been successfully deployed.                                    ║
║               │[helloworld-local.helloworld-v2], State = [helloworld-local.helloworld-v2-0=deployed]║
╚═══════════════╧═════════════════════════════════════════════════════════════════════════════════════╝

You can now curl the greeting endpoint at the new port and see that the application has been updated.

$ curl http://localhost:8100/greeting
Olá Mundo!

To delete the release, use the delete command.

skipper:>delete --release-name helloworld-local
helloworld-local has been deleted.
This example where the upgrade changed only a property of the application is not realistic. A more realistic example is the case where code has changed in the updated application so that it behaves differently.

You can also deploy the other packages named helloworld-docker to the local machine.

This example shows the most basic operations, other interesting commands such as manifest get, rollback, list and history are covered in the Three minute Tour.

Three minute Tour

Picking up from where the A three second tour left off, this section walks through the additional commands and other features of Skipper. Each section walks through the same set of operations, but for a different platform.

8. Local machine

Start up the server and shell as in the three second tour.

Let’s install and then update the hello world application.

skipper:>install --release-name helloworldlocal --package-name helloworld --package-version 1.0.0 --properties spec.applicationProperties.server.port=8099
Released helloworldlocal. Now at version v1.

You can now curl the greeting endpoint.

$ curl http://localhost:8099/greeting
Hello World!
$ curl http://localhost:8099/about
Hello World v1.0.0.RELEASE

We will use a YAML file to update the release. This application contains a Spring Boot @ConfigurationProperty named helloworld.greeting, so we will set that along with a standard Spring Boot property endpoints.sensitive=false. We will also bump the memory up to 2G, make the Boot actuator endpoint not sensitive and set the port to 8100.

The helloworld-upgrade-local.yml file contains

spec:
  applicationProperties:
    server.port: 8100
    endpoints.sensitive: false
    helloworld.greeting: yo
  deploymentProperties:
    spring.cloud.deployer.memory: 2048m

The upgrade command

skipper:>upgrade --release-name helloworldlocal --package-name helloworld --package-version 1.0.1 --file /home/mpollack/helloworld-upgrade-local.yml
helloworldlocal has been upgraded.  Now at version v2.

The current upgrade strategy is very simple, if the new app is healthy, the old app is removed. There is not a rolling upgrade option, all new apps are deployed, checked for health, and then previous versions removed. More flexible upgrade strategies are planned along with the introduction of the Spring Cloud State Machine project to orchestrate the update process.

You can now curl the greeting endpoint and the about endpoint or view them in your browser.

$ curl http://localhost:8100/greeting
yo
$ curl http://localhost:8100/about
Hello World v1.0.1.RELEASE

The list command shows you the current DEPLOYED and DELETED releases for every release name. In this case there is just one entry

skipper:>list
╔═══════════════╤═══════╤═════════════╤════════╤══════════╤═════════╤═════════╤════════════════════════════════════════════════════╗
║     Name      │Version│Last updated │ Status │ Package  │ Package │Platform │                  Platform Status                   ║
║               │       │             │        │   Name   │ Version │  Name   │                                                    ║
╠═══════════════╪═══════╪═════════════╪════════╪══════════╪═════════╪═════════╪════════════════════════════════════════════════════╣
║helloworldlocal│2      │Fri Oct 27   │DEPLOYED│helloworld│1.0.1    │default  │[helloworldlocal.helloworld-v2], State =            ║
║               │       │16:39:03 IST │        │          │         │         │[helloworldlocal.helloworld-v2-0=deployed]          ║
║               │       │2017         │        │          │         │         │                                                    ║
╚═══════════════╧═══════╧═════════════╧════════╧══════════╧═════════╧═════════╧════════════════════════════════════════════════════╝

You can get the full history of the release using the history command.

skipper:>history --release-name helloworldlocal
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║2      │Fri Oct 27 16:39:03 IST 2017│DEPLOYED│helloworld  │1.0.1          │Upgrade complete║
║1      │Fri Oct 27 16:37:59 IST 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

To see what changed, you can look at the Skipper manifest for each release using the manifest get command. A manifest diff command is coming in the next release.

skipper:>manifest get --release-name helloworldlocal --release-version 2

---
# Source: helloworld.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: helloworld
  type: demo
spec:
  resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld:1.0.1.RELEASE
  applicationProperties:
    server.port: 8100
    endpoints.sensitive: false
    helloworld.greeting: yo
  deploymentProperties:
    spring.cloud.deployer.memory: 2048m
    spring.cloud.deployer.count: 1

and

skipper:>manifest get --release-name helloworldlocal --release-version 1

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

Next we will use the rollback command to deploy an older version of the application. Since we have the manifest for that version, we have all we need to redeploy an earlier release.

skipper:>rollback --release-name helloworldlocal --release-version 1
helloworldlocal has been rolled back.  Now at version v3.

The history now shows a new v3 version, even though it is identical in terms of app behavior to the v2 version.

skipper:>history --release-name helloworldlocal
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║3      │Fri Oct 27 16:42:47 IST 2017│DEPLOYED│helloworld  │1.0.0          │Upgrade complete║
║2      │Fri Oct 27 16:39:03 IST 2017│DELETED │helloworld  │1.0.1          │Delete complete ║
║1      │Fri Oct 27 16:37:59 IST 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

You can now curl the greeting endpoint.

$ curl http://localhost:8099/greeting
Hello World!
$ curl http://localhost:8099/about
Hello World v1.0.0.RELEASE

9. Cloud Foundry

Skipper uses a Relational Database to store state. In this tour we will just be using the embedded database. You can modify the example manifest file below to bind to a relational database service instead of using the embedded database. You can find an example here.

applications:
- name: mlp-skipper
  host: mlp-skipper
  memory: 1G
  disk_quota: 1G
  timeout: 180
  instances: 1
  path: spring-cloud-skipper-server-1.0.0.M2.jar
env:
    SPRING_APPLICATION_NAME: mlp-skipper
    SPRING_CLOUD_SKIPPER_SERVER_ENABLE_LOCAL_PLATFORM: false
    SPRING_CLOUD_SKIPPER_SERVER_STRATEGIES_HEALTHCHECK.TIMEOUTINMILLIS: 300000
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_CONNECTION_URL: https://api.run.pivotal.io
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_CONNECTION_ORG: scdf-ci
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_CONNECTION_SPACE: space-mark
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_CONNECTION_USERNAME: <your-username>
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_CONNECTION_PASSWORD: <your-password>
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_CONNECTION_SKIP_SSL_VALIDATION: false
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_DEPLOYMENT_DELETE_ROUTES: false
    SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[cf-dev]_DEPLOYMENT_DOMAIN: cfapps.io

This defines cf-dev as a named Cloud Foundry account. You can define multiple Cloud Foundry accounts and reference them in the shell commands when ever there is a command option for --platform-name.

The deployment.deleteRoutes property is important if you are deploying HTTP apps. When doing an upgrade, setting this to false prevents the routes from disappearing after deleting the old application. The underlying Spring Cloud Deployer library for Cloud Foundry has this value set to true as the default.

Note you can also run the Skipper Server locally and deploy to Cloud Foundry. In this case, it is more convenient to specify the configuration as a skipper.yml file, shown below, and start the server with the option --spring.config.location=skipper.yml

spring:
  cloud:
    skipper:
      server:
        enableLocalPlatform: false
        platform:
          cloudfoundry:
            accounts:
              cf-dev:
                connection:
                  url: https://api.run.pivotal.io
                  org: scdf-ci
                  space: space-mark
                  username: <your-username>
                  password: <your-password>
                  skipSslValidation: false
                deployment:
                  deleteRoutes: false
                  domain: cfapps.io

When you start the Skipper shell, by default it tries to look for the Skipper server on the same (local) machine. To specify the Skipper server that is running on Cloud Foundry, use the CF route with the config command

skipper:>config --uri https://mlp-skipper.cfapps.io/api
Successfully targeted https://mlp-skipper.cfapps.io/api

The repo list command shows the experimental and local repositories, since they are configured by default.

skipper:>repo list
╔════════════╤═══════════════════════════════════════════════════════════╤═════╤═════╗
║    Name    │                            URL                            │Local│Order║
╠════════════╪═══════════════════════════════════════════════════════════╪═════╪═════╣
║experimental│http://skipper-repository.cfapps.io/repository/experimental│false│0    ║
║local       │http://d4d6d1b6-c7e5-4226-69ec-01d4:7577                   │true │1    ║
╚════════════╧═══════════════════════════════════════════════════════════╧═════╧═════╝

and the search command shows

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

The command platform list shows which platforms the server has been configured with, in this case just one Cloud Foundry platform. Disabling the local platform with the property enableLocalPlatform = false is why the default local platform does not appear.

skipper:>platform list
╔══════╤════════════╤═════════════════════════════════════════════════════════════════════════╗
║ Name │    Type    │                               Description                               ║
╠══════╪════════════╪═════════════════════════════════════════════════════════════════════════╣
║cf-dev│cloudfoundry│org = [scdf-ci], space = [space-mark], url = [https://api.run.pivotal.io]║
╚══════╧════════════╧═════════════════════════════════════════════════════════════════════════╝

Let’s install the Hello World app, specifically, the maven based artifact.

skipper:>install --release-name helloworldpcf --package-name helloworld --package-version 1.0.0 --platform-name cf-dev --properties spec.deploymentProperties.spring.cloud.deployer.cloudfoundry.route=helloworldpcf.cfapps.io
Released helloworldpcf. Now at version v1.

If you do not specify --platform-name cf-dev the command will fail since the command property defaults to a platform named default. Instead of specifying it, you can register this Cloud Foundry Platform account in the manifest with the name default instead of cf-dev.

You can monitor the process using the status command.

skipper:>status --release-name helloworldpcf
╔═══════════════╤════════════════════════════════════════════════╗
║Last Deployed  │Tue Oct 24 22:54:30 EDT 2017                    ║
║Status         │DEPLOYED                                        ║
║Platform Status│The applications are being deployed.            ║
║               │[helloworldpcf-helloworld-v1], State = [partial]║
╚═══════════════╧════════════════════════════════════════════════╝

Eventually the Platform Status will say All applications have been successfully deployed.

Note that the status DEPLOYED above indicates that Skipper has told the platform to deploy. Skipper does not keep track of the intermediate states 'deploying' or 'deleting'.

A cf apps command will now have a new listing for this deployed application.

$ cf apps
Getting apps in org scdf-ci / space space-mark as [email protected]
OK

name                          requested state   instances   memory   disk   urls
helloworldpcf-helloworld-v1   started           1/1         1G       1G     helloworldpcf.cfapps.io

You can now curl the greeting endpoint and the about endpoint.

$ curl http://helloworldpcf.cfapps.io/greeting
Hello World!
$ curl http://helloworldpcf.cfapps.io/about
Hello World v1.0.0.RELEASE

The name of the application is based on the convention <release-name>-<package-name>-v<incrementing-counter>.

Also note that we specified a route for this application that is different than the application’s name. The deployment property spring.cloud.deployer.cloudfoundry.route is set to something that will not change across the deployment of different versions of this application, in this case helloworldpcf.cfapps.io.

The package provides a means to template the application version, application properties and deployment properties that are used to deploy the application to Cloud Foundry. The manifest get command shows the final YAML file which is passed off to the Spring Cloud Deployer Library.

skipper:>manifest get --release-name helloworldpcf

---
# Source: helloworld.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: helloworld
  type: demo
spec:
  resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld:1.0.0.RELEASE
  applicationProperties:
  deploymentProperties:
    spring.cloud.deployer.cloudfoundry.route: helloworldpcf.cfapps.io

The manifest is in a Kubernetes Resource file inspired format. By looking at the manifest you can see which maven artifact was used and which properties were set before the final push to Cloud Foundry. The metadata values that are present will be used in the next release to support searching for releases based on those values.

Since it is somewhat awkward to specify multiple flattened out YAML values for the --properties argument in the shell, you can also specify the location of a YAML file when installing or upgrading. We will use a YAML file to update the release. This application contains a Spring Boot @ConfigurationProperty named helloworld.greeting, so we will set that along with a standard Spring Boot property endpoints.sensitive=false. We will also bump the memory up to 2G.

spec:
  applicationProperties:
    endpoints.sensitive: false
    helloworld.greeting: yo
  deploymentProperties:
    spring.cloud.deployer.cloudfoundry.route: helloworldpcf.cfapps.io
    spring.cloud.deployer.memory: 2048m

The upgrade command

skipper:>upgrade --release-name helloworldpcf --package-name helloworld --package-version 1.0.0 --file /home/mpollack/helloworld-upgrade.yml
helloworldpcf has been upgraded.  Now at version v2.

Will start another instance of the hello world application. If you do not specify --package-version it will pick the latest version of the helloworld package. You do not need to specify the --platform-name as it will always be where the current application was deployed.

The cf apps and cf routes command shows

$ cf apps
Getting apps in org scdf-ci / space space-mark as [email protected]
OK

name                          requested state   instances   memory   disk   urls
helloworldpcf-helloworld-v1   started           1/1         1G       1G     helloworldpcf.cfapps.io
helloworldpcf-helloworld-v2   stopped           0/1         2G       1G     helloworldpcf.cfapps.io

and

$ cf routes
Getting routes for org scdf-ci / space space-mark as [email protected] ...

space        host                          domain      port   path   type   apps                                                      service
space-mark   helloworldpcf                 cfapps.io                        helloworldpcf-helloworld-v1,helloworldpcf-helloworld-v2

At this point Skipper is looking to see if the health endpoint of the Boot application is ok. The property spring.cloud.skipper.server.strategies.healthcheck.timeoutInMillis is the maximum time the upgrade process will wait for a healthy app. The default value is 5 minutes. Skipper will fail the deployment if it is not healthy within that time. The property spring.cloud.skipper.server.strategies.healthcheck.sleepInMillis is how long to sleep between health checks.

The current upgrade strategy is very simple, if the new app is healthy, the old app is removed. There is not a rolling upgrade option, all new apps are deployed, checked for health, and then previous versions removed. More flexible upgrade strategies are planned along with the introduction of the Spring Cloud State Machine project to orchestrate the update process.

You can now curl the greeting endpoint and the about endpoint.

$ curl http://helloworldpcf.cfapps.io/greeting
yo
$ curl http://helloworldpcf.cfapps.io/about
Hello World v1.0.0.RELEASE

The list command shows you the current DEPLOYED and DELETED releases for every release name. In this case there is just one entry

╔══════════════╤═══════╤══════════════════════════╤════════╤═══════════╤══════════════╤════════════╤══════════════════════════════════════════════════════════════════════════════╗
║     Name     │Version│       Last updated       │ Status │  Package  │   Package    │  Platform  │                               Platform Status                                ║
║              │       │                          │        │   Name    │   Version    │    Name    │                                                                              ║
╠══════════════╪═══════╪══════════════════════════╪════════╪═══════════╪══════════════╪════════════╪══════════════════════════════════════════════════════════════════════════════╣
║helloworldpcf │2      │Tue Oct 24 22:57:02 EDT   │DEPLOYED│helloworld │1.0.0         │cf-dev      │ [helloworldpcf-helloworld-v2], State =                                       ║
║              │       │2017                      │        │           │              │            │ [helloworldpcf-helloworld-v2-0=deployed]                                     ║
╚══════════════╧═══════╧══════════════════════════╧════════╧═══════════╧══════════════╧════════════╧══════════════════════════════════════════════════════════════════════════════╝

You can get the full history of the release using the history command

skipper:>history --release-name helloworldpcf
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║2      │Tue Oct 24 22:57:02 EDT 2017│DEPLOYED│helloworld  │1.0.0          │Upgrade complete║
║1      │Tue Oct 24 22:54:30 EDT 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

A more typical upgrade process is not to change application properties, but to change the version of the application because the code has change. We will now upgrade the release to use a new maven artifact, version 1.0.1, which also corresponds to version 1.0.1 of the helloworld skipper package. In this case, we will not add any additional properties other than the route.

skipper:>upgrade --release-name helloworldpcf --package-name helloworld --package-version 1.0.1 --properties spec.deploymentProperties.spring.cloud.deployer.cloudfoundry.route=helloworldpcf.cfapps.io
helloworldpcf has been upgraded.  Now at version v3.

Note that the current release’s property values such as using 2G, or the greeting being yo are not carried over. In a future release we will introduce a --reuse-properties command that will carry the current release properties over to the next release to be made. You can monitor the status of the upgrade using the status command

skipper:>status --release-name helloworldpcf
╔═══════════════╤═════════════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Tue Oct 24 23:09:39 EDT 2017                                                     ║
║Status         │DEPLOYED                                                                         ║
║Platform Status│All applications have been successfully deployed.                                ║
║               │[helloworldpcf-helloworld-v3], State = [helloworldpcf-helloworld-v3-0=deployed]  ║
╚═══════════════╧═════════════════════════════════════════════════════════════════════════════════╝

And a curl command shows

curl http://helloworldpcf.cfapps.io/greeting
Olá Mundo!
$ curl http://helloworldpcf.cfapps.io/about
Hello World v1.0.1.RELEASE

Our history now looks like

skipper:>history --release-name helloworldpcf
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║3      │Tue Oct 24 23:09:39 EDT 2017│DEPLOYED│helloworld  │1.0.1          │Upgrade complete║
║2      │Tue Oct 24 22:57:02 EDT 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
║1      │Tue Oct 24 22:54:30 EDT 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

Next we will use the rollback command to deploy an older version of the application. Since we have the manifest for that version, we have all we need to redeploy an earlier release.

skipper:>rollback --release-name helloworldpcf --release-version 2
helloworldpcf has been rolled back.  Now at version v4.

The history now shows a new v4 version, even though it is identical in terms of app behavior to the v2 version.

skipper:>history --release-name helloworldpcf
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║4      │Tue Oct 24 23:15:01 EDT 2017│DEPLOYED│helloworld  │1.0.0          │Upgrade complete║
║3      │Tue Oct 24 23:09:39 EDT 2017│DELETED │helloworld  │1.0.1          │Delete complete ║
║2      │Tue Oct 24 22:57:02 EDT 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
║1      │Tue Oct 24 22:54:30 EDT 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

The curl commands show

$ curl http://helloworldpcf.cfapps.io/greeting
yo
$ curl http://helloworldpcf.cfapps.io/about
Hello World v1.0.0.RELEASE

10. Kuberenetes

In this example we will be running the Skipper server on the local machine and deploying to minikube also running on the local machine.

The upgrade approach in 1.0 M2 does not handle correctly the routing of http traffic between versions, so take what is below with a grain of salt. The Spring Cloud Deployer for Kubernetes creates a service, replication controller, and pod for the app (or optionally a Deployment) This is not an issue for apps that communicate via Messaging middleware. Treat the current M2 release as a WIP.

Start the Skipper server with the option --spring.config.location=skipper.yml where the YAML is shown below.

spring:
  cloud:
    skipper:
      server:
        enableLocalPlatform: false
        platform:
          kubernetes:
            accounts:
              minikube:
                namespace: default

The repo list command shows the experimental and local repositories, since they are configured by default.

skipper:>repo list
╔════════════╤═══════════════════════════════════════════════════════════╤═════╤═════╗
║    Name    │                            URL                            │Local│Order║
╠════════════╪═══════════════════════════════════════════════════════════╪═════╪═════╣
║experimental│http://skipper-repository.cfapps.io/repository/experimental│false│0    ║
║local       │http://d4d6d1b6-c7e5-4226-69ec-01d4:7577                   │true │1    ║
╚════════════╧═══════════════════════════════════════════════════════════╧═════╧═════╝

and the search command shows

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

The command platform list shows which platforms the server has been configured with, in this case just one Kubernetes namespace. Disabling the local platform with the property enableLocalPlatform = false is why the default local platform does not appear.

skipper:>platform list
╔════════╤══════════╤══════════════════════════════════════════════════════════════════════════════════════╗
║  Name  │   Type   │                                     Description                                      ║
╠════════╪══════════╪══════════════════════════════════════════════════════════════════════════════════════╣
║minikube│kubernetes│master url = [https://192.168.99.100:8443/], namespace = [default], api version = [v1]║
╚════════╧══════════╧══════════════════════════════════════════════════════════════════════════════════════╝

Let’s install the Hello World app, specifically, the Docker based artifact.

skipper:>install --release-name helloworldk8s --package-name helloworld-docker --package-version 1.0.0 --platform-name minikube --properties spec.deploymentProperties.spring.cloud.deployer.kubernetes.createNodePort=32123
Released helloworldk8s. Now at version v1.

If you do not specify --platform-name minikube the command will fail since the command property defaults to a platform named default. Instead of specifying it, you can register this Kubernetes Platform account in the manifest with the name default instead of minikube.

You can monitor the process using the status command.

skipper:>status --release-name helloworldk8s
╔═══════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Wed Oct 25 17:34:24 EDT 2017                                                                      ║
║Status         │DEPLOYED                                                                                          ║
║Platform Status│The applications are being deployed.                                                              ║
║               │[helloworldk8s-helloworld-docker-v1], State = [helloworldk8s-helloworld-docker-v1-cch68=deploying]║
╚═══════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════╝

Eventually the Platform Status will say All applications have been successfully deployed.

Note that the status DEPLOYED above indicates that Skipper has told the platform to deploy. Skipper does not keep track of the intermediate states 'deploying' or 'deleting'.

A kubectl pods command will now have a new listing for this deployed application

$ kubectl get pods
NAME                                       READY     STATUS    RESTARTS   AGE
helloworldk8s-helloworld-docker-v1-g8j39   0/1       Running   0          37s

$ kubectl get service
NAME                                 CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
helloworldk8s-helloworld-docker-v1   10.0.0.202   <nodes>       8080:32123/TCP   41s
kubernetes                           10.0.0.1     <none>        443/TCP          57m

To get the URL of this app on minikube

$ minikube service --url helloworldk8s-helloworld-docker-v1
http://192.168.99.100:32123

You can now curl the greeting endpoint and the about endpoint.

$ curl http://192.168.99.100:32123/greeting
Hello World!
$ curl http://192.168.99.100:32123/about
Hello World v1.0.0.RELEASE

The name of the application is based on the convention <release-name>-<package-name>-v<incrementing-counter>. This will need to change in future releases in order to handle routing correctly.

The package provides a means to template the application version, application properties and deployment properties that are used to deploy the application to Kubernetes. The manifest get command shows the final YAML file which is passed off to the Spring Cloud Deployer Library.

skipper:>manifest get --release-name helloworldk8s

---
# Source: template.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: helloworld-docker
spec:
  resource: docker:springcloud/spring-cloud-skipper-samples-helloworld:1.0.0.RELEASE
  applicationProperties:
  deploymentProperties:
    spring.cloud.deployer.kubernetes.createNodePort: 32123

The manifest is in a Kubernetes Resource file inspired format. By looking at the manifest you can see which Docker images was used and which properties were set before the final push to Kubernetes. The metadata values that are present will be used in the next release to support searching for releases based on those values.

Since it is somewhat awkward to specify multiple flattened out YAML values for the --properties argument in the shell, you can also specify the location of a YAML file when installing or upgrading. We will use a YAML file when we will update the release. This application contains a Spring Boot @ConfigurationProperty named helloworld.greeting, so we will set that along with a standard Spring Boot property endpoints.sensitive=false. We will also bump the memory up to 2G.

spec:
  applicationProperties:
    endpoints.sensitive: false
    helloworld.greeting: yo
  deploymentProperties:
    spring.cloud.deployer.kubernetes.createNodePort: 32124
    spring.cloud.deployer.memory: 2048m

The upgrade command

skipper:>upgrade --release-name helloworldk8s --package-name helloworld-docker --package-version 1.0.0 --file /home/mpollack/helloworld-upgrade-k8s.yml
helloworldk8s has been upgraded.  Now at version v2.

This will start another instance of the hello world application. If you do not specify --package-version it will pick the latest version of the helloworld-docker package. You do not need to specify the --platform-name as it will always be where the current application was deployed.

the kubectl get all command shows

$ kubectl get all
NAME                                          READY     STATUS    RESTARTS   AGE
po/helloworldk8s-helloworld-docker-v1-g8j39   1/1       Running   0          2m
po/helloworldk8s-helloworld-docker-v2-jz85l   0/1       Running   0          50s

NAME                                    DESIRED   CURRENT   READY     AGE
rc/helloworldk8s-helloworld-docker-v1   1         1         1         2m
rc/helloworldk8s-helloworld-docker-v2   1         1         0         50s

NAME                                     CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
svc/helloworldk8s-helloworld-docker-v1   10.0.0.202   <nodes>       8080:32123/TCP   2m
svc/helloworldk8s-helloworld-docker-v2   10.0.0.154   <nodes>       8080:32124/TCP   51s
svc/kubernetes                           10.0.0.1     <none>        443/TCP          59m

At this point Skipper is looking to see if the health endpoint of the Boot application is ok. The property spring.cloud.skipper.server.strategies.healthcheck.timeoutInMillis is the maximum time the upgrade process will wait for a healthy app. The default value is 5 minutes. Skipper will fail the deployment if it is not healthy within that time. The property spring.cloud.skipper.server.strategies.healthcheck.sleepInMillis is how long to sleep between health checks.

The current upgrade strategy is very simple, if the new app is healthy, the old app is removed. There is not a rolling upgrade option, all new apps are deployed, checked for health, and then previous versions removed. More flexible upgrade strategies are planned along with the introduction of the Spring Cloud State Machine project to orchestrate the update process.

You can now curl the greeting endpoint and the about endpoint.

$ curl http://192.168.99.100:32124/greeting
yo
$ curl http://192.168.99.100:32124/about
Hello World v1.0.0.RELEASE

The list command shows you the current DEPLOYED and DELETED release for every release name. In this case there is just one entry

skipper:>list
╔═════════════╤═══════╤════════════════════════════╤════════╤═════════════════╤═══════════════╤═════════════╤═══════════════╗
║    Name     │Version│        Last updated        │ Status │  Package Name   │Package Version│Platform Name│Platform Status║
╠═════════════╪═══════╪════════════════════════════╪════════╪═════════════════╪═══════════════╪═════════════╪═══════════════╣
║helloworldk8s│2      │Wed Oct 25 17:36:16 EDT 2017│DEPLOYED│helloworld-docker│1.0.0          │minikube     │               ║
╚═════════════╧═══════╧════════════════════════════╧════════╧═════════════════╧═══════════════╧═════════════╧═══════════════╝

You can get the full history of the release using the history command.

skipper:>history --release-name helloworldk8s
╔═══════╤════════════════════════════╤════════╤═════════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │  Package Name   │Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪═════════════════╪═══════════════╪════════════════╣
║2      │Wed Oct 25 17:36:16 EDT 2017│DEPLOYED│helloworld-docker│1.0.0          │Upgrade complete║
║1      │Wed Oct 25 17:34:24 EDT 2017│DELETED │helloworld-docker│1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧═════════════════╧═══════════════╧════════════════╝

A more typical upgrade process is not to change application properties, but to change the version of the application because the code has change. We will now upgrade the release to use a new Docker artifact, version 1.0.1, which also corresponds to version 1.0.1 of the helloworld Skipper package. In this case we will not add any additional properties other than the NodePort.

skipper:>upgrade --release-name helloworldk8s --package-name helloworld-docker --package-version 1.0.1 --properties spec.deploymentProperties.spring.cloud.deployer.kubernetes.createNodePort=32125
Released helloworldk8s. Now at version v3.

Note that the the current release’s property values such as using 2G, or the greeting being yo are not carried over. In a future release we will introduce a --reuse-properties command that will carry the current release properties over to the next release to be made. You can monitor the status of the upgrade using the status command

skipper:>status --release-name helloworldk8s
╔═══════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Wed Oct 25 17:41:33 EDT 2017                                                                      ║
║Status         │DEPLOYED                                                                                          ║
║Platform Status│All applications have been successfully deployed.                                                 ║
║               │[helloworldk8s-helloworld-docker-v3], State = [helloworldk8s-helloworld-docker-v3-sb59j=deployed] ║
╚═══════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════╝

And a curl command shows

$ curl http://192.168.99.100:32125/greeting
Olá Mundo!

$ curl http://192.168.99.100:32125/about
Hello World v1.0.1.RELEASE

Our history now looks like

skipper:>history --release-name helloworldk8s
╔═══════╤════════════════════════════╤════════╤═════════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │  Package Name   │Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪═════════════════╪═══════════════╪════════════════╣
║3      │Wed Oct 25 17:41:33 EDT 2017│DEPLOYED│helloworld-docker│1.0.1          │Upgrade complete║
║2      │Wed Oct 25 17:36:16 EDT 2017│DELETED │helloworld-docker│1.0.0          │Delete complete ║
║1      │Wed Oct 25 17:34:24 EDT 2017│DELETED │helloworld-docker│1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧═════════════════╧═══════════════╧════════════════╝

Next we will use the rollback command to deploy an older version of the application. Since we have the manifest for that version, we have all we need to redeploy an earlier release.

skipper:>rollback --release-name helloworldk8s --release-version 2
helloworldk8s has been rolled back.  Now at version v4.

The history now shows a new v4 version, even though it is identical to the v2 version.

skipper:>history --release-name helloworldk8s
╔═══════╤════════════════════════════╤════════╤═════════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │  Package Name   │Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪═════════════════╪═══════════════╪════════════════╣
║4      │Wed Oct 25 17:44:25 EDT 2017│DEPLOYED│helloworld-docker│1.0.0          │Upgrade complete║
║3      │Wed Oct 25 17:41:33 EDT 2017│DELETED │helloworld-docker│1.0.1          │Delete complete ║
║2      │Wed Oct 25 17:36:16 EDT 2017│DELETED │helloworld-docker│1.0.0          │Delete complete ║
║1      │Wed Oct 25 17:34:24 EDT 2017│DELETED │helloworld-docker│1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧═════════════════╧═══════════════╧════════════════╝

The curl commands show

$ curl http://192.168.99.100:32124/greeting
yo
$ curl http://192.168.99.100:32124/about
Hello World v1.0.0.RELEASE

Using Skipper

This section is the 'three hour tour' of Skipper. It describes how to configure and use the main feature set of Skipper in detail. We will cover, platforms, packages, repositories, releases and update strategies.

Feel free to reach out on Gitter for help and ask questions on Stack Overflow. Issues can be filed on Github issues.

11. Platforms

Skipper supports deploying to multiple platforms. The platforms included are Local, Cloud Foundry and Kubernetes. For each platform, you can configure multiple accounts. Each account name must be globally unique across all platforms.

Usually different accounts will correspond to a different orgs/spaces for Cloud Foundry and different namespaces for a single Kubernetes cluster.

Platforms are defined using Spring Boot’s Externalized Configuration feature. To simplify setup in 1.0 M2, if a local platform account is not defined in your configuration, Skipper will create a local deployer implementation named default.

You can make use of the Encryption and Decryption features of Spring Cloud Config as one way to secure credentials.

Distinct from where Skipper will deploy application, you can also run the Skipper server itself on a platform. Installation on other platforms is covered in the [skipper-installation] section.

Here is example YAML file showing configuration of all three platforms

spring:
  cloud:
    skipper:
      server:
        platform:
          local:
            accounts:
              localDevDebug:
                javaOpts: "-Xdebug"
          cloudfoundry:
            accounts:
              cf-dev:
                connection:
                  url: https://api.run.pivotal.io
                  org: scdf-ci
                  space: space-mark
                  domain: cfapps.io
                  username: <your-username>
                  password: <your-password>
                  skipSslValidation: false
                deployment:
                  deleteRoutes: false
          kubernetes:
            accounts:
              minikube:
                namespace: default

The properties available for each platform can be found in these classes

12. Packages

Packages contain all the necessary information to install your application or group of applications. The approach to decribing the applications is to use a YAML file that provides all the necessary information to help facilitate searching for your application hosted in a Package Registry and to install your application to a platform.

To make it easy to customize a package, the YAML files are templated. The final version of the YAML file, with all values substituted is known as the release manifest. Skipper currently understands how to deploy applications based off a YAML file that contains the information needed for a Spring Cloud Deployer implementation to deploy an application. It describes, where to find the application (either a http, maven or docker location) , application properties (think Spring Boot @ConfigurationProperties), an deployment properites (e.g. how much memory to use).

12.1. Package Format

A package is a collection of YAML files that are zipped up into a file with the 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 JMustache. The YAML files can have either .yml or .yaml extensions.

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

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

12.2. Package with multiple applications

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

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 above, the mypackagegroup would still have its own package.yml, values.yml to specify the package metadata and the values to override. All the applications inside the mypackagegroup are considered sub-packages and would follow the similar package structure as the individual packages. These sub packages need to be specified inside the packages directory of the root package mypackagegroup.

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

12.3. Package Metadata (package.yml)

The package.yml file specifies the package metadata. A sample package metadata would look like this:

# 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:

  • apiVersion - The Package Index spec version this file is based on

  • kinds - What type of package system is being used

  • name - name of the package

  • version - version of the package

Optional Fields:

  • packageSourceUrl - Location to source code for this package.

  • packageHomeUrl - The home page of the package

  • tags - A comma separated list of tags to be used for searching

  • maintainer - Who is maintaining this package

  • description Free form text describing the functionality of the package. Will generally be shown in search results.

  • sha256 - Hash of package binary (not yet enforced)

  • iconUrl - URL for an icon to show for this package.

  • origin - Free form text describing the origin of this package, for example your company name.

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, separated by the standard three dash notation --- to separate the documents. For example index.yml.

12.4. Package Templates (template.yml)

The template.yml file in a package structure such as

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

will commonly have the following content:

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

The apiVersion, kind and spec.resource are required.

The spec.resource and spec.version defines where the application executable is located. This is either a Spring Boot uberjar hosted under a http endpoint or a maven or docker repository. The template placeholder {{version}} so that the version of a specific application can be easily upgraded without having to create a new package .zip file.

The resource is http:// or a maven:// or docker: based. The format for specifying a resource is shown below.

12.4.1. HTTP Resources

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

There is a naming convention that must be followed for HTTP based resource so that Skipper can assemble a full URL from the resource and version field and also parse the version number given the URL. The above spec will reference a URL at example.com/app/hello-world-1.0.0.RELEASE.jar. The resource and version fields should not have any numbers after the - character.

12.4.2. Docker Resources

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

The mapping to docker registry names is

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

12.4.3. Maven Resources

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 is

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 applies across all platform accounts. By default the configuration:

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

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

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

The metadata is used to help search for applications after they have been installed and is not available in Skipper 1.0 M2.

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

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.

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

12.5. Package Values (values.yml)

The values YAML 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

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. That is, given a multiple application package with the layout

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

A top level values.yml file

#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

Would set 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.

12.6. Package Upload

After creating the package in the above structure, we can compress it in a zip file with the name [PackageName]-[PackageVersion].zip e.g. mypackage-1.0.0.zip

For instance, the package directory would look like this before compression:

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

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

Using the Skipper Shell, we can upload the package zip into Skipper server’s one of the local repositories.

skipper:>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 will use local as the repository to upload.

skipper:>search
╔═════════════════╤═══════╤════════════════════════════════════════════════════════════════════════════════╗
║      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                                                      ║
╚═════════════════╧═══════╧════════════════════════════════════════════════════════════════════════════════╝

12.7. Creating Your Own Package

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

For this package, we are going to be creating a super simple package and uploading it to our local machine.

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

Go into the package.yml where we are going to specify the package metadata, for this app we are only going to be filling the minimum values possible:

# package.yml

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

Importantly here, ensure that your name and version matches the name and version in your folder name or you will get an error.

Next, open up your templates/template.yml. Here we are going to be specifying the actual information about your package and most importantly setting default values. In the template.yml, copy the template for the kind SpringCloudDeployerApplication from the above sample.

# 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}}

Simply, this specifies our application name is demo, and finds our package in maven and we can specify a version, applicationProperties and deploymentProperties in our values.yml. So lets do that.

# 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

This will set out version to 1.0.0.RELEASE and also set 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 would look like this:

# 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 allows you to overwrite the values at run time using the --file or --properties flags.

We have now finished making our file, we now have to zip it up. The easiest way to do is the zip -r command line command. You should see something like:

$ 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:

skipper:> 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 above, then install it!

skipper:>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!

13. Repositories

Repositories are where package metadata and package .zip files are hosted. Repositores can be local or remote, were local means backed by Skipper’s relational database and remote means a filesystem exposed over http.

When registering a remote registry, for example, the experimental one that is currently defined by default in addition to one named local` use the following format:

spring
  cloud:
    skipper:
      server:
        packageRepositories:
          -
            name: experimental
            url: http://skipper-repository.cfapps.io/repository/experimental
            description: Experimental Skipper Repository
            repoOrder: 0
          -
            name: local
            url: http://${spring.cloud.client.hostname}:7577
            local: true
            description: Default local database backed repository
            repoOrder: 1

The repoOrder determines which repository will serve up a package if one with the same name is registered in two or more repositories.

The directory structure assumed for a remote repository is the registered url value followed by the package name and then the zip file name., e.g. skipper-repository.cfapps.io/repository/experimental/helloworld/helloworld-1.0.0.zip for the package helloworld with the version 1.0.0. Directly under the registered url is expected to be a file named index.yml, e.g. skipper-repository.cfapps.io/repository/experimental/index.yml. This contains the package metadata for all the packages hosted by the repository.

It is up to you to update the index.yml file 'by-hand' for remote repositories.

'Local' repositories are backed by Skipper’s database. In the 1.0 M2 release they does not expose the index.yml or the .zip files under a filesystem like URL structure as with remote repositories. This will be provided in the next version. However, on the positive side, you can upload packages to a local repository and don’t need to maintain an index file. See the skipper command section for information on creating local repositories.

A good example that shows using a Spring Boot web application with static resources to host a Repository can be found here. This application is currently running under skipper-repository.cfapps.io/repository/experimental.

Skipper Commands

14. Release and Package commands

14.1. Search command

The command search shows all the packages available to be installed by the Skipper server.

skipper:>search
╔═════════════════╤═══════╤════════════════════════════════════════════════════════════════════════════════╗
║      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.1  │The app has two endpoints, /about and /greeting in Portuguese.  Docker resource.║
║helloworld-docker│1.0.0  │The app has two endpoints, /about and /greeting in English.  Docker resource.   ║
╚═════════════════╧═══════╧════════════════════════════════════════════════════════════════════════════════╝

The search command can use --name option to search for the package name containing the given option value.

skipper:>search --name helloworld-
╔═════════════════╤═══════╤════════════════════════════════════════════════════════════════════════════════╗
║      Name       │Version│                                  Description                                   ║
╠═════════════════╪═══════╪════════════════════════════════════════════════════════════════════════════════╣
║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.║
╚═════════════════╧═══════╧════════════════════════════════════════════════════════════════════════════════╝

To search for more details of the packages, the option --details can be used.

skipper:>search --name helloworld- --details
╔════════════════╤═════════════════════════════════════════════════════════════════════════════╗
║      Name      │                                    Value                                    ║
╠════════════════╪═════════════════════════════════════════════════════════════════════════════╣
║apiVersion      │v1                                                                           ║
║origin          │A sample repository for using Skipper                                        ║
║repositoryId    │1                                                                            ║
║kind            │skipper                                                                      ║
║name            │helloworld-docker                                                            ║
║version         │1.0.0                                                                        ║
║packageSourceUrl│https://github.com/markpollack/skipper-sample-repository                     ║
║packageHomeUrl  │https://github.com/markpollack/skipper-sample-repository                     ║
║tags            │web, demo, docker, helloworld                                                ║
║maintainer      │https://github.com/markpollack                                               ║
║description     │The app has two endpoints, /about and /greeting in English.  Docker resource.║
║sha256          │                                                                             ║
║iconUrl         │                                                                             ║
╚════════════════╧═════════════════════════════════════════════════════════════════════════════╝

╔════════════════╤════════════════════════════════════════════════════════════════════════════════╗
║      Name      │                                     Value                                      ║
╠════════════════╪════════════════════════════════════════════════════════════════════════════════╣
║apiVersion      │v1                                                                              ║
║origin          │A sample repository for using Skipper                                           ║
║repositoryId    │1                                                                               ║
║kind            │skipper                                                                         ║
║name            │helloworld-docker                                                               ║
║version         │1.0.1                                                                           ║
║packageSourceUrl│https://github.com/markpollack/skipper-sample-repository                        ║
║packageHomeUrl  │https://github.com/markpollack/skipper-sample-repository                        ║
║tags            │web, demo, docker, helloworld                                                   ║
║maintainer      │https://github.com/markpollack                                                  ║
║description     │The app has two endpoints, /about and /greeting in Portuguese.  Docker resource.║
║sha256          │                                                                                ║
║iconUrl         │                                                                                ║
╚════════════════╧════════════════════════════════════════════════════════════════════════════════╝

14.2. Install command

This command installs a package.

skipper:>install --release-name helloworldlocal --package-name helloworld --package-version 1.0.0 --properties spec.applicationProperties.server.port=8099
Released helloworldlocal. Now at version v1.

If no package-version is specified, then the latest package version by the given package-name will be considered.

If no platform-name is specified, the platform name default will be used.

The properties can either be provided via comma separated YAML String using the --properties option or, via a YAML file using the --file option.

14.3. Upgrade command

This command upgrades a package.

skipper:>upgrade --release-name helloworldlocal --package-name helloworld --package-version 1.0.0 --properties spec.applicationProperties.server.port=9090
helloworldpcf has been upgraded.  Now at version v2.

If no package-version is specified, then the latest package version by the given package-name will be considered. The properties can either be provided via comma separated YAML String using the --properties option or, via a YAML file using the --file option.

An upgrade can be done by overriding the package version or by keeping the existing package version but by overriding the properties. When overriding the package version, it needs to accompany with the corresponding properties as the existing properties won’t be carried over. In a future release we will introduce a --reuse-properties command that will carry the current release properties over to the next release to be made.

When performing an update on a package that contains nested packages, use the name of the package as a prefix in the property string or as the first level in the YAML document. For example, the ticktock package that contains a time and a log application, a command to upgrade the log application would be

skipper:>upgrade --release-name ticktockskipper --package-name ticktock --file /home/mpollack/log-level-change.yml

where log-level-change.yml is

log:
  version: 1.1.1.RELEASE
  spec:
    applicationProperties:
      server.port: 9999
      endpoints.sensitive: false
      log.level: ERROR

Since it is quite a common use-case to change only the version of the application, the packages can list the version as a top level property in the values.yml file. For example, in the test package ticktock (located here), values.yml is

version: 1.1.0.RELEASE
spec:
  applicationProperties:
    log.level: DEBUG
  deploymentProperties:
    memory: 1024m

You can then use the --properties option in the upgrade command as shown below

skipper:>upgrade --release-name ticktockskipper --package-name ticktock --properties log.version=1.1.1.RELEASE

14.4. Status command

This command shows the status of a specific release and version.

skipper:>status --release-name helloworldlocal
╔═══════════════╤═══════════════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Mon Oct 30 17:53:50 IST 2017                                                       ║
║Status         │DEPLOYED                                                                           ║
║Platform Status│All applications have been successfully deployed.                                  ║
║               │[helloworldlocal.helloworld-v2], State = [helloworldlocal.helloworld-v2-0=deployed]║
╚═══════════════╧═══════════════════════════════════════════════════════════════════════════════════╝

If no --release-version specifed, then the latest release version will be used.

skipper:>status --release-name helloworldlocal --release-version 1
╔═══════════════╤════════════════════════════════════════════════════════════════════════╗
║Last Deployed  │Mon Oct 30 17:52:57 IST 2017                                            ║
║Status         │DELETED                                                                 ║
║Platform Status│The applications are known to the system, but is not currently deployed.║
║               │[helloworldlocal.helloworld-v1], State = [unknown]                      ║
╚═══════════════╧════════════════════════════════════════════════════════════════════════╝

14.5. Rollback command

This command rollsback the release to a specific version.

skipper:>rollback --release-name helloworldlocal --release-version 1
helloworldlocal has been rolled back.  Now at version v3.

If no --release-version specified, then the rollback version is the previous stable release (either in DELETED or DEPLOYED status).

14.6. List command

This command lists the latest deployed or failed release.

skipper:>list
╔═══════════════╤═══════╤═════════════════════════╤════════╤═══════════╤══════════════╤════════════╤══════════════════════════════════════════════════════════════════════════════╗
║     Name      │Version│      Last updated       │ Status │  Package  │   Package    │  Platform  │                               Platform Status                                ║
║               │       │                         │        │   Name    │   Version    │    Name    │                                                                              ║
╠═══════════════╪═══════╪═════════════════════════╪════════╪═══════════╪══════════════╪════════════╪══════════════════════════════════════════════════════════════════════════════╣
║helloworldlocal│3      │Mon Oct 30 17:57:41 IST  │DEPLOYED│helloworld │1.0.0         │default     │[helloworldlocal.helloworld-v3], State =                                      ║
║               │       │2017                     │        │           │              │            │[helloworldlocal.helloworld-v3-0=deployed]                                    ║
╚═══════════════╧═══════╧═════════════════════════╧════════╧═══════════╧══════════════╧════════════╧══════════════════════════════════════════════════════════════════════════════╝

14.7. History command

This command shows the history of a specific release.

skipper:>history --release-name helloworldlocal
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║3      │Mon Oct 30 17:57:41 IST 2017│DEPLOYED│helloworld  │1.0.0          │Upgrade complete║
║2      │Mon Oct 30 17:53:50 IST 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
║1      │Mon Oct 30 17:52:57 IST 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

The number of revisions in the history result can be limited using --max option. For instance,

skipper:>history --release-name helloworldlocal --max 2
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║3      │Mon Oct 30 17:57:41 IST 2017│DEPLOYED│helloworld  │1.0.0          │Upgrade complete║
║2      │Mon Oct 30 17:53:50 IST 2017│DELETED │helloworld  │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

14.8. Delete command

This command deletes a specific release’s latest deployed revision.

skipper:>delete --release-name helloworldlocal
helloworldlocal has been deleted.

15. Manifest commands

The manifest get command shows the manifest used for a specific release.

skipper:>manifest get --release-name helloworldk8s

---
# Source: template.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: helloworld-docker
spec:
  resource: docker:springcloud/spring-cloud-skipper-samples-helloworld:1.0.0.RELEASE
  applicationProperties:
  deploymentProperties:
    spring.cloud.deployer.kubernetes.createNodePort: 32123

16. Platform commands

The platform list command shows the list all the available deployment platform accounts.

An example output of platform list can be

skipper:>platform list
╔════════╤════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  Name  │    Type    │                                                                         Description                                                                          ║
╠════════╪════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║default │local       │ShutdownTimeout = [30], EnvVarsToInherit = [TMP,LANG,LANGUAGE,LC_.*,PATH], JavaCmd =                                                                          ║
║        │            │[/Library/Java/JavaVirtualMachines/jdk1.8.0_131.jdk/Contents/Home/jre/bin/java], WorkingDirectoriesRoot = [/var/folders/t3/qf1wkpwj4lgd9gjccwk0wr7h0000gp/T], ║
║        │            │DeleteFilesOnExit = [true]                                                                                                                                    ║
║cf-dev  │cloudfoundry│org = [scdf-ci], space = [ilaya-space], url = [https://api.run.pivotal.io]                                                                                    ║
║minikube│kubernetes  │master url = [https://192.168.99.101:8443/], namespace = [default], api version = [v1]                                                                        ║
╚════════╧════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

17. Repository commands

You can list add or delete a repository using the commands repo add, repo delete and repo list

An example output of repo list is shown below

skipper:>repo list
╔════════════╤═══════════════════════════════════════════════════════════╤═════╤═════╗
║    Name    │                            URL                            │Local│Order║
╠════════════╪═══════════════════════════════════════════════════════════╪═════╪═════╣
║experimental│http://skipper-repository.cfapps.io/repository/experimental│false│0    ║
║local       │http://10.55.13.45:7577                                    │true │1    ║
╚════════════╧═══════════════════════════════════════════════════════════╧═════╧═════╝

If a repository is local, it is backed by Skipper’s database and you will be able to upload packages to the repository. If it is not local, it is a remote repository and you are only able to read packages. The packages in a remote repository are updated outside of Skipper’s control. The 1.0 M2 release only polls the remote repository for contents upon server startup. Follow issue GH-262 for more on adding support for dynamic updating of remote repository metadata.

Architecture

Skipper uses a basic client server architecture. The server exposes a HTTP API that is used by the interactive shell. The server persists Package Metadata and Release state in a relational database.

Platforms are defined using Spring Boot’s docs.spring .io/spring-boot/docs/current/reference/html/boot-features-external-config.html[Externalized Configuration] feature. See the Platforms section for more information on configuring the platforms. The platforms map onto an instance of a Spring Cloud Deployer implementation which is responsible for deploying the applications.

The release workflow is currently a hard-coded blue/green workflow. The plan is to use the Spring Cloud State Machine project to orchestrate the release workflow.

REST API Guide

In this section you will learn all about the Spring Cloud Skipper REST API.

18. Overview

Spring Cloud Skipper provides a REST API allowing you to access all aspects of the server. In fact the Spring Cloud Skipper Shell is a first-class consumer of that API.

18.1. HTTP verbs

Spring Cloud Skipper tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates. Also used for resources that imply the concept of restarts.

DELETE

Used to delete an existing resource

18.2. HTTP status codes

RESTful note tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

18.3. Headers

Every response has the following header(s):

Name Description

Content-Type

The Content-Type of the payload, e.g. application/hal+json

18.4. Errors

Path Type Description

error

String

The HTTP error that occurred, e.g. Bad Request

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

Number

The time, in milliseconds, at which the error occurred

18.5. Hypermedia

Spring Cloud Skipper uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application from resource to resource Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate.

19. Resources

19.1. Index

The index provides the entry point into Spring Cloud Skipper’s REST API.

19.1.1. Accessing the index

A GET request is used to access the index

Request structure
GET /api HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api' -i
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2149

{
  "_links" : {
    "appDeployerDatas" : {
      "href" : "http://localhost:7577/api/appDeployerDatas{?page,size,sort}",
      "templated" : true
    },
    "packageMetadata" : {
      "href" : "http://localhost:7577/api/packageMetadata{?page,size,sort,projection}",
      "templated" : true
    },
    "releases" : {
      "href" : "http://localhost:7577/api/releases{?page,size,sort}",
      "templated" : true
    },
    "deployers" : {
      "href" : "http://localhost:7577/api/deployers{?page,size,sort}",
      "templated" : true
    },
    "repositories" : {
      "href" : "http://localhost:7577/api/repositories{?page,size,sort}",
      "templated" : true
    },
    "about" : {
      "href" : "http://localhost:7577/api/about"
    },
    "upload" : {
      "href" : "http://localhost:7577/api/upload"
    },
    "install" : {
      "href" : "http://localhost:7577/api/install"
    },
    "install/id" : {
      "href" : "http://localhost:7577/api/install/{id}",
      "templated" : true
    },
    "status/name" : {
      "href" : "http://localhost:7577/api/status/{name}",
      "templated" : true
    },
    "status/name/version" : {
      "href" : "http://localhost:7577/api/status/{name}/123",
      "templated" : true
    },
    "manifest" : {
      "href" : "http://localhost:7577/api/manifest/{name}",
      "templated" : true
    },
    "manifest/name/version" : {
      "href" : "http://localhost:7577/api/manifest/{name}/123",
      "templated" : true
    },
    "upgrade" : {
      "href" : "http://localhost:7577/api/upgrade"
    },
    "rollback" : {
      "href" : "http://localhost:7577/api/rollback/{name}/123",
      "templated" : true
    },
    "delete" : {
      "href" : "http://localhost:7577/api/delete/{name}",
      "templated" : true
    },
    "history" : {
      "href" : "http://localhost:7577/api/history/{name}/123",
      "templated" : true
    },
    "list" : {
      "href" : "http://localhost:7577/api/list"
    },
    "list/name" : {
      "href" : "http://localhost:7577/api/list/{name}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:7577/api/profile"
    }
  }
}

The main element of the index are the links as they allow you to traverse the API and execute the desired functionality:

Relation Description

about

Provides meta information of the server

upload

Uploads a package

install

Installs a package

install/id

Installs a package by also providing the package id

appDeployerDatas

Exposes App Deployer Data

repositories

Exposes package repositories

deployers

Exposes deployer

releases

Exposes release information

packageMetadata

Provides details for Package Metadata

profile

Entrypoint to provide ALPS metadata defining simple descriptions of application-level semantics

status/name

Get the status for the last known release version of the release by the given release name

status/name/version

Get the status for the release by the given release name and version

manifest

Get a release’s manifest

manifest/name/version

Get a release’s manifest by providing name and version

upgrade

Upgrade a release

rollback

Rollback the release to a previous or a specific release

delete

Delete the release

history

List the history of versions for a given release

list

List the latest version of releases with status of deployed or failed

list/name

List the latest version of releases by release name with status of deployed or failed

19.2. Server Meta Information

19.2.1. Retrieving information about the server

A GET request will return meta information for Spring Cloud Skipper. This includes:

  • Server name, typically spring-cloud-skipper-server

  • Version of the server, e.g. 1.0.0.M3

Request structure
GET /api/about HTTP/1.1
Accept: application/json
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/about' -i \
    -H 'Accept: application/json'
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 39

{
  "name" : null,
  "version" : null
}
Response fields
Path Type Description

name

Null

Name of the Skipper server.

version

Null

Version of the Skipper server.

19.3. Upload

19.3.1. Upload a package

Upload a package into a configured local repository.

Request structure
POST /api/upload HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Host: localhost:7577
Content-Length: 2155

{
  "name" : "log",
  "repoName" : "local",
  "version" : "9.9.9",
  "extension" : "zip",
  "packageFileAsBytes" : "UEsDBAoAAAAAABirQ0sAAAAAAAAAAAAAAAAKABwAbG9nLTkuOS45L1VUCQADXzjUWWM41Fl1eAsAAQToAwAABOgDAABQSwMEFAAAAAgAGKtDS8fRN6fRAAAAKQEAABQAHABsb2ctOS45LjkvdmFsdWVzLnltbFVUCQADXzjUWV841Fl1eAsAAQToAwAABOgDAAB1Tjtrw0AM3u9XCDz70ma8zRDTJe3QdOko27J75F7odC4l5L9XtHQsCIT0PTs40YotCOwYGlVYM8PtljDS/W46ePvwFXQQ3ofnc69oRBFaYPWBrBJONAdkUjl7nII6SIaJoGCtSvNJz6/cGIRiCShUzU5cfU4OHu3RPtjX8TwOl9FEElxQ0BmAObckSjAdU1X1TNVpGIS8/WyAv/8T51aGtLxoYwcRd0rucMi82VrYp21lBT4zX+0ccltsFSaMFktxatZXn6494zR5+fX9p5z5BlBLAwQUAAAACABggjhLl0n3puQAAACOAQAAFQAcAGxvZy05LjkuOS9wYWNrYWdlLnltbFVUCQADNBPIWTg41Fl1eAsAAQToAwAABOgDAACFj7FOxDAMhvc8RR6AJhwb3RgqMTDdAbsvNa3VNo4SpxJvjxsELCehyFJkff5+GxK9Yy7Esbf7ySwUx96WhVLCbCJs2NuVJ7P/MI9On4GUfqdO7sHdu/PwMjxdBpMgLDDhhWsO+JbX3s4iqfTeTyRzvbrAmy8pU5y6sHIduyIZYetUqV/Iol6vkV7b6Peb9mfe/tyqbiL3bXXE//uNwFTaZZOCd7ZQXMwGFEUL8+2l+foZZl2AzYglZErS7n+d8RA1h60FixXtaNxKAQ6kxWC2wparpCoNGEHAfnC2FEvCcIDOfAFQSwMECgAAAAAAGKtDSwAAAAAAAAAAAAAAABQAHABsb2ctOS45LjkvdGVtcGxhdGVzL1VUCQADXzjUWWM41Fl1eAsAAQToAwAABOgDAABQSwMEFAAAAAgAGKtDS+YXM8/oAAAAQAIAABsAHABsb2ctOS45LjkvdGVtcGxhdGVzL2xvZy55bWxVVAkAA1841FlfONRZdXgLAAEE6AMAAAToAwAApVA9a8MwEN39KwSdI9NVW7MXCoHuF/liVNu64yQ7GOP/3pODA4WUtnSTnp7eF3B4R0mBojOpC8wo9fRcdSE2zpxYQmyPRPmFuRowQwMZXGVMhAGd6anVs6cxZmeWZSfYDVlXfcszKy+F2FWJ0ZevgolG8QoPMGF0dU3S2rRZXUR1rySd9T2NjU1ZEAYLzE69DkXnIHA+h+yWZbrl3nx20dc94//EP0Dcve5XJ6X3wUPW+5uQzpUDptLL6AJPpaR9SLEYs8wnvO1SyB3O61p2m6Af8Q7Xv9VokHuaB8W+C/KI8cccP0l8AlBLAQIeAwoAAAAAABirQ0sAAAAAAAAAAAAAAAAKABgAAAAAAAAAEAD9QQAAAABsb2ctOS45LjkvVVQFAANfONRZdXgLAAEE6AMAAAToAwAAUEsBAh4DFAAAAAgAGKtDS8fRN6fRAAAAKQEAABQAGAAAAAAAAQAAALSBRAAAAGxvZy05LjkuOS92YWx1ZXMueW1sVVQFAANfONRZdXgLAAEE6AMAAAToAwAAUEsBAh4DFAAAAAgAYII4S5dJ96bkAAAAjgEAABUAGAAAAAAAAQAAALSBYwEAAGxvZy05LjkuOS9wYWNrYWdlLnltbFVUBQADNBPIWXV4CwABBOgDAAAE6AMAAFBLAQIeAwoAAAAAABirQ0sAAAAAAAAAAAAAAAAUABgAAAAAAAAAEAD9QZYCAABsb2ctOS45LjkvdGVtcGxhdGVzL1VUBQADXzjUWXV4CwABBOgDAAAE6AMAAFBLAQIeAxQAAAAIABirQ0vmFzPP6AAAAEACAAAbABgAAAAAAAEAAAC0geQCAABsb2ctOS45LjkvdGVtcGxhdGVzL2xvZy55bWxVVAUAA1841Fl1eAsAAQToAwAABOgDAABQSwUGAAAAAAUABQDAAQAAIQQAAAAA"
}
Example request
$ curl 'http://localhost:7577/api/upload' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "name" : "log",
  "repoName" : "local",
  "version" : "9.9.9",
  "extension" : "zip",
  "packageFileAsBytes" : "UEsDBAoAAAAAABirQ0sAAAAAAAAAAAAAAAAKABwAbG9nLTkuOS45L1VUCQADXzjUWWM41Fl1eAsAAQToAwAABOgDAABQSwMEFAAAAAgAGKtDS8fRN6fRAAAAKQEAABQAHABsb2ctOS45LjkvdmFsdWVzLnltbFVUCQADXzjUWV841Fl1eAsAAQToAwAABOgDAAB1Tjtrw0AM3u9XCDz70ma8zRDTJe3QdOko27J75F7odC4l5L9XtHQsCIT0PTs40YotCOwYGlVYM8PtljDS/W46ePvwFXQQ3ofnc69oRBFaYPWBrBJONAdkUjl7nII6SIaJoGCtSvNJz6/cGIRiCShUzU5cfU4OHu3RPtjX8TwOl9FEElxQ0BmAObckSjAdU1X1TNVpGIS8/WyAv/8T51aGtLxoYwcRd0rucMi82VrYp21lBT4zX+0ccltsFSaMFktxatZXn6494zR5+fX9p5z5BlBLAwQUAAAACABggjhLl0n3puQAAACOAQAAFQAcAGxvZy05LjkuOS9wYWNrYWdlLnltbFVUCQADNBPIWTg41Fl1eAsAAQToAwAABOgDAACFj7FOxDAMhvc8RR6AJhwb3RgqMTDdAbsvNa3VNo4SpxJvjxsELCehyFJkff5+GxK9Yy7Esbf7ySwUx96WhVLCbCJs2NuVJ7P/MI9On4GUfqdO7sHdu/PwMjxdBpMgLDDhhWsO+JbX3s4iqfTeTyRzvbrAmy8pU5y6sHIduyIZYetUqV/Iol6vkV7b6Peb9mfe/tyqbiL3bXXE//uNwFTaZZOCd7ZQXMwGFEUL8+2l+foZZl2AzYglZErS7n+d8RA1h60FixXtaNxKAQ6kxWC2wparpCoNGEHAfnC2FEvCcIDOfAFQSwMECgAAAAAAGKtDSwAAAAAAAAAAAAAAABQAHABsb2ctOS45LjkvdGVtcGxhdGVzL1VUCQADXzjUWWM41Fl1eAsAAQToAwAABOgDAABQSwMEFAAAAAgAGKtDS+YXM8/oAAAAQAIAABsAHABsb2ctOS45LjkvdGVtcGxhdGVzL2xvZy55bWxVVAkAA1841FlfONRZdXgLAAEE6AMAAAToAwAApVA9a8MwEN39KwSdI9NVW7MXCoHuF/liVNu64yQ7GOP/3pODA4WUtnSTnp7eF3B4R0mBojOpC8wo9fRcdSE2zpxYQmyPRPmFuRowQwMZXGVMhAGd6anVs6cxZmeWZSfYDVlXfcszKy+F2FWJ0ZevgolG8QoPMGF0dU3S2rRZXUR1rySd9T2NjU1ZEAYLzE69DkXnIHA+h+yWZbrl3nx20dc94//EP0Dcve5XJ6X3wUPW+5uQzpUDptLL6AJPpaR9SLEYs8wnvO1SyB3O61p2m6Af8Q7Xv9VokHuaB8W+C/KI8cccP0l8AlBLAQIeAwoAAAAAABirQ0sAAAAAAAAAAAAAAAAKABgAAAAAAAAAEAD9QQAAAABsb2ctOS45LjkvVVQFAANfONRZdXgLAAEE6AMAAAToAwAAUEsBAh4DFAAAAAgAGKtDS8fRN6fRAAAAKQEAABQAGAAAAAAAAQAAALSBRAAAAGxvZy05LjkuOS92YWx1ZXMueW1sVVQFAANfONRZdXgLAAEE6AMAAAToAwAAUEsBAh4DFAAAAAgAYII4S5dJ96bkAAAAjgEAABUAGAAAAAAAAQAAALSBYwEAAGxvZy05LjkuOS9wYWNrYWdlLnltbFVUBQADNBPIWXV4CwABBOgDAAAE6AMAAFBLAQIeAwoAAAAAABirQ0sAAAAAAAAAAAAAAAAUABgAAAAAAAAAEAD9QZYCAABsb2ctOS45LjkvdGVtcGxhdGVzL1VUBQADXzjUWXV4CwABBOgDAAAE6AMAAFBLAQIeAxQAAAAIABirQ0vmFzPP6AAAAEACAAAbABgAAAAAAAEAAAC0geQCAABsb2ctOS45LjkvdGVtcGxhdGVzL2xvZy55bWxVVAUAA1841Fl1eAsAAQToAwAABOgDAABQSwUGAAAAAAUABQDAAQAAIQQAAAAA"
}'
Response structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 526

{
  "apiVersion" : "v1",
  "origin" : null,
  "repositoryId" : 2,
  "kind" : "skipper",
  "name" : "log",
  "version" : "9.9.9",
  "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RELEASE",
  "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
  "tags" : "logging, sink",
  "maintainer" : "https://github.com/sobychacko",
  "description" : "The log sink uses the application logger to output the data for inspection.",
  "sha256" : null,
  "iconUrl" : null
}
Response fields
Path Type Description

apiVersion

String

The Package Index spec version this file is based on

origin

Null

Indicates the origin of the repository (free form text)

repositoryId

Number

The repository ID this Package Index file belongs to

kind

String

What type of package system is being used

name

String

The name of the package

version

String

The version of the package

packageSourceUrl

String

Location to source code for this package

packageHomeUrl

String

The home page of the package

tags

String

A comma separated list of tags to use for searching

maintainer

String

Who is maintaining this package

description

String

Brief description of the package

sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

iconUrl

Null

Url location of a icon

19.4. Install

19.4.1. Install a package

Install a package (identified by the InstallRequest) into the target platform.

Request structure
POST /api/install HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Host: localhost:7577
Content-Length: 223

{
  "packageIdentifier" : {
    "repositoryName" : "notused",
    "packageName" : "log",
    "packageVersion" : "1.0.0"
  },
  "installProperties" : {
    "releaseName" : "myLogRelease",
    "platformName" : "default"
  }
}
Example request
$ curl 'http://localhost:7577/api/install' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "packageIdentifier" : {
    "repositoryName" : "notused",
    "packageName" : "log",
    "packageVersion" : "1.0.0"
  },
  "installProperties" : {
    "releaseName" : "myLogRelease",
    "platformName" : "default"
  }
}'
Response structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 2929

{
  "name" : "myLogRelease",
  "version" : 1,
  "info" : {
    "status" : {
      "statusCode" : "DEPLOYED",
      "platformStatus" : "[{\"deploymentId\":\"myLogRelease.log-v1\",\"instances\":{\"myLogRelease.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:20343\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"20343\",\"pid\":\"20154\",\"port\":\"20343\",\"stderr\":\"/tmp/spring-cloud-dataflow-1577899662462569014/myLogRelease-1512522551265/myLogRelease.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-1577899662462569014/myLogRelease-1512522551265/myLogRelease.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:20343\",\"working.dir\":\"/tmp/spring-cloud-dataflow-1577899662462569014/myLogRelease-1512522551265/myLogRelease.log-v1\"},\"id\":\"myLogRelease.log-v1-0\",\"state\":\"deploying\"}},\"state\":\"deploying\"}]"
    },
    "firstDeployed" : 1512522551255,
    "lastDeployed" : 1512522551255,
    "deleted" : null,
    "description" : "Install complete"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.2.0.RC1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.2.0.RC1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
}
Response fields
Path Type Description

name

String

Name of the release

version

Number

Version of the release

info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

info.status.platformStatus

String

Status from the underlying platform

info.firstDeployed

Number

Date/Time of first deployment

info.lastDeployed

Number

Date/Time of last deployment

info.deleted

Null

Date/Time of when the release was deleted

info.description

String

Human-friendly 'log entry' about this release

pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

pkg.metadata.kind

String

What type of package system is being used

pkg.metadata.name

String

The name of the package

pkg.metadata.version

String

The version of the package

pkg.metadata.packageSourceUrl

String

Location to source code for this package

pkg.metadata.packageHomeUrl

String

The home page of the package

pkg.metadata.tags

String

A comma separated list of tags to use for searching

pkg.metadata.maintainer

String

Who is maintaining this package

pkg.metadata.description

String

Brief description of the package

pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

pkg.metadata.iconUrl

Null

Url location of a icon

pkg.templates[].name

String

Name is the path-like name of the template

pkg.templates[].data

String

Data is the template as string data

pkg.dependencies

Array

The packages that this package depends upon

pkg.configValues.raw

String

The raw YAML string of configuration values

pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

configValues.raw

Null

The raw YAML string of configuration values

manifest

String

The manifest of the release

platformName

String

Platform name of the release

19.4.2. Install a package with id

Install a package identified by its ID into the target platform.

Request structure
POST /api/install/2 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Host: localhost:7577
Content-Length: 87

{
  "releaseName" : "myLogReleaseWithInstallProperties",
  "platformName" : "default"
}
Example request
$ curl 'http://localhost:7577/api/install/2' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "releaseName" : "myLogReleaseWithInstallProperties",
  "platformName" : "default"
}'
Response structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 3141

{
  "name" : "myLogReleaseWithInstallProperties",
  "version" : 1,
  "info" : {
    "status" : {
      "statusCode" : "DEPLOYED",
      "platformStatus" : "[{\"deploymentId\":\"myLogReleaseWithInstallProperties.log-v1\",\"instances\":{\"myLogReleaseWithInstallProperties.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:44059\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"44059\",\"pid\":\"20231\",\"port\":\"44059\",\"stderr\":\"/tmp/spring-cloud-dataflow-1577899662462569014/myLogReleaseWithInstallProperties-1512522566471/myLogReleaseWithInstallProperties.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-1577899662462569014/myLogReleaseWithInstallProperties-1512522566471/myLogReleaseWithInstallProperties.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:44059\",\"working.dir\":\"/tmp/spring-cloud-dataflow-1577899662462569014/myLogReleaseWithInstallProperties-1512522566471/myLogReleaseWithInstallProperties.log-v1\"},\"id\":\"myLogReleaseWithInstallProperties.log-v1-0\",\"state\":\"deploying\"}},\"state\":\"deploying\"}]"
    },
    "firstDeployed" : 1512522566464,
    "lastDeployed" : 1512522566464,
    "deleted" : null,
    "description" : "Install complete"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.1.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.3.0.M1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.3.0.M1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
}
Response fields
Path Type Description

name

String

Name of the release

version

Number

Version of the release

info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

info.status.platformStatus

String

Status from the underlying platform

info.firstDeployed

Number

Date/Time of first deployment

info.lastDeployed

Number

Date/Time of last deployment

info.deleted

Null

Date/Time of when the release was deleted

info.description

String

Human-friendly 'log entry' about this release

pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

pkg.metadata.kind

String

What type of package system is being used

pkg.metadata.name

String

The name of the package

pkg.metadata.version

String

The version of the package

pkg.metadata.packageSourceUrl

String

Location to source code for this package

pkg.metadata.packageHomeUrl

String

The home page of the package

pkg.metadata.tags

String

A comma separated list of tags to use for searching

pkg.metadata.maintainer

String

Who is maintaining this package

pkg.metadata.description

String

Brief description of the package

pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

pkg.metadata.iconUrl

Null

Url location of a icon

pkg.templates[].name

String

Name is the path-like name of the template

pkg.templates[].data

String

Data is the template as string data

pkg.dependencies

Array

The packages that this package depends upon

pkg.configValues.raw

String

The raw YAML string of configuration values

pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

configValues.raw

Null

The raw YAML string of configuration values

manifest

String

The manifest of the release

platformName

String

Platform name of the release

19.5. Status

19.5.1. Get status of release

This REST endpoint provides the status for the last known release version.

Request structure
GET /api/status/myLogRelease HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/status/myLogRelease' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 990

{
  "status" : {
    "statusCode" : "DEPLOYED",
    "platformStatus" : "[{\"deploymentId\":\"myLogRelease.log-v1\",\"instances\":{\"myLogRelease.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:64142\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"64142\",\"pid\":\"19621\",\"port\":\"64142\",\"stderr\":\"/tmp/spring-cloud-dataflow-7113709307438055616/myLogRelease-1512522414695/myLogRelease.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-7113709307438055616/myLogRelease-1512522414695/myLogRelease.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:64142\",\"working.dir\":\"/tmp/spring-cloud-dataflow-7113709307438055616/myLogRelease-1512522414695/myLogRelease.log-v1\"},\"id\":\"myLogRelease.log-v1-0\",\"state\":\"deployed\"}},\"state\":\"deployed\"}]"
  },
  "firstDeployed" : 1512522414678,
  "lastDeployed" : 1512522414678,
  "deleted" : null,
  "description" : "Install complete"
}
Response fields
Path Type Description

status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

status.platformStatus

String

Status from the underlying platform

firstDeployed

Number

Date/Time of first deployment

lastDeployed

Number

Date/Time of last deployment

deleted

Null

Date/Time of when the release was deleted

description

String

Human-friendly 'log entry' about this release

19.5.2. Get status of release for a specific version

This REST endpoint provides the status for a specific release version.

Request structure
GET /api/status/myLogRelease2/1 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/status/myLogRelease2/1' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 999

{
  "status" : {
    "statusCode" : "DEPLOYED",
    "platformStatus" : "[{\"deploymentId\":\"myLogRelease2.log-v1\",\"instances\":{\"myLogRelease2.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:32291\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"32291\",\"pid\":\"19680\",\"port\":\"32291\",\"stderr\":\"/tmp/spring-cloud-dataflow-7113709307438055616/myLogRelease2-1512522430175/myLogRelease2.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-7113709307438055616/myLogRelease2-1512522430175/myLogRelease2.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:32291\",\"working.dir\":\"/tmp/spring-cloud-dataflow-7113709307438055616/myLogRelease2-1512522430175/myLogRelease2.log-v1\"},\"id\":\"myLogRelease2.log-v1-0\",\"state\":\"deployed\"}},\"state\":\"deployed\"}]"
  },
  "firstDeployed" : 1512522430157,
  "lastDeployed" : 1512522430157,
  "deleted" : null,
  "description" : "Install complete"
}
Response fields
Path Type Description

status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

status.platformStatus

String

Status from the underlying platform

firstDeployed

Number

Date/Time of first deployment

lastDeployed

Number

Date/Time of last deployment

deleted

Null

Date/Time of when the release was deleted

description

String

Human-friendly 'log entry' about this release

19.6. Manifest

19.6.1. Get the manifest

REST endpoint that returns the manifest for the last known release version.

Request structure
GET /api/manifest/myLogRelease HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/manifest/myLogRelease' -i \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 277


---
# Source: log.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: log
  type: sink
spec:
  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit
  version: 1.2.0.RC1
  applicationProperties:
  deploymentProperties:

19.6.2. Get the manifest for a specific version

REST endpoint that returns the manifest for a specific release version.

Request structure
GET /api/manifest/myLogRelease2/1 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/manifest/myLogRelease2/1' -i
Response structure
HTTP/1.1 200 OK
Content-Type: text/plain;charset=ISO-8859-1
Content-Length: 277


---
# Source: log.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: log
  type: sink
spec:
  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit
  version: 1.2.0.RC1
  applicationProperties:
  deploymentProperties:

19.7. Upgrade

19.7.1. Upgrade a release

Upgrade an existing release using the configured package and config values from the UpgradeRequest.

Request structure
POST /api/upgrade HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Host: localhost:7577
Content-Length: 157

{
  "packageIdentifier" : {
    "packageName" : "log",
    "packageVersion" : "1.1.0"
  },
  "upgradeProperties" : {
    "releaseName" : "myLogRelease"
  }
}
Example request
$ curl 'http://localhost:7577/api/upgrade' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "packageIdentifier" : {
    "packageName" : "log",
    "packageVersion" : "1.1.0"
  },
  "upgradeProperties" : {
    "releaseName" : "myLogRelease"
  }
}'
Response structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 2154

{
  "name" : "myLogRelease",
  "version" : 2,
  "info" : {
    "status" : {
      "statusCode" : "UNKNOWN",
      "platformStatus" : null
    },
    "firstDeployed" : 1512522463706,
    "lastDeployed" : 1512522463706,
    "deleted" : null,
    "description" : "Upgrade install underway"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.1.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.3.0.M1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.3.0.M1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
}
Response fields
Path Type Description

name

String

Name of the release

version

Number

Version of the release

info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

info.status.platformStatus

Null

Status from the underlying platform

info.firstDeployed

Number

Date/Time of first deployment

info.lastDeployed

Number

Date/Time of last deployment

info.deleted

Null

Date/Time of when the release was deleted

info.description

String

Human-friendly 'log entry' about this release

pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

pkg.metadata.kind

String

What type of package system is being used

pkg.metadata.name

String

The name of the package

pkg.metadata.version

String

The version of the package

pkg.metadata.packageSourceUrl

String

Location to source code for this package

pkg.metadata.packageHomeUrl

String

The home page of the package

pkg.metadata.tags

String

A comma separated list of tags to use for searching

pkg.metadata.maintainer

String

Who is maintaining this package

pkg.metadata.description

String

Brief description of the package

pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

pkg.metadata.iconUrl

Null

Url location of a icon

pkg.templates[].name

String

Name is the path-like name of the template

pkg.templates[].data

String

Data is the template as string data

pkg.dependencies

Array

The packages that this package depends upon

pkg.configValues.raw

String

The raw YAML string of configuration values

pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

configValues.raw

Null

The raw YAML string of configuration values

manifest

String

The manifest of the release

platformName

String

Platform name of the release

19.8. Rollback

19.8.1. Rollback release

Rollback the release to a previous or a specific release.

Request structure
POST /api/rollback/myLogRelease/1 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/rollback/myLogRelease/1' -i -X POST
Response structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 2152

{
  "name" : "myLogRelease",
  "version" : 3,
  "info" : {
    "status" : {
      "statusCode" : "UNKNOWN",
      "platformStatus" : null
    },
    "firstDeployed" : 1512522346738,
    "lastDeployed" : 1512522346738,
    "deleted" : null,
    "description" : "Initial install underway"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.2.0.RC1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.2.0.RC1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
}
Response fields
Path Type Description

name

String

Name of the release

version

Number

Version of the release

info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

info.status.platformStatus

Null

Status from the underlying platform

info.firstDeployed

Number

Date/Time of first deployment

info.lastDeployed

Number

Date/Time of last deployment

info.deleted

Null

Date/Time of when the release was deleted

info.description

String

Human-friendly 'log entry' about this release

pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

pkg.metadata.kind

String

What type of package system is being used

pkg.metadata.name

String

The name of the package

pkg.metadata.version

String

The version of the package

pkg.metadata.packageSourceUrl

String

Location to source code for this package

pkg.metadata.packageHomeUrl

String

The home page of the package

pkg.metadata.tags

String

A comma separated list of tags to use for searching

pkg.metadata.maintainer

String

Who is maintaining this package

pkg.metadata.description

String

Brief description of the package

pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

pkg.metadata.iconUrl

Null

Url location of a icon

pkg.templates[].name

String

Name is the path-like name of the template

pkg.templates[].data

String

Data is the template as string data

pkg.dependencies

Array

The packages that this package depends upon

pkg.configValues.raw

String

The raw YAML string of configuration values

pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

configValues.raw

Null

The raw YAML string of configuration values

manifest

String

The manifest of the release

platformName

String

Platform name of the release

19.9. Delete

19.9.1. Delete a release

Delete an existing release by uninstalling the installed packages corresponding to the release.

Request structure
POST /api/delete/myLogRelease HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/delete/myLogRelease' -i -X POST
Response structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 2143

{
  "name" : "myLogRelease",
  "version" : 1,
  "info" : {
    "status" : {
      "statusCode" : "DELETED",
      "platformStatus" : null
    },
    "firstDeployed" : 1512522374041,
    "lastDeployed" : 1512522374041,
    "deleted" : null,
    "description" : "Delete complete"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.2.0.RC1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.2.0.RC1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
}
Response fields
Path Type Description

name

String

Name of the release

version

Number

Version of the release

info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

info.status.platformStatus

Null

Status from the underlying platform

info.firstDeployed

Number

Date/Time of first deployment

info.lastDeployed

Number

Date/Time of last deployment

info.deleted

Null

Date/Time of when the release was deleted

info.description

String

Human-friendly 'log entry' about this release

pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

pkg.metadata.kind

String

What type of package system is being used

pkg.metadata.name

String

The name of the package

pkg.metadata.version

String

The version of the package

pkg.metadata.packageSourceUrl

String

Location to source code for this package

pkg.metadata.packageHomeUrl

String

The home page of the package

pkg.metadata.tags

String

A comma separated list of tags to use for searching

pkg.metadata.maintainer

String

Who is maintaining this package

pkg.metadata.description

String

Brief description of the package

pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

pkg.metadata.iconUrl

Null

Url location of a icon

pkg.templates[].name

String

Name is the path-like name of the template

pkg.templates[].data

String

Data is the template as string data

pkg.dependencies

Array

The packages that this package depends upon

pkg.configValues.raw

String

The raw YAML string of configuration values

pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

configValues.raw

Null

The raw YAML string of configuration values

manifest

String

The manifest of the release

platformName

String

Platform name of the release

19.10. History

19.10.1. Show version history

List the history of versions for a given release.

Request structure
GET /api/history/myLogRelease/3 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/history/myLogRelease/3' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2931

[ {
  "name" : "myLogRelease",
  "version" : 1,
  "info" : {
    "status" : {
      "statusCode" : "DEPLOYED",
      "platformStatus" : "[{\"deploymentId\":\"myLogRelease.log-v1\",\"instances\":{\"myLogRelease.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:53806\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"53806\",\"pid\":\"20374\",\"port\":\"53806\",\"stderr\":\"/tmp/spring-cloud-dataflow-7566479659457130646/myLogRelease-1512522601698/myLogRelease.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-7566479659457130646/myLogRelease-1512522601698/myLogRelease.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:53806\",\"working.dir\":\"/tmp/spring-cloud-dataflow-7566479659457130646/myLogRelease-1512522601698/myLogRelease.log-v1\"},\"id\":\"myLogRelease.log-v1-0\",\"state\":\"deployed\"}},\"state\":\"deployed\"}]"
    },
    "firstDeployed" : 1512522601689,
    "lastDeployed" : 1512522601689,
    "deleted" : null,
    "description" : "Install complete"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.2.0.RC1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.2.0.RC1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
} ]
Response fields
Path Type Description

[].name

String

Name of the release

[].version

Number

Version of the release

[].info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

[].info.status.platformStatus

String

Status from the underlying platform

[].info.firstDeployed

Number

Date/Time of first deployment

[].info.lastDeployed

Number

Date/Time of last deployment

[].info.deleted

Null

Date/Time of when the release was deleted

[].info.description

String

Human-friendly 'log entry' about this release

[].pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

[].pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

[].pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

[].pkg.metadata.kind

String

What type of package system is being used

[].pkg.metadata.name

String

The name of the package

[].pkg.metadata.version

String

The version of the package

[].pkg.metadata.packageSourceUrl

String

Location to source code for this package

[].pkg.metadata.packageHomeUrl

String

The home page of the package

[].pkg.metadata.tags

String

A comma separated list of tags to use for searching

[].pkg.metadata.maintainer

String

Who is maintaining this package

[].pkg.metadata.description

String

Brief description of the package

[].pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

[].pkg.metadata.iconUrl

Null

Url location of a icon

[].pkg.templates[].name

String

Name is the path-like name of the template

[].pkg.templates[].data

String

Data is the template as string data

[].pkg.dependencies

Array

The packages that this package depends upon

[].pkg.configValues.raw

String

The raw YAML string of configuration values

[].pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

[].configValues.raw

Null

The raw YAML string of configuration values

[].manifest

String

The manifest of the release

[].platformName

String

Platform name of the release

19.11. List

19.11.1. List

List the latest version of releases with status of deployed or failed.

Request structure
GET /api/list HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/list' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2931

[ {
  "name" : "myLogRelease",
  "version" : 1,
  "info" : {
    "status" : {
      "statusCode" : "DEPLOYED",
      "platformStatus" : "[{\"deploymentId\":\"myLogRelease.log-v1\",\"instances\":{\"myLogRelease.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:31894\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"31894\",\"pid\":\"20080\",\"port\":\"31894\",\"stderr\":\"/tmp/spring-cloud-dataflow-3305576492408317010/myLogRelease-1512522534413/myLogRelease.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-3305576492408317010/myLogRelease-1512522534413/myLogRelease.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:31894\",\"working.dir\":\"/tmp/spring-cloud-dataflow-3305576492408317010/myLogRelease-1512522534413/myLogRelease.log-v1\"},\"id\":\"myLogRelease.log-v1-0\",\"state\":\"deployed\"}},\"state\":\"deployed\"}]"
    },
    "firstDeployed" : 1512522534406,
    "lastDeployed" : 1512522534406,
    "deleted" : null,
    "description" : "Install complete"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.2.0.RC1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.2.0.RC1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
} ]
Response fields
Path Type Description

[].name

String

Name of the release

[].version

Number

Version of the release

[].info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

[].info.status.platformStatus

String

Status from the underlying platform

[].info.firstDeployed

Number

Date/Time of first deployment

[].info.lastDeployed

Number

Date/Time of last deployment

[].info.deleted

Null

Date/Time of when the release was deleted

[].info.description

String

Human-friendly 'log entry' about this release

[].pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

[].pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

[].pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

[].pkg.metadata.kind

String

What type of package system is being used

[].pkg.metadata.name

String

The name of the package

[].pkg.metadata.version

String

The version of the package

[].pkg.metadata.packageSourceUrl

String

Location to source code for this package

[].pkg.metadata.packageHomeUrl

String

The home page of the package

[].pkg.metadata.tags

String

A comma separated list of tags to use for searching

[].pkg.metadata.maintainer

String

Who is maintaining this package

[].pkg.metadata.description

String

Brief description of the package

[].pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

[].pkg.metadata.iconUrl

Null

Url location of a icon

[].pkg.templates[].name

String

Name is the path-like name of the template

[].pkg.templates[].data

String

Data is the template as string data

[].pkg.dependencies

Array

The packages that this package depends upon

[].pkg.configValues.raw

String

The raw YAML string of configuration values

[].pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

[].configValues.raw

Null

The raw YAML string of configuration values

[].manifest

String

The manifest of the release

[].platformName

String

Platform name of the release

19.11.2. List by release name

List the latest version of releases with status of deployed or failed by the given release name.

Request structure
GET /api/list/myLogRelease2 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/list/myLogRelease2' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2941

[ {
  "name" : "myLogRelease2",
  "version" : 1,
  "info" : {
    "status" : {
      "statusCode" : "DEPLOYED",
      "platformStatus" : "[{\"deploymentId\":\"myLogRelease2.log-v1\",\"instances\":{\"myLogRelease2.log-v1-0\":{\"instanceNumber\":0,\"baseUrl\":\"http://10.194.6.14:28655\",\"process\":{\"errorStream\":{},\"outputStream\":{},\"alive\":true,\"inputStream\":{}},\"attributes\":{\"guid\":\"28655\",\"pid\":\"20012\",\"port\":\"28655\",\"stderr\":\"/tmp/spring-cloud-dataflow-3305576492408317010/myLogRelease2-1512522519004/myLogRelease2.log-v1/stderr_0.log\",\"stdout\":\"/tmp/spring-cloud-dataflow-3305576492408317010/myLogRelease2-1512522519004/myLogRelease2.log-v1/stdout_0.log\",\"url\":\"http://10.194.6.14:28655\",\"working.dir\":\"/tmp/spring-cloud-dataflow-3305576492408317010/myLogRelease2-1512522519004/myLogRelease2.log-v1\"},\"id\":\"myLogRelease2.log-v1-0\",\"state\":\"deployed\"}},\"state\":\"deployed\"}]"
    },
    "firstDeployed" : 1512522518993,
    "lastDeployed" : 1512522518993,
    "deleted" : null,
    "description" : "Install complete"
  },
  "pkg" : {
    "metadata" : {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null
    },
    "templates" : [ {
      "name" : "log.yml",
      "data" : "apiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: {{version}}\n  applicationProperties:\n    {{#spec.applicationProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.applicationProperties.entrySet}}\n  deploymentProperties:\n    {{#spec.deploymentProperties.entrySet}}\n    {{key}}: {{value}}\n    {{/spec.deploymentProperties.entrySet}}\n"
    } ],
    "dependencies" : [ ],
    "configValues" : {
      "raw" : "# Default values for {{name}}\n# This is a YAML-formatted file.\n# Declare variables to be passed into your templates\nversion: 1.2.0.RC1\n"
    },
    "fileHolders" : [ ]
  },
  "configValues" : {
    "raw" : null
  },
  "manifest" : "\n---\n# Source: log.yml\napiVersion: skipper.spring.io/v1\nkind: SpringCloudDeployerApplication\nmetadata:\n  name: log\n  type: sink\nspec:\n  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit\n  version: 1.2.0.RC1\n  applicationProperties:\n  deploymentProperties:\n",
  "platformName" : "default"
} ]
Response fields
Path Type Description

[].name

String

Name of the release

[].version

Number

Version of the release

[].info.status.statusCode

String

StatusCode of the release’s status (UNKNOWN,DEPLOYED,DELETED,FAILED)

[].info.status.platformStatus

String

Status from the underlying platform

[].info.firstDeployed

Number

Date/Time of first deployment

[].info.lastDeployed

Number

Date/Time of last deployment

[].info.deleted

Null

Date/Time of when the release was deleted

[].info.description

String

Human-friendly 'log entry' about this release

[].pkg.metadata.apiVersion

String

The Package Index spec version this file is based on

[].pkg.metadata.origin

String

Indicates the origin of the repository (free form text)

[].pkg.metadata.repositoryId

Number

The repository ID this Package Index file belongs to

[].pkg.metadata.kind

String

What type of package system is being used

[].pkg.metadata.name

String

The name of the package

[].pkg.metadata.version

String

The version of the package

[].pkg.metadata.packageSourceUrl

String

Location to source code for this package

[].pkg.metadata.packageHomeUrl

String

The home page of the package

[].pkg.metadata.tags

String

A comma separated list of tags to use for searching

[].pkg.metadata.maintainer

String

Who is maintaining this package

[].pkg.metadata.description

String

Brief description of the package

[].pkg.metadata.sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

[].pkg.metadata.iconUrl

Null

Url location of a icon

[].pkg.templates[].name

String

Name is the path-like name of the template

[].pkg.templates[].data

String

Data is the template as string data

[].pkg.dependencies

Array

The packages that this package depends upon

[].pkg.configValues.raw

String

The raw YAML string of configuration values

[].pkg.fileHolders

Array

Miscellaneous files in a package, e.g. README, LICENSE, etc.

[].configValues.raw

Null

The raw YAML string of configuration values

[].manifest

String

The manifest of the release

[].platformName

String

Platform name of the release

19.12. Resources Repositories

19.12.1. Retrieving a list of repositories

A GET request will return a paginated list for all Spring Cloud Skipper repositories.

Request structure
GET /api/repositories?page=0&size=10 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/repositories?page=0&size=10' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1321

{
  "_embedded" : {
    "repositories" : [ {
      "name" : "test",
      "url" : "classpath:/repositories/binaries/test",
      "sourceUrl" : null,
      "local" : false,
      "description" : "test repository with a few packages",
      "repoOrder" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/repositories/1"
        },
        "repository" : {
          "href" : "http://localhost:7577/api/repositories/1"
        }
      }
    }, {
      "name" : "local",
      "url" : "http://localhost:7577",
      "sourceUrl" : null,
      "local" : true,
      "description" : "Default local database backed repository",
      "repoOrder" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/repositories/2"
        },
        "repository" : {
          "href" : "http://localhost:7577/api/repositories/2"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/repositories{&sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:7577/api/profile/repositories"
    },
    "search" : {
      "href" : "http://localhost:7577/api/repositories/search"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}
Response fields
Path Type Description

page

Object

Pagination properties

page.size

Number

The size of the page being returned

page.totalElements

Number

Total elements available for pagination

page.totalPages

Number

Total amount of pages

page.number

Number

Page number of the page returned (zero-based)

_embedded.repositories

Array

Contains a collection of Repositories

_embedded.repositories[].name

String

Name of the Repository

_embedded.repositories[].url

String

Url of the Repository

_embedded.repositories[].sourceUrl

Null

Source Url of the repository

_embedded.repositories[].description

String

Description of the Repository

_embedded.repositories[].local

Boolean

Is the repo local?

_embedded.repositories[].repoOrder

Null

Order of the Repository

19.12.2. Retrieving a single repository

A GET request will return a single Spring Cloud Skipper repositories.

Request structure
GET /api/repositories/1 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/repositories/1' -i
Response structure
HTTP/1.1 200 OK
ETag: "0"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 377

{
  "name" : "test",
  "url" : "classpath:/repositories/binaries/test",
  "sourceUrl" : null,
  "local" : false,
  "description" : "test repository with a few packages",
  "repoOrder" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/repositories/1"
    },
    "repository" : {
      "href" : "http://localhost:7577/api/repositories/1"
    }
  }
}
Response fields
Path Type Description

name

String

Name of the Repository

url

String

URL of the Repository

description

String

Description of the Repository

local

Boolean

Is the repo local?

repoOrder

Null

Order of the Repository

sourceUrl

Null

Source URL of the repository

19.13. App Deployers Datas

19.13.1. Retrieving a list of app deployer datas

A GET request will return a paginated list for all Spring Cloud Skipper app deployer data.

Request structure
GET /api/appDeployerDatas?page=0&size=10 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/appDeployerDatas?page=0&size=10' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 471

{
  "_embedded" : {
    "appDeployerDatas" : [ ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/appDeployerDatas{&sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:7577/api/profile/appDeployerDatas"
    },
    "search" : {
      "href" : "http://localhost:7577/api/appDeployerDatas/search"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}
Response fields
Path Type Description

page

Object

Pagination properties

page.size

Number

The size of the page being returned

page.totalElements

Number

Total elements available for pagination

page.totalPages

Number

Total amount of pages

page.number

Number

Page number of the page returned (zero-based)

_embedded.appDeployerDatas

Array

Array of App Deployer Data objects.

19.14. Deployers

19.14.1. Retrieving a list of app deployers

A GET request will return a paginated list for all the Spring Cloud Skipper application deployers.

Request structure
GET /api/deployers?page=0&size=10 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/deployers?page=0&size=10' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 983

{
  "_embedded" : {
    "deployers" : [ {
      "name" : "default",
      "type" : "local",
      "description" : "ShutdownTimeout = [30], EnvVarsToInherit = [TMP,LANG,LANGUAGE,LC_.*,PATH], JavaCmd = [/opt/jdk1.8.0_144/jre/bin/java], WorkingDirectoriesRoot = [/tmp], DeleteFilesOnExit = [true]",
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/deployers/509f73ab-5f7f-4475-8e09-14fb770d7ade"
        },
        "deployer" : {
          "href" : "http://localhost:7577/api/deployers/509f73ab-5f7f-4475-8e09-14fb770d7ade"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/deployers{&sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:7577/api/profile/deployers"
    },
    "search" : {
      "href" : "http://localhost:7577/api/deployers/search"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
Response fields
Path Type Description

page

Object

Pagination properties

page.size

Number

The size of the page being returned

page.totalElements

Number

Total elements available for pagination

page.totalPages

Number

Total amount of pages

page.number

Number

Page number of the page returned (zero-based)

_embedded.deployers

Array

Array containing Deployer objects

_embedded.deployers[].name

String

Name of the deployer

_embedded.deployers[].type

String

Type of the deployer (e.g. 'local')

_embedded.deployers[].description

String

Description providing some deployer properties

19.15. Releases

19.15.1. Retrieving a list of releases

A GET request will return a paginated list for all Spring Cloud Skipper releases.

Request structure
GET /api/releases?page=0&size=10 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/releases?page=0&size=10' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 439

{
  "_embedded" : {
    "releases" : [ ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/releases{&sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:7577/api/profile/releases"
    },
    "search" : {
      "href" : "http://localhost:7577/api/releases/search"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}
Response fields
Path Type Description

page

Object

Pagination properties

page.size

Number

The size of the page being returned

page.totalElements

Number

Total elements available for pagination

page.totalPages

Number

Total amount of pages

page.number

Number

Page number of the page returned (zero-based)

_embedded.releases

Array

Provides a list of releases

19.16. Package Metadata

19.16.1. Retrieving a list of package metadata

A GET request will return a paginated list for all Spring Cloud Skipper package metadata.

Request structure
GET /api/packageMetadata?page=0&size=10 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/packageMetadata?page=0&size=10' -i
Response structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 8320

{
  "_embedded" : {
    "packageMetadata" : [ {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/1"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/1{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/1"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "1.1.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/2"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/2{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/2"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log",
      "version" : "2.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The log sink uses the application logger to output the data for inspection.",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/3"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/3{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/3"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "time",
      "version" : "2.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/time/tree/v1.2.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "time, source",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "The time source periodically emits a timestamp string.",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/4"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/4{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/4"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "ticktock",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://example.com/dataflow/ticktock",
      "packageHomeUrl" : "http://example.com/dataflow/ticktock",
      "tags" : "stream, time, log",
      "maintainer" : "https://github.com/markpollack",
      "description" : "The ticktock stream sends a time stamp and logs the value.",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/5"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/5{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/5"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log-docker",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.1.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "Docker version of the log sink application",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/6"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/6{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/6"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "log-docker",
      "version" : "2.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "logging, sink",
      "maintainer" : "https://github.com/sobychacko",
      "description" : "Docker version of the log sink application",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/7"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/7{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/7"
        }
      }
    }, {
      "apiVersion" : "skipper.spring.io/v1",
      "origin" : "samples-package-repository",
      "repositoryId" : 1,
      "kind" : "SkipperPackageMetadata",
      "name" : "helloworld-docker",
      "version" : "1.0.0",
      "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.1.0.RELEASE",
      "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
      "tags" : "helloworld",
      "maintainer" : "https://github.com/markpollack",
      "description" : "The hello world app says hello.",
      "sha256" : null,
      "iconUrl" : null,
      "_links" : {
        "self" : {
          "href" : "http://localhost:7577/api/packageMetadata/8"
        },
        "packageMetadata" : {
          "href" : "http://localhost:7577/api/packageMetadata/8{?projection}",
          "templated" : true
        },
        "install" : {
          "href" : "http://localhost:7577/api/install/8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/packageMetadata{&sort,projection}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:7577/api/profile/packageMetadata"
    },
    "search" : {
      "href" : "http://localhost:7577/api/packageMetadata/search"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 8,
    "totalPages" : 1,
    "number" : 0
  }
}
Response fields
Path Type Description

page

Object

Pagination properties

page.size

Number

The size of the page being returned

page.totalElements

Number

Total elements available for pagination

page.totalPages

Number

Total amount of pages

page.number

Number

Page number of the page returned (zero-based)

_embedded.packageMetadata

Array

Contains a collection of Package Metadata items

_embedded.packageMetadata[].apiVersion

String

The Package Index spec version this file is based on

_embedded.packageMetadata[].origin

String

Indicates the origin of the repository (free form text)

_embedded.packageMetadata[].repositoryId

Number

The repository ID this Package Index file belongs to

_embedded.packageMetadata[].kind

String

What type of package system is being used

_embedded.packageMetadata[].name

String

The name of the package

_embedded.packageMetadata[].version

String

The version of the package

_embedded.packageMetadata[].packageSourceUrl

String

Location to source code for this package

_embedded.packageMetadata[].packageHomeUrl

String

The home page of the package

_embedded.packageMetadata[].tags

String

A comma separated list of tags to use for searching

_embedded.packageMetadata[].maintainer

String

Who is maintaining this package

_embedded.packageMetadata[].description

String

Brief description of the package

_embedded.packageMetadata[].sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

_embedded.packageMetadata[].iconUrl

Null

Url location of a icon

19.16.2. Package metadata details

A GET request will return details of a package using the id of the package.

Request structure
GET /api/packageMetadata/1 HTTP/1.1
Host: localhost:7577
Example request
$ curl 'http://localhost:7577/api/packageMetadata/1' -i
Response structure
HTTP/1.1 200 OK
ETag: "1"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 892

{
  "apiVersion" : "skipper.spring.io/v1",
  "origin" : "samples-package-repository",
  "repositoryId" : 1,
  "kind" : "SkipperPackageMetadata",
  "name" : "log",
  "version" : "1.0.0",
  "packageSourceUrl" : "https://github.com/spring-cloud-stream-app-starters/log/tree/v1.2.0.RC1",
  "packageHomeUrl" : "http://cloud.spring.io/spring-cloud-stream-app-starters/",
  "tags" : "logging, sink",
  "maintainer" : "https://github.com/sobychacko",
  "description" : "The log sink uses the application logger to output the data for inspection.",
  "sha256" : null,
  "iconUrl" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:7577/api/packageMetadata/1"
    },
    "packageMetadata" : {
      "href" : "http://localhost:7577/api/packageMetadata/1{?projection}",
      "templated" : true
    },
    "install" : {
      "href" : "http://localhost:7577/api/install/1"
    }
  }
}
Response fields
Path Type Description

apiVersion

String

The Package Index spec version this file is based on

origin

String

Indicates the origin of the repository (free form text)

repositoryId

Number

The repository ID this Package Index file belongs to

kind

String

What type of package system is being used

name

String

The name of the package

version

String

The version of the package

packageSourceUrl

String

Location to source code for this package

packageHomeUrl

String

The home page of the package

tags

String

A comma separated list of tags to use for searching

maintainer

String

Who is maintaining this package

description

String

Brief description of the package

sha256

Null

Hash of package binary that will be downloaded using SHA256 hash algorithm

iconUrl

Null

Url location of a icon

Appendices

Appendix A: Building

To build the source you will need to install JDK 1.8.

The build uses the Maven wrapper so you don’t have to install a specific version of Maven.

The main build command is

$ ./mvnw clean install

To create the executables and avoid running the tests and generating JavaDocs, use the command

$./mvnw clean package -DskipTests -Dmaven.javadoc.skip=true
You can also install Maven (>=3.3.3) yourself and run the mvn command in place of ./mvnw in the examples below. If you do that you also might need to add -P spring if your local Maven settings do not contain repository declarations for spring pre-release artifacts.
Be aware that you might need to increase the amount of memory available to Maven by setting a MAVEN_OPTS environment variable with a value like -Xmx512m -XX:MaxPermSize=128m. We try to cover this in the .mvn configuration, so if you find you have to do it to make a build succeed, please raise a ticket to get the settings added to source control.

A.1. Documentation

To generate just the REST Docs documentation, use the command

./mvnw test -pl spring-cloud-skipper-server-core -Dtest=*Documentation*

To build the asciidoctor documentation only, use the command

./mvnw package -DskipTests -Pfull -pl spring-cloud-skipper-docs

A.2. Importing into eclipse

You can generate eclipse project metadata using the following command:

$ ./mvnw eclipse:eclipse

The generated eclipse projects can be imported by selecting import existing projects from the file menu.

Appendix B: Contributing

Spring Cloud is released under the non-restrictive Apache 2.0 license, and follows a very standard Github development process, using Github tracker for issues and merging pull requests into master. If you want to contribute even something trivial please do not hesitate, but follow the guidelines below.

B.1. Sign the Contributor License Agreement

Before we accept a non-trivial patch or pull request we will need you to sign the contributor’s agreement. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests.

B.2. Code Conventions and Housekeeping

None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.

  • Use the Spring Framework code format conventions. Follow these instructions for setting up the eclipse formatter in eclipse or IntelliJ. Note that checkstyle is enabled in the build.

  • Make sure all new .java files to have a simple Javadoc class comment with at least an @author tag identifying you, and preferably at least a paragraph on what the class is for.

  • Add the ASF license header comment to all new .java files (copy from existing files in the project)

  • Add yourself as an @author to the .java files that you modify substantially (more than cosmetic changes).

  • Add some Javadocs and, if you change the namespace, some XSD doc elements.

  • A few unit tests would help a lot as well — someone has to do it.

  • If no-one else is using your branch, please rebase it against the current master (or other target branch in the main project).

  • When writing a commit message please follow these conventions, if you are fixing an existing issue please add Fixes gh-XXXX at the end of the commit message (where XXXX is the issue number).