Skip to content

plicity/plicity

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

21 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

PLICITY ๐Ÿ—

An Open Source Node.js Cloud-Operator for Development supported by consol with ๐Ÿ’›.

This project is "work in progress" ๐Ÿšง. Many features are still missing. Same for security. โš  Don't use this version in production.

plicity logo

๐Ÿค” What is it?

You and your team ๐Ÿ‘ฅ

  • โœ” is developing a web application in the โ˜ cloud?
  • โœ” use branches for parallel ๐Ÿ”ƒ feature development?

... great, maybe PLICITY can help you! ๐Ÿ‘จโ€โš•๏ธ

The idea is very simple ๐Ÿ’ก

  • ๐Ÿ” PLICITY will watch your Git repository
  • ๐Ÿ”ง every time a branch is created, it will trigger a hook
  • ๐Ÿšฎ same for deleting or updating a branch

A simple idea needs simple implementation โœŒ:

  • ๐Ÿ“ƒ the operator is Node.js script in your project
  • ๐Ÿ•ถ it will start everything and implement the hooks
  • ๐Ÿ‘Œ hooks are simple JS callbacks
operator.start({
  onCreateBranch:     setup,      // a new git branch is created
  onChangeBranchHead: startBuild, // push to a branch
  onDeleteBranch:     deleteAll,  // delete a remote branch
  onServerBuild:      startBuild  // press "Build" in the Operator UI
});

onCreateBranch

When a new git branch is created, we could oc process -f ...yml | oc apply -f - a template which will deploy everything needed for the application? It should create an ImageStream, BuildConfig, ..., maybe also a new isolated Database and of course a Route because we want to access it.

async function setup(event) {
  await oc.project(event.args.openshiftProject);
  await oc.applyTemplate(`${__dirname}/setup.yml`, {
    GITLAB_REPOSITORY_URL: event.gitlabRepositoryUrl, // needed for BuildConfig
    BRANCH_NAME_NORMALIZED: event.branchNormalized,   // needed for BuildConfig
    NAME: event.args.name // used as prefix for all resource names and labels
  });
}

onChangeBranchHead, onServerBuild

When a branch has a new commit or someone presses "Build" in the Operator UI, we simply want to start the build.

async function startBuild(event) {
  await oc.project(event.args.openshiftProject);
  await oc.startBuild(`${event.args.name}-${event.branchNormalized}`, {commit: event.commit});
}

onDeleteBranch

When a branch is deleted, we want to delete everything we set up in setup. We use labels, that we can delete everything with one command.

async function deleteAll(event) {
  await oc.project(event.args.openshiftProject);
  await oc.deleteAll(`app.plicity.io/branch=${event.args.name}-${event.branchNormalized}`);
}

Conclusion

Of course you're free to do more in the hooks, like running smoke ๐Ÿšฌ or โš™ integration tests or create ๐Ÿ“ซ notifications on your Slack channel.

You run the operator. You implement the hooks. Everything is under your control. Create your very best build pipeline for development. PLICITY will โ™ฅ to support you and your team with ๐Ÿš€ development, ๐Ÿงช testing and finally โ›ต ship faster.

Now give it a try and please give feedback ๐Ÿ˜ฌ.

Install

Before using it, please also check Security section.

The target folder has to exist and should be empty.

1. Initialize your project

npm init @plicity <target dir>

2. Commit plicity to your repository

git add -A
git commit -m 'add plicity'
git push

3. Update .env file

Go into your target directory and open /plicity/.env.

3.1 Openshift Configuration

You can get url and token by copying your login command

openshift copy login command

It should look like this:

oc login https://openshift.mycompany.org:8443 --token=abcdefghijklmnopqrstuvwxyz0123456789

Use an openshift project which is already created for your app.

PLICITY_OPENSHIFT_URL=https://openshift.mycompany.org:8443
PLICITY_OPENSHIFT_TOKEN=abcdefghijklmnopqrstuvwxyz0123456789
PLICITY_OPENSHIFT_PROJECT=plicity-test

