github.com/freiheit-com/kuberpult@v1.24.2-0.20240328135542-315d5630abe6/README.md (about) 1 ![Main Pipeline](https://github.com/freiheit-com/kuberpult/actions/workflows/execution-plan-main.yml/badge.svg) 2 ![Release Pipeline](https://github.com/freiheit-com/kuberpult/actions/workflows/release.yml/badge.svg) 3 4 5 # Kuberpult Readme for users 6 7 ## Etymology 8 9 Kuberpult is a catapult for [kubernetes](https://kubernetes.io/) :) it catapults the containers of microservices to different stages in kubernetes clusters. 10 11 ## About 12 13 **Kuberpult** helps you manage different versions of different microservices in different cluster. 14 While [Argo CD](https://argo-cd.readthedocs.io/en/stable) applies the *current* version of your services in clusters, 15 Kuberpult also helps you with managing what is deployed *next*. 16 17 ## Purpose 18 The purpose of Kuberpult is to help roll out quickly yet organized. 19 We use it for requirements like this: 20 * We have 3 clusters, development, staging, production 21 * Any merged changes should instantly be deployed to development. 22 * After running some test on development, roll out to staging. 23 * Once a day we trigger a release train that deploys everything to production - using the versions of staging as source. 24 * Sometimes we want to prevent certain deployments, either of single services, or of entire clusters. 25 * We never want to deploy (to production) between 9am and 11am as these are peak business hours. 26 27 28 ## Kuberpult Design Principles 29 30 We use these principles to decide what features to focus on. We may deviate a little, but in general 31 we don't want features in kuberpult that violate these points: 32 33 * **Automatic and regular deployments**: Kuberpult is built for teams who want to deploy often (e.g. daily) and setup automated processes for the deployments. 34 * **All power to the engineers**: Kuberpult never stops an engineer from deploying manually. The engineers know their services best, so they can decide which version to deploy. 35 * **Microservices**: Kuberpult is built on the assumption that our teams work with kubernetes microservices. 36 * **Monorepo**: Kuberpult is built for a monorepo setup. One product should be one monorepo. If you have multiple products, consider giving each one a kuberpult instance. 37 38 39 ## API 40 Kuberpult has an API that is intended to be used in CI/CD (GitHub Actions, Azure Pipelines, etc.) to release new versions of one (or more) microservices. 41 The API can also roll out many services at the same time via "release trains". It also supports rolling out some groups of services. 42 43 # Argo CD 44 Kuberpult works best with [Argo CD](https://argo-cd.readthedocs.io/en/stable/) which applies the 45 manifests to your clusters and Kuberpult helps you to manage those manifests in the repository. 46 47 `Kuberpult` does not actually `deploy`. That part is usually handled by Argo CD. 48 49 # App Locks & Environment Locks 50 `Kuberpult` can handle *locks* in its UI. When something is locked, it's version will not be changed via the API. 51 Both *environments* and *microservices* can be `locked`. 52 53 ## Public releases of Kuberpult 54 55 ### Docker Registries 56 Kuberpult's docker images are currently available in 2 docker registries: (Example with version 0.4.55) 57 * `docker pull europe-west3-docker.pkg.dev/fdc-public-docker-registry/kuberpult/kuberpult-frontend-service:0.4.55` ([Link for Kuberpult devs](https://console.cloud.google.com/artifacts/docker/fdc-public-docker-registry/europe-west3/kuberpult/kuberpult-frontend-service)) 58 * `docker pull ghcr.io/freiheit-com/kuberpult/kuberpult-frontend-service:0.4.55` ([Link for Kuberpult devs](https://github.com/freiheit-com/kuberpult/pkgs/container/kuberpult%2Fkuberpult-frontend-service)) 59 And the same applies for the `kuberpult-cd-service` - just replace "frontend" by "cd". 60 61 We may deprecate one of the registries in the future for simplicity. 62 63 If you're using Kuberpult's helm chart, generally you don't have to worry about that. 64 65 ### GitHub Releases 66 67 To use the helm chart, you can use [this url](https://github.com/freiheit-com/kuberpult/releases/download/0.4.55/kuberpult-0.4.55.tgz) (replace both versions with the current version!). 68 You can see all releases on the [Releases page on GitHub](https://github.com/freiheit-com/kuberpult/releases) 69 70 #### Helm Chart 71 See [values.yaml.tpl](https://github.com/freiheit-com/kuberpult/blob/main/charts/kuberpult/values.yaml.tpl) for details like default values. 72 73 Most important helm chart parameters are: 74 * `git.url`: **required** - The url of the git manifest repository. This is a shared repo between Kuberpult and Argo CD. 75 * `git.branch`: **recommended** - Branch name of the git repo. Must be the same one that Argo CD uses. 76 * `ssh.identity`: **required** - The ssh private key to access the git manifest repo. 77 * `ssh.known_hosts`: - The ssh key fingerprints of for your git provider (e.g. [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints)) 78 * `pgp.keyring`: **recommended** - Additional security. Highly recommended if you do not us IAP. If enabled, calls to the REST API need to provide signatures with each call. See [create-release](https://github.com/freiheit-com/kuberpult/blob/main/infrastructure/scripts/create-testdata/create-release.sh) for an example. 79 * `ingress.create`: **recommended** - If you want to use your own ingress, set to false. 80 * `ingress.iap`: **recommended** - We recommend to use IAP, but note that this a GCP-only feature. 81 * `datadogTracing`: **recommended** - We recommend using Datadog for tracing. Requires the [Datadog daemons to run on the cluster](https://docs.datadoghq.com/containers/kubernetes/installation/?tab=operator). 82 * `dogstatsdMetrics`: **optional** - As of now Kuberpult sends very limited metrics to Datadog, so this is optional. 83 * `auth.aureAuth.enabled`: **recommended** - Enable this on Azure to limit who can use Kuberpult. Alternative to IAP. Requires an Azure "App" to be set up. 84 85 ## Releasing a new version 86 See [endpoint-release](./docs/endpoint-release.md) 87 88 ## Release Train Overview 89 See [release train](./docs/release-train.md) 90 91 #### Environment Config 92 See [environment](./docs/environment.md) 93 94 95 ## Best practices 96 97 ### Remove individual environments from a service 98 See [Remove Env From Service](./docs/remove-env-from-service.md) 99 100 ### Remove a service entirely 101 See [Remove Service Entirely](./docs/remove-service.md) 102