Repos moved

This repository is not longer active and has been moved to https://github.com/syndesisio/syndesis (code & issues)

Syndesis OpenShift Templates

This repository is about the canonical way to install Syndesis by using OpenShift templates for deploying on an OpenShift cluster.

There exist different flavours of OpenShift templates, with the following characteristics:

More about the differences can be found in this issue

In order to apply the templates you can directly refer to the given files via its GitHub URL:

$ oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/syndesis.yml

All of these templates are generated from a single source syndesis.yml.mustache. So instead of editing individual descriptors you have to change this master template and then run generator/run.sh.

Template parameters

All template parameters are required. Most of them have sane defaults, but some of them have not. These must be provided during instantiation with oc new-app

Required input parametes

In order to one of the templates described above these parameters must be provided:

$ oc new-app syndesis -p \
       ROUTE_HOSTNAME=<external hostname>

Replace <external hostname> with a value that will resolve to the address of the OpenShift router.

You have to chose an address or <external hostname> which is routable on your system (and also resolvable from inside your cluster). For a development setup you can use an external DNS resolving service like xip.io or nip.io: Assuming that your OpenShift cluster is reachable under the IP address ip then use syndesis.ip.nip.io.) (e.g. syndesis.127.0.0.1.nip.io if your cluster is listening on localhost). With minishift you can retrieve the IP of the cluster with minishift ip.

Once all pods are started up, you should be able to access the Syndesis at https://<external hostname>/.

Parameters with default values

Running as a Cluster Admin

You can use either Minishift or oc cluster up to setup your OpenShift system. For Minishift specific instructions see below.

Once they are started and you have logged in with oc login -u system:admin, run:

$ oc create -n openshift -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/syndesis.yml
$ oc new-project syndesis
# Create app with the required params
$ oc new-app syndesis -p ROUTE_HOSTNAME=syndesis.127.0.0.1.nip.io
# Wait until all started
$ oc get pods -w

If you want to use the development version which refers directly to Docker images substitute syndesis with syndesis-dev in the example above.

Once everything is running, you should be able to access Syndesis at https://syndesis.127.0.0.1.nip.io and log in with the OpenShift user developer using any password.

Running in a Restricted environment

If you don't have cluster admin privileges, then you can run the Syndesis as a single tenant deployment which only needs admin role in a project. This restricts all access to the single project and as such acts as a single tenant. The drawback to this is of course that you need to deploy the Syndesis services and pods into every project that you want to provision integrations in, but this is fine for a single, local deployment.

Deployment is a bit more complicated because it requires a few extra steps to set stuff up:

(Optional) Create a project

It is advisable to run the Syndesis in its own project so that it can adhere to cluster quotas:

$ oc new-project syndesis-restricted

Create service account to use as OAuth client

OpenShift includes the ability for a service account to act as a limited OAuthClient (see here for more details). Let's create the service account with the correct redirect URIs enabled:

$ oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/support/serviceaccount-as-oauthclient-restricted.yml

Create the template to use

We will create the template in the project, rather than in the openshift namespace as it is assumed the user does not have cluster-admin rights:

$ oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/syndesis-dev-restricted.yml

Create the new app

You can now use the template and the ServiceAccount created above to deploy the restricted Syndesis for a single tenant Syndesis:

$ oc new-app syndesis-dev-restricted \
    -p ROUTE_HOSTNAME=<EXTERNAL_HOSTNAME> \
    -p OPENSHIFT_MASTER=$(oc whoami --show-server) \
    -p OPENSHIFT_PROJECT=$(oc project -q) \
    -p OPENSHIFT_OAUTH_CLIENT_SECRET=$(oc sa get-token syndesis-oauth-client) \
    -p INSECURE_SKIP_VERIFY=true

Replace EXTERNAL_HOSTNAME appropriately with your public Syndesis address (something like syndesis.127.0.0.1.nip.io works great if you are using oc cluster up locally).

Log in

You should be able to log in at https://<EXTERNAL_HOSTNAME>.

Minishift Quickstart

With Minishift you can easily try out Syndesis.

Template selection

The template to use in the installation instructions depend on your use case:

• Developer : Use the template syndesis-dev or syndesis-dev-restricted which directly references Docker images without image streams. The restricted variant should be used when running in an OpenShift environment where you don't have or don't want to use admin access. Then when before building you images e.g. with mvn fabric8:build set your DOCKER_HOST envvar to use the Minishift Docker daemon via eval $(minishift docker-env). After you have created a new image you simply only need to kill the appropriate pod so that the new pod spinning up will use the freshly created image.

• Tester / User : In case you only want to have the latest version of Syndesis on your local Minishift installation, use the template syndesis which uses image stream refering to the published Docker Hub images. Minishift will update its images and trigger a redeployment when the images at Docker Hub changes. Therefore it checks every 15 minutes for a change image. You do not have to do anything to get your application updated except for waiting on Minishift to pick up new images.

Depending on your role please use the appropriate template in the instructions below.

Install instructions

Here are step-by-step the installation instructions for setting up a Minishift installation in an restricted OpenShift environment:

# Fire up minishift if not alread running.
# 4 MB of memories are recommended
minishift start --memory 4192

# Add a serviceaccount as OAuth client to OpenShift
oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/support/serviceaccount-as-oauthclient-restricted.yml

# Install the OpenShift template
oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/syndesis-dev-restricted.yml

# Create an App. Use "syndesis-dev" or "syndesis" depending on the template
# you have installed
oc new-app syndesis-dev-restricted \
    -p ROUTE_HOSTNAME=syndesis.$(minishift ip).nip.io \
    -p OPENSHIFT_MASTER=$(oc whoami --show-server)

# Wait until all pods are running. Some pods are crashing at first, but are restarted
# so that the system will eventually converts to a stable state ;-). Especially the proxies
# need up to 5 restarts
watch oc get pods

# Open browser pointing ot the app
open https://syndesis.$(minishift ip).nip.io