3.2 Gitlab Configuration

Note: Gitlab project needs to be public. Also see Security section.

3.2.1 PLICITY_GITLAB_HOST

Just the Gitlab host. Not the URL to the repository.

PLICITY_GITLAB_HOST=https://gitlab.mycompany.org
3.2.2 PLICITY_GITLAB_PROJECT_ID

Go to your Gitlab Project and copy the Project ID.

gitlab project id

PLICITY_GITLAB_PROJECT_ID=1147
3.2.3 PLICITY_GITLAB_TOKEN

Go to Settings.

gitlab settings

Go to Access Tokens.

gitlab access token

Create Access Token.

gitlab create access token

PLICITY_GITLAB_TOKEN=abcdefghijklmnop

3.3 Further PLICITY configuration

3.3.1 PLICITY_NAME

Name of the Operator and used as prefix $name-... for all OpenShift resources. It has to only contain valid characters or it will crash.

PLICITY_NAME=pli
3.3.1 PLICITY_LOG_LEVEL

Just for local development of your Operator.

Valid log level according to pino logger. In OpenShift it will run info.

PLICITY_LOG_LEVEL=debug
3.3.1 PLICITY_LOG_PRETTY

Just for local development of your Operator.

Log output has json format. Make it human-readable setting this to true. In OpenShift it will output json.

PLICITY_LOG_PRETTY=true

Example

mkdir demo-app
npm init @plicity demo-app
# npx: installed 123 in 9.758s
# โœ” copied 10 files to demo-app
# โœ” install dependencies
# โœ” add scripts - write demo-app/plicity/package.json
# โ„น 1. please commit and push
# โ„น 2. update demo-app/plicity/.env
# โ„น 3. initialize openshift: `cd demo-app/plicity; npm run init`.

cd demo-app/plicity
cat .env
# PLICITY_OPENSHIFT_URL=https://openshift.mycompany.org:8443
# PLICITY_OPENSHIFT_TOKEN=abcdefghijklmnopqrstuvwxyz0123456789
# PLICITY_OPENSHIFT_PROJECT=plicity-test
# 
# PLICITY_GITLAB_HOST=https://gitlab.mycompany.org
# PLICITY_GITLAB_TOKEN=abcdefghijklmnop
# PLICITY_GITLAB_PROJECT_ID=1147
# 
# PLICITY_NAME=pli
# PLICITY_LOG_LEVEL=debug
# PLICITY_LOG_PRETTY=true

npm run init
# > [email protected] init demo-app/plicity
# > plicity init
# 
# INFO  (โ€ฆopenshift/oc.js): using KUBECONFIG /tmp/.kube/config

Check OpenShift to see Operator build.

openshift operator build

When Operator POD is up and running all branches will be deployed.

openshift operator build

Advanced Settings

If you want to use your own registry:

npm init @plicity <target dir> \
  --npm-registry=http://registry.mycompany.org \
  --npm-strict-ssl=false

Security

Good things first ๐Ÿ˜ฌ:

  • 100% On-Premise in your Private or Public Cloud.
  • No OpenShift cluster admin rights needed.
  • Your OpenShift token is not exposed. The Operator will run with a special ServiceAccount with a RoleBinding allowed to control your project. Your token is just used for the initial setup or if you want to run the Operator local, e.g. updating it.

Need of improvement ๐Ÿค:

  • Gitlab project needs to be public. Yet no authentication implemented.
  • We give full Gitlab access to the Operator. Assumption is that the only API call we need at current is to add and remove the badge to the Gitlab project. This may change when implementing authentication for OpenShift for Gitlab.
  • Your Gitlab Token is exposed as OpenShift secret. Everyone with access to your project can use that Gitlab token.

Grey zone ๐Ÿคซ:

Contribution

alphabetical order

Known Issues

  • Will not work on Windows and probably not on MacOS
  • Only OpenShift compatible with oc v3.11.0 and Gitlab supported