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