diff --git a/README.md b/README.md index 094f4f52c53e7f0e1546938f52c29f5a84d02be5..5ade9886c5bf01cc1671687f7a638bb790fd8d94 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,3 @@ -# Kubernetes base - -This repository contains all gitlab-ci include files: - -- `node-kubernetes`: include for node, nextjs and nestjs apps -- `meteor-kubernetes`: include for meteor apps -- `panter-kubernetes-base`: use this for anything else that has not yet an include (java, rails) - -## Troubleshoot - -[troubleshoot](./Troubleshoot.md) - - - -## Usage - -``` -# on top of your gitlab-ci.yml - -include: - - project: gitlab-ci/kubernetes-base - ref: v6 - file: <include to use> - -``` - -E.g for node apps: - -``` -include: - - project: gitlab-ci/kubernetes-base - ref: v6 - file: node-kubernetes.yml - -``` - -We recommend to use a certain version as ref. Without a ref, it will always take master (latest) which might break your builds. - -You need to provide the following variables in your gitlab-ci.yml: - -``` -variables: - CUSTOMER_NAME: pan - APP_NAME: awesomeapp - CLUSTER_NAME: production - COMPONENT_NAME: web # optional, if you want to have multiple services/apps into the same namespace, this needs to be different - CHART_NAME: panter-charts/manulstack # path to a panter-charts helm chart or local path (/chart) - APP_DIR: . # path where your app leaves (package.json) relative to the git-root - REPLICAS: '3' # how many pods to launch (only on prod. review and stage have always 1) -``` - -## General Features - -This includes defines the following: - -- test, app-build and docker-build -- deploys to kubernetes -- deploys to review environment on every branch (review apps, one per Branch) -- deploys to dev environment on every master commit -- you can trigger a `semantic-release` manually, which will tag the repository and deploys to prod or stage environment. -- you can manually deploy to prod from stage - -### release handling - -You can create a release manually on the repository, which does a `semantic-release`, creates a changelog, bumps the version number and tags the repository. For this to work **_your commits need to follow semantic versionsing_**: `fix(scope): nasty bug` or `feat(scope): new fancy feature`. - -After the repository got tagged, a deploy to prod or stage is done (depending on whether staging is enabled, see below). - -In the pipeline, click on "create-release" to create a release tag and trigger therefore a new release. - -### hotfixing older release - -You might come accross the situatio where you have a tagged version that is about to get released, -but its still getting tested by the customer on staging. - -Now, a wild bug occures and you have to fix that on production! - -With the normal workflow you would need to fix that, merge it into master and trigger a normal release. -But this will release everything that is on stage right now! - -To avoid this, you can do this hotfix flow, which follows [this recipe](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/maintenance-releases.md): - -Let's assume your current "good" version on prod is `v2.4.3` -It's important that this version is the latest `patch` version so (v2.4.4 does not exist). This is usually in praxis, as you want to release bugfixes as soon as possible usually. -So we want to have a new patched version 2.4.4 that will be our new prod : - -- create a branch for the hotfix: `git checkout -b 2.4.x v2.4.3 -- do your fixes and commit with a `fix:` commit: `fix: very important bug to hotfix` -- push this branch to gitlab -- this will now trigger a special pipeline where you have your usuall lint/test/build and review deploy. -- Additionaly this pipeline contains a "create-release"-step. Run this job to create the new hotfix release 2.4.4. -- this will in turn run a pipeline that let's you deploy it to prod and stage. its not done automatically. Chose the right destination for your hotfix. -- pull the branch again locally (if you want to have it in the changelog file) and merge it into master -- this might lead to conflicts now if the hotfix no longer applies, but that's ok! Maybe it was already fixed in some stage feature. - -### enable staging - -if you set `STAGING_ENABLED: "true"` in your `variables`, it will deploy to stage first when doing a release. You can then do the prod release manually. - -### automatically release - -if you set AUTO_RELEASE: "true", commits on master automatically creates a release and therefore deploy to prod. This is good for continues deployment. - -Note: If you also set STAGING_ENABLED: "true", the automatic release will deploy to stage, so you have to deploy to prod manually. - -### automatic cleanup - -By default your review environment will selfdestruct after _2 weeks_ -You can not override this setting put pin the environment in the environment overview - - -## Values handling - -If your project contains a file called `values.yml` it will get passed automatically to your helm-chart. - -If your project contains `values-stage.yml` `values-review.yml` or `values-prod.yml`, this values will be used only on deployments to the corresponding environment. -These environment-specific values get merged with `values.yml`. - -### Default values: - -these values are always set: - -`application.componentName`: The value of `COMPONENT_NAME`, unless you are in a review-app. In this case, the name has a suffix describing the review-app. -This guarantees that multiple review-apps do not collide in the namespace if used correctly in your helm-chart. - -`application.hostCanonical`: A hostname for the app that is always defined. If you use our helm-charts this will guarantee that the app is always reachable with this hostname. - - -## Post deploy stages - -you can implement `verify-<env>` stages that will run after deployment. You can e.g. run test against the deployed version. - -*Cypress example*: - -``` - - -.e2ebase: - image: cypress/browsers:node12.18.3-chrome89-ff86 - extends: .cache-node-modules - script: - - yarn install --frozen-lockfile - #- yarn cypress install - - CYPRESS_BASE_URL=$CI_ENVIRONMENT_URL yarn cypress:run --browser chrome --headless - artifacts: - when: always - paths: - - cypress/videos/**/*.mp4 - - cypress/screenshots/**/*.png - expire_in: 5 day - -verify-review: - extends: - - .verify-review - - .e2ebase - -verify-dev: - extends: - - .verify-dev - - .e2ebase - - - ``` - -## Platform specific includes - -### kubernetes-node - - -``` - -include: - - project: gitlab-ci/kubernetes-base - ref: v6 - file: kubernetes-node - -``` - -this assumes the following scripts to be available: - -- `yarn build`: invoked during build stage. Should produce a build in `./dist` (or in next-app it builds in `./.next`) -- `yarn lint`: lints your app -- `yarn test`: tests your app (usually unit tests) - -This include automatically generates a Dockerfile unless you specify one. You can control the node-version by -adding a `.nvmrc` file. It will use the "alpine" version of the specified node version - - -### meteor-kubernetes - -``` - -include: - - project: gitlab-ci/kubernetes-base - ref: v6 - file: meteor-kubernetes.yml - -variables: - - # meteors specific: - MONGODB_ENABLED: 'true' # whether to create a mongobd - WORKER_ENABLED: 'false' # whether to launch an additional pod which has WORKER_ENABLED env var. usefull for cronjobs and migrations - MONGODB_REPLICAS: '3' # how many mongodb-replicas it will launch on production. other envs have always 1 - - -``` - -This works similarly to `node-kubernetes`, but adds a meteor specific dockerfile - - -### panter-kubernetes-base - -a base image that can be used for anything else. - -You can override .lint, .test, .app-build stages to specify mvn commands or similar - - - - - - - +# deprecated +see https://git.panter.ch/catladder/gitlab-ci/