fabric8-launcher / launcher-application

The fabric8-launcher application
https://developers.redhat.com/launch/
Apache License 2.0
18 stars 53 forks source link
github-client keycloak-client openshift-client quarkus

Fabric8-Launcher Application

Dependabot Status Project Chat

This is a Quarkus application exposing a Web front-end and several JAX-RS endpoints to handle launching of application into Openshift. This application collects from an end user the information needed to generate a Zip file containing a project populated for any runtime (see https://github.com/fabric8-launcher/launcher-booster-catalog for the full list).

The OpenAPI 3.0 descriptor for these services is available at https://editor.swagger.io/?url=https://forge.api.openshift.io/openapi

How to install

If you want to install a stable release of the Launcher in your OpenSHift environment read the instructions here.

The rest of the README is for those wanting to build from source and/or contribute.

Chat

We're in ZulipChat! Join us now at https://launcher.zulipchat.com/

Contributions

Contributions are welcome!

Please read the Contributing Guide to help you make a great contribution.

Setting up the environment

You can source, or use as an example, the environment script template located there: ./launcher-env-template.sh

$ source ./launcher-env-template.sh

You can select the development mode to use by setting the LAUTH environemnt variable to either TOKEN (the default), OAUTH or KEYCLOAK before sourcing the script.

KeyCloak adds authentication to the Launcher and secures services with minimum fuss. No need to deal with storing users or authenticating users. It's all available out of the box. For development only, you can choose to work without KeyCloak by changing the option in the environment script. If you are not using KeyCloak, you can find information on how to setup your git providers default credentials.

IDE Setup

Build and Run the Application

Build and Run the Unit Tests

Build and Run the Unit and Integration Tests

Reindex the booster catalog

Run the following command, replace TOKEN with the value defined in the environment variable LAUNCHER_BACKEND_CATALOG_REINDEX_TOKEN. Doesn't need to be specified if the environment variable doesn't exist in the running environment:

    $ curl -v -H "Content-Type: application/json" -d '{}' -X POST  https://localhost:8180/api/booster-catalog/reindex\?token\=TOKEN

Setup git providers default credentials (TOKEN mode)

GitHub

GitLab

BitBucket

Gitea

Launcher accesses Gitea using the Sudo feature, so make sure that the user referenced in the Authorization HTTP Header also exists in the Gitea server

Environment Description
LAUNCHER_GIT_PROVIDER The default Git provider to use, should be Gitea
LAUNCHER_MISSIONCONTROL_GITEA_URL The URL where the Gitea server is running
LAUNCHER_MISSIONCONTROL_GITEA_USERNAME The admin username
LAUNCHER_MISSIONCONTROL_GITEA_TOKEN The admin access token

Setup using OAuth (OAUTH mode)

You can set the proper environment variables for local development with OAuth like this:

$ LAUTH=OAUTH source ./launcher-env-template.sh

But you also need to add an OAuthClient to your OpenShift cluster. You can run the following command while being logged in with a user that has cluster admin rights:

$ cat <<EOF | oc create -f -
kind: OAuthClient
apiVersion: oauth.openshift.io/v1
metadata:
  name: launcher
secret: my-secret-password
redirectURIs:
  - "http://localhost:8080"
grantMethod: prompt
EOF

And depending on the Git provider you're using you'll also have to follow the steps in one of the following sections:

GitHub

Create an OAuth App named "launcher" and set the Authorization callback URL to the (base) URL of the Launcher frontend. If you're testing locally this would be http://localhost:8080/launch for example.

Then copy the Client ID and Client Secret values to their corresponding fields in the GitHub section of the git-providers.yml file.

GitLab

Create an OAuth App named "launcher", mark "Confidential" and "api" and set the Callback URL to the (base) URL of the Launcher frontend. If you're testing locally this would be http://localhost:8080/launch for example.

Then copy the Client ID and Client Secret values to their corresponding fields in the GitLab section of the git-providers.yml file. Also copy the Callback URL to the clientProperties / redirectUri.

Filtering the booster catalog

This feature can be activated by providing the LAUNCHER_BOOSTER_CATALOG_FILTER env param/system property The script must evaluate to a boolean using the booster variable, that is an instance of RhoarBooster.

    $ export LAUNCHER_BOOSTER_CATALOG_FILTER=booster.mission.id === 'rest-http'

Examples:

Multi-tenant (User impersonation)

In a single multi-tenant cluster, the Keycloak used to authenticate in Launcher may be the same as the one used in OpenShift. In this case, Launcher shouldn't require Keycloak to be configured with OpenShift as an identity provider. Launcher supports that using a ServiceAccount with user impersonation.

More info in https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation

Here are the steps to configure:

1) Create an impersonator cluster role as described below (it can be any name, as long as it contains the impersonate verb):

```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: impersonator
rules:
- apiGroups: [""]
  resources: ["users", "groups", "serviceaccounts"]
  verbs: ["impersonate"]
```

2) Create a ServiceAccount in the cluster with the impersonator cluster role 3) Set the LAUNCHER_MISSIONCONTROL_OPENSHIFT_TOKEN env in the launcher-backend pointing to the token corresponding to the ServiceAccount created in step 2 4) Set the LAUNCHER_MISSIONCONTROL_OPENSHIFT_IMPERSONATE_USER env var to true meaning that launcher will impersonate the current logged user from the ServiceAccount created in step 2 when connecting to OpenShift

Code of Conduct

Please adopt our Code of Conduct to follow our community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse.