GitHub - bratislava/bratiska-cli: simple command line utility for app deployment

 ____                   _     _         _                             _   _
| __ )   _ __    __ _  | |_  (_)  ___  | | __   __ _            ___  | | (_)
|  _ \  | '__|  / _` | | __| | | / __| | |/ /  / _` |  _____   / __| | | | |
| |_) | | |    | (_| | | |_  | | \__ \ |   <  | (_| | |_____| | (__  | | | |
|____/  |_|     \__,_|  \__| |_| |___/ |_|\_\  \__,_|          \___| |_| |_|

Simple deployment utility for our Bratislava projects

Installation

Installing dependencies

yarn global add bratislava/bratiska-cli@stable

Note

This utility needs linux based operating system to run properly. If you are using Windows, you can use WSL to run it.

Versions

We provide three versions of bratiska-cli:

stable - this is the stable version of bratiska-cli which is sometimes more versions behind than beta. And it is used in our CI/CD pipelines.
beta - this is the latest version of bratiska-cli which is not always stable
vX.X.X - this is the specific version of bratiska-cli which is not always stable, but it usually the latest.

To install specific version of bratiska-cli use:

yarn global add bratislava/bratiska-cli#vX.X.X

To install beta version of bratiska-cli use:

yarn global add bratislava/bratiska-cli#beta

To install stable version of bratiska-cli use:

yarn global add bratislava/bratiska-cli#stable

Prerequisites

To be able to work with this utility, you need to have a few things configured. Different commands require different accesses. How to install required tools and how to configure them is described bellow this list. This utility runs only on linux based operating systems.

`tag` command

Is the simplies command, it requires only:

installed git
correct access rights to github repository.

`build_image` command

Requires more things to be installed and configured:

installed git
installed docker
access rights to docker repository
access rights to github repository

`build_kustomize` command

Requires even more things to be installed and configured:

installed git
installed docker
installed kustomize
installed envsubst
access rights to docker repository
access rights to github repository

`deploy` command

The most complex command, requires much more things to be installed and configured:

installed git
installed docker
installed kustomize
installed envsubst
installed kubectl
access rights to docker repository
access rights to github repository
access rights to kubernetes cluster

`label` command

If you need to add label to kubernetes resources, you can use this command. It requires:

installed git
installed kubectl
access rights to kubernetes cluster

Accesses:

Docker Harbor access - can be granted here ( note
- OIADS_EMPLOYEES are included by default)
Kubernetes access - contact the IT department
Github access on github.com/bratislava - contact the IT department

Install guides

Installed git (https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
Installed kubectl (https://kubernetes.io/docs/tasks/tools/)
Installed Bratislava kubectl vsphere plugin, you need to be connected on cable or through VPN to magistrat (https://k8s.tanzu.bratislava.sk/)

Windows - copy kubectl and kubectl-vsphere to c:/windows/system32 (needed admin rights) otherwise kubectl vsphere login commands will not work

Installed kustomize (https://kubectl.docs.kubernetes.io/installation/kustomize/)
Installed docker (https://docs.docker.com/engine/install)
Installed envsubst (brew install gettext)
Kustomization files in /kubernetes folder

Required running apps:

These apps needs are running when you use bratiska-cli:

running docker
You must be signed in to our docker repository harbor.bratislava.sk. See the manual below.
```
docker login https://harbor.bratislava.sk
```
For Windows WSL use:
```
docker login harbor.bratislava.sk
```
You need to have running kubect and be signed into the Kubernetes cluster. If you have issues signing to Kubernetes, contact your administrator.

Usage

command `tag`

This is the simpliest command of bratiska-cli. We are using it for our CI/CD. It is creates a tag on the current branch and pushes it to the remote repository. Before creating the tag, it checks if the current branch is clean and if there are any untracked files, and it is pulling the newest version from the repository. Then it tries to dtermine the branch, enviroment or user to create proper tag value for some enviroments (see bellow tag values).

Add tag

To tag a version of a code you can simply run just this command. Please note that this command will create a tag locally and on remote repository. This creates a dynamic tag based on your current environment (checking it from kubernetes if authorized). See tags format bellow.

bratiska-cli tag

Specify environment

You don't have to use automatic environment, there is also option to specify env in command:

bratiska-cli tag dev

Allowed env values are dev, staging, prod.

Specify environment and tech

Maybe you would like to invoke only deployment of strapi or next so use this command:

bratiska-cli tag staging-strapi

or

bratiska-cli tag staging-next

Specify environment, tech and version

Automatically to every tag we increment last value. So if a tag is on staging-strapi1.2.2 it will be automatically incremented to staging-strapi1.2.3.

bratiska-cli tag staging-strapi

If you did some feature update, use feature flag --feature to increment feature version from staging-strapi1.2.2 to staging-strapi1.3.0

bratiska-cli tag staging-strapi --feature

And if you did major change, you can use --major flag to increment from staging-strapi1.2.2 to staging-strapi2.0.0

bratiska-cli tag staging-strapi --major

or you can specify tech by using --tech flag:

bratiska-cli tag staging --tech strapi

Specify tag value

Sometimes you need different tag value, so use --tag flag to define your custom tag:

bratiska-cli tag --tag stable

or just specify version:

bratiska-cli tag --tag v1.2.3

Tag local only

To tag only locally use --local flag:

bratiska-cli tag --local

Tag local only without pulling changes from the remote repository

To tag only locally use --local --no_pull flag:

bratiska-cli tag --local --no_pull

Delete tag value

If you need to delete tag, you can use automatic last tag delete by tech, or you can specify it. Just add --delete flag.

bratiska-cli tag --tag stable --delete

(deletes stable tag)

bratiska-cli tag dev-next --delete

(deletes last dev-next tag)

Recreate tag value

If tag is already created on different commit, you can recreate it on your current commit like:

bratiska-cli tag --tag stable --recreate

(delete old stable and create it in a current commit)

Debugging

If you have some problem, there is always option to use --debug flag to print more info.

bratiska-cli tag --tag stable --recreate --debug

or use --dry_run flag to see what will be done:

bratiska-cli tag --tag stable --recreate --dry_run

Tags format

For every environment we have different tag format:

Environment `dev`

Tags are based on format {env}-{tech}-{branch}-{commit_short}-{user_name} so it can be like: dev-next-master-4a18e16-richi

Environment `staging` and `prod`

Tags are based on format {env}-{tech}{version} so it can be like staging-next1.4.7

Versions format

Versions are done in a way:

bugfix is incrementing last digit 0.0.1
feature is incrementing middle digit 0.1.0
major is incrementing first digit 1.0.0

command `build_image`

For building images we are using command build_image. It is building image from Dockerfile in the current directory and pushing it to our docker repository.

Build image

The simplest usage is using command without any flags. It will build image from Dockerfile in the current directory and push it to our docker repository.

bratiska-cli build_image

Don't push image to the registry

If you don't want to push image to the registry, use --build_image_no_registry flag.

bratiska-cli build_image --no_push

Specify image registry

If you want to specify image registry, use --registry flag.

bratiska-cli build_image --registry harbor.example.com

Specify namespace

If you want to specify for harbor, use --namespace flag.

bratiska-cli build_image --namespace wordpress

No image registry check

CLI will tell you that image you are building is already in registry. To skip this check use --no_image_repo_check flag.

bratiska-cli build_image --no_image_repo_check

Define build time sentry

If you want to define build time sentry token, use --sentry flag.

bratiska-cli build_image --sentry 1234567890

Force rebuild an image

If you want to force rebuild an image, use --force_rebuild flag. It is needed for overriding cache and image tag.

bratiska-cli build_image --force_rebuild

Specify the tag value

If you want to specify tag for the image, use --tag flag.

bratiska-cli build_image --tag 6.2-wordpress-php-fpm8.2

Debugging

If you have some problem, there is always option to use --debug flag to print more info.

bratiska-cli build_image --force_rebuild --debug

To use beta functionality, you can use --beta flag.

bratiska-cli build_image --force_rebuild --beta

command `build_kustomize`

If you want to just build kustomize from the source /kubernetes folder you can use build_kustomize command.

Build kustomize

This commands build kustomize from the source /kubernetes folder. Please note that you need have already ready image in the registry.

bratiska-cli build_kustomize

Specify image environment

If you want to specify image environment, use:

bratiska-cli build_kustomize dev

allowed values are dev, staging and prod

Build image with custom image

If you want to build image with custom image, use --image flag. Please note that you need have already ready image in the registry.

bratiska-cli build_kustomize --image harbor.example.com/standalone/nest-prisma-template/master-4a18e16-richi

if you want to just use whatever image, then after --image flag type app package name, like nest-prisma-template

bratiska-cli build_kustomize --image app-package-name

No image registry check

CLI will tell you that image you are building is already in registry. To skip this check use --no_image_repo_check flag.

bratiska-cli build_kustomize --no_image_repo_check

Specify namespace

If you want to specify kubernetes namespace together with harbor namespace (we use it together), use --namespace flag.

bratiska-cli build_kustomize --namespace standalone

Specify deployment name

If you want to specify kubernetes deployment name, use --deployment flag.

bratiska-cli build_kustomize --deployment nest-prisma-template

Specify kustomize path

If you want to specify kustomize address path, use --kustomize flag.

bratiska-cli build_kustomize --kustomize /new_kubernetes

Define host address

If you want to define host address, use --host flag.

bratiska-cli build_kustomize --host nest-prisma-template.example.com

Debugging

If you have some problem, there is always option to use --debug flag to print more info.

bratiska-cli build_kustomize --debug

To use beta functionality, you can use --beta flag.

bratiska-cli build_kustomize --beta

command `deploy`

Before you run any of the following commands, make sure you are

logged in to harbor (see running apps above, as well as the signing to harbor section below)
logged in to correct cluster (replace <env> is one of dev, staging or prod and user.name@bratislava.sk with your credentials)

to login through Windows you need to set password export KUBECTL_VSPHERE_PASSWORD={{password}}

kubectl vsphere login --server=10.10.10.1 --insecure-skip-tls-verify --tanzu-kubernetes-cluster-name=tkg-innov-<env> -u user.name@bratislava.sk

if you are logged in to multiple clusters, make sure you are using the correct one - kubectl config use-context tkg-innov-<env>

Simple deploy

There is straightforward usage because the utility tries to obtain all values from the repo automatically, and if something is missing, it will point out.

bratiska-cli deploy

Specify deploy environment

if you want to specify image environment, use:

bratiska-cli deploy dev

allowed values are dev, staging and prod.

Also you can specify all options manually

If you need to deploy to staging or production, you need to add a special flag to the command.

```bash
bratiska-cli deploy --staging

or

bratiska-cli deploy --production

Deploy with a special image

If you have a specified image, you can deploy it.

bratiska-cli deploy --image harbor.bratislava.sk/standalone/nest-prisma-template:bratiska-cli-3f3ce4fd14c76138a081596b2987a81f18a3c747-master-untracked

Specify kustomize file or folder

If you want, you can specify the kustomize file or kustomize folder with this command:

bratiska-cli deploy --kustomize ./path/path

Dry run, without deploying to Kubernetes

If you don`t want to deploy to Kubernetes, then you can run it with a dry run flag:

bratiska-cli deploy --dry_run

Namespace

The default namespace for utility is standalone, but you can change it to other like:

bratiska-cli deploy --namespace=bratislava-monorepo

Deployment

Default deployment for the app names from project.json, but you can change it like:

bratiska-cli deploy --deployment=nest-prisma-template-super-duper

Host

Default deployment host for an app depends on deployment and environment, but you can change it like:

bratiska-cli deploy --host=starwars.bratislava.sk

Or you switch env with kubectl config use-context tkg-innov-dev

Registry

If you want to use a different registry like ghcr.io, you can change it here, but don`t forget to add new credentials.

bratiska-cli deploy --registry=ghcr.io

Staging and Production

To deploy to the stage, you need to add --staging flag, and your changes need to be committed and pushed to branch to our repository. You can`t have untracked changes.

The same applies to production, so you must use --production, and changes must be merged to master. Otherwise, you can`t update production.

bratiska-cli deploy --staging

Skip deployment check

If you are deploying some cron jobs to kubernetes, there is nothing to check if the deployment was successful, so in that case, we have this option flag you can use.

bratiska-cli deploy --skip_deployment_check

Debug

If you need to debug the deploy process, you can add the --debug option. This will save the kustomize manifest to the directory so you can inspect it. Also, it does not delete the image from docker, so you can look at it.

bratiska-cli deploy --debug

Examples

Dry run with custom image and specified folder to kustomize.

bratiska-cli deploy --dry_run --image harbor.bratislava.sk/standalone/nest-prisma-template:bratiska-cli-3f3ce4fd14c76138a081596b2987a81f18a3c747-master-untracked --kustomize ./kubernetes/base

command `label`

This command allow you to add lables to kubernetes resources. You can specify resources by name or by label selector. As secrets don't have app name labels, bratiska-cli tries to use some predefined most used secrets to try to hit correct secret for that app. Kubernetes resource with new label looks like this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nest-forms-backend-app
  namespace: standalone
  labels:
    app: nest-forms-backend
    source: nest-forms-backend
    labelkey: labelvalue

Simple add label to kubernetes app

If you want to add label to almost all resources which has a deployment like nest-prisma-template, you can use this command:

bratiska-cli label key=value

Please note that you need to be in folder where is project.json file from which we determine the name of the app. In normal run you don`t need to specify resource, because label command is taking all these resources into account:

pods
deployments
statefulsets
persistentvolumeclaims
services
endpoints
ingresses
configmaps
sealedsecrets
secrets

Add label on staging or production

Just as in other cases you can use --staging or --production flag to confirm environment. You also need to have kubectl context set to correct cluster.

bratiska-cli label key=value --staging

or

bratiska-cli label key=value --production

Specify resource which needs to be tagged

If you want to tag only one resource, you can use this command:

bratiska-cli label key=value --resources=deployments

Specify secret which needs to be tagged

If your app has some secret which was not taged from general list of secrets, you can specify it like this:

bratiska-cli label key=value --secret=database-secret

Usually secret has a name nest-prisma-template-database-secret, but you have to specify it without app name.

Here is the list of secrets which are trying to be tagged by default:

tls
database-secret
general-secret
mailgun-secret
azure-secret
internals-secret
meilisearch-secret
plugin-preview-secret
cognito-secret
magproxy-secret
scanner-secret
forms-secret
app-secret
mapbox-secret
msal-secret
ginis-secret

If secret does not exist in the namespace label command will just skip it and says that secret does not exist.

Error from server (NotFound): secrets "nest-forms-backend-mapbox-secret" not found
secret mapbox-secret does not exist. Skipping...

Add label to subset of resources

This feature is not yet fully implemented in the version 3.0.0 but if you need to add label to sub resources you can use:

bratiska-cli label key=value --recursive

Please not that this will restart the current running pods.

Automatisation

Bratiska-cli args in config.json

You can automatize the running of the utility with a configuration file, which can overwrite startup arguments. If you need to have some permanent settings on the environment, you can define a config in /kubernetes/envs/[Dev,Staging,Prod] with the name config.json. Config is overriding all options passed or automatically assessed by the bratiska-cli utility. Example of config:

Example of config.json file

{
  "host": "bratislava.sk",
  "env": "prod"
}

Environment variables for kustomize

You can extend config.json with custom environment variables for kustomize attributes. For example, you can define some settings in kustomize, which needs to be dynamic like:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${BUILD_REPOSITORY_NAME}-app
  namespace: ${NAMESPACE}
  labels:
    service: app

So ${BUILD_REPOSITORY_NAME} is env variable BUILD_REPOSITORY_NAME which you can define in config.json like here:

{
  "host": "gmb.sk",
  "envs": {
    "BUILD_REPOSITORY_NAME": "super-duper-app"
  }
}

Btw BUILD_REPOSITORY_NAME is automatically created from package.json, so there is no need to create it in config.json

Environment variables for docker next build

Sometimes you need to have different environment variables for other clusters during docker next build with bratiska. You can achieve it by creating files:

.env.bratiska-cli-build.dev .env.bratiska-cli-build.staging .env.bratiska-cli-build.prod

Which is then loaded by bratiska-cli, and all its content is copied to file .env.production.local, which is then loaded to docker and processed by next during the build. More info regarding the next envs can be found here: https://nextjs.org/docs/basic-features/environment-variables

Environment variables passed to kustomize files

BUILD_REPOSITORY_URI

Git repository uri, and if is an external image, then the value is using_external_image

BUILD_REPOSITORY_NAME

name from package.json

DEPLOYMENT_ENV

it is used in URL addresses like DEPLOYMENT_ENVbratislava.sk dev => dev. staging => staging. prod => `` (is empty)

ENV

Can have three values: dev, staging, prod

HOSTNAME

or

BRATISKA_HOSTNAME

the hostname of the app

IMAGE_TAG

complete image tag with URL and tag like harbor.bratislava.sk/municipal-police/zandaris:bratiska-cli-1.5.64-pipelines-1e6277615d3649300384a399f7cb6a8c12a0e128-master-v0.3.1

IMAGE

image part of IMAGE_TAG like harbor.bratislava.sk/municipal-police/zandaris

TAG

tag value bratiska-cli-1.5.64-pipelines-1e6277615d3649300384a399f7cb6a8c12a0e128-master-v0.3.1

GIT_TAG

value of git tag used in a deployment like dev1.47.

COMMIT

value of commit 1e6277615d3649300384a399f7cb6a8c12a0e128 and if we are using external image then value is using_external_image

NAMESPACE

Namespace where should be image deployed like standalone

IMAGE_PULL_SECRET

an Image pull secret name, which is then checked if it exists on Kubernetes like harbor-secret-dev-standalone-bratiska-cli

INTERNAL_APP_PORT

App port which is then exposed to the public like 1338

More manuals

Signing to harbor

We need to configure a harbor connection for uploading images to the registry.

Open our registry website: https://harbor.bratislava.sk
Sign in with your Azure account
Copy CLI secret from your profile. Follow the picture guide:
- Go to your profile in the right top corner:
- Click on `User Profile
- Copy CLI secret
Sign in docker with the command:

docker login https://harbor.bratislava.sk

You use your username your.name@bratislava.sk and CLI secret value 5. When you see Login Succeeded, then you are done 👏

Development

You need to pull this repo with git clone bratislava/bratiska-cli. Then you can build it with the command: yarn run build. You could test it locally with yarn run start if everything were built fine.

Release

Create tag:

git tag -a v1.3.5 -m "1.3.5 env fix"

Push tag

git push origin v1.3.5

Stay in touch

If you find some bug, please get in touch with us on GitHub or mail inovacie@bratislava.sk
Website - https://inovacie.bratislava.sk/

Name		Name	Last commit message	Last commit date
Latest commit History 297 Commits
.github		.github
dist		dist
public/readme		public/readme
src		src
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

bratislava/bratiska-cli

Folders and files

Latest commit

History

Repository files navigation

Simple deployment utility for our Bratislava projects

Installation

Note

Versions

Prerequisites

tag command

build_image command

build_kustomize command

deploy command

label command

Accesses:

Install guides

Required running apps:

Usage

command tag

Add tag

Specify environment

Specify environment and tech

Specify environment, tech and version

Specify tag value

Tag local only

Tag local only without pulling changes from the remote repository

Delete tag value

Recreate tag value

Debugging

Tags format

Environment dev

Environment staging and prod

Versions format

command build_image

Build image

Don't push image to the registry

Specify image registry

Specify namespace

No image registry check

Define build time sentry

Force rebuild an image

Specify the tag value

Debugging

command build_kustomize

Build kustomize

Specify image environment

Build image with custom image

No image registry check

Specify namespace

Specify deployment name

Specify kustomize path

Define host address

Debugging

command deploy

Simple deploy

Specify deploy environment

Also you can specify all options manually

Deploy with a special image

Specify kustomize file or folder

Dry run, without deploying to Kubernetes

Namespace

Deployment

Host

Registry

Staging and Production

Skip deployment check

Debug

Examples

command label

Simple add label to kubernetes app

Add label on staging or production

Specify resource which needs to be tagged

Specify secret which needs to be tagged

Add label to subset of resources

Automatisation

Bratiska-cli args in config.json

Environment variables for kustomize

Environment variables for docker next build

Environment variables passed to kustomize files

`tag` command

`build_image` command

`build_kustomize` command

`deploy` command

`label` command

command `tag`

Environment `dev`

Environment `staging` and `prod`

command `build_image`

command `build_kustomize`

command `deploy`

command `label`

Packages