diff --git a/README.md b/README.md index d7a4c010..604a1977 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,14 @@ This repo contains a set of three interlinked projects: - The **Prometheus Federator** is a k8s Operator that manages deploying Project Monitoring Stacks. - The **Helm Project Operator** is a generic design for a Kubernetes Operator that acts on `ProjectHelmChart` CRs. + - This project depends heavily on and expands functionality of `helm-controller`. - **Helm Locker** is a Kubernetes operator that prevents resource drift on (i.e. "locks") Kubernetes objects that are tracked by Helm 3 releases. > [!NOTE] > The last two project (helm-project-operator and helm-locker) are not intended or supported for standalone use. -For more info on _Helm Project Operator_, see the [dedicated README file](README-helm-project-operator.md). -For more info on _Helm Locker_, see the [dedicated README file](README-helm-locker.md). +For more info on _Helm Project Operator_, see the [dedicated README file](cmd/helm-project-operator/README.md). +For more info on _Helm Locker_, see the [dedicated README file](cmd/helm-locker/README.md). ## Getting Started @@ -20,18 +21,20 @@ For more information, see the [Getting Started guide](docs/prometheus-federator/ ### Branches and Releases This is the current branch strategy for `rancher/prometheus-federator`, it may change in the future. -| Branch | Tag | Rancher | -|----------------|----------|------------------------| -| `main` | `head` | `main` branch (`head`) | -| `release/v0.0` | `v0.x.x` | `v2.9.x`, `v2.8.x` | +| Branch | Tag | Rancher | +|----------------|------------------|------------------------| +| `main` (v3.x) | `head`, `v3.x.x` | `main` branch (`head`) | +| `release/v1.x` | `v1.x.x` | `v2.10.x`, `v2.9.x` | +| `release/v0.x` | `v0.x.x` | Legacy Branch | > [!NOTE] -> We are starting our new Branch strategy officially in 2.10, the prior Rancher versions will receive updates to their new versions once cleared for backporting. +> We are still adopting our new Branch strategy. Soon all Rancher Minors will have a branch targeting them. +> When a Branch for v2.x is created 2.10 will be updated to use that rather than v1.x. ## More Info -Prometheus Federator is an operator (powered by [`rancher/helm-project-operator`](README-helm-project-operator.md) and [`rancher/charts-build-scripts`](README-helm-locker.md)) that manages deploying one or more Project Monitoring Stacks composed of the following set of resources that are scoped to project namespaces: +Prometheus Federator is an operator (powered by [`rancher/helm-project-operator`](cmd/helm-project-operator/README.md) and [`rancher/charts-build-scripts`](cmd/helm-locker/README.md)) that manages deploying one or more Project Monitoring Stacks composed of the following set of resources that are scoped to project namespaces: - [Prometheus](https://prometheus.io/) (managed externally by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator)) - [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) (managed externally by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator)) - [Grafana](https://github.com/helm/charts/tree/master/stable/grafana) (deployed via an embedded Helm chart) @@ -47,12 +50,22 @@ For more information on ProjectHelmCharts and how to configure the underlying op For more information on how to configure the underlying Project Monitoring Stack, please read the [`README.md` of the underlying chart](packages/rancher-project-monitoring/charts/README.md) (`rancher-project-monitoring`). ## Developing +For more information, see the [Developing guide](docs/prometheus-federator/developing.md). ### Which branch do I make changes on? -Prometheus Federator is built and released off the contents of the `main` branch. To make a contribution, open up a PR to the `main` branch. +This depends on the component of Prometheus Federator you're seeing to modify. +Here's a good guide: -For more information, see the [Developing guide](docs/prometheus-federator/developing.md). +- Prometheus Federator directly: Target the `main` branch by default, unless change is specific to a Rancher Minor. +- Rancher Project Monitoring: + 1. Use the [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo `main` branch, + 2. After chart updated in `ob-team-charts`, update `build.yaml` version on your target branch (likely main, then backport) + +### How do I know what version of Rancher Project Monitoring is used? +There are a few options depending on where you're working. +For compiled binaries, you can use the `debug-chart` command to dump the static chart. +Or, you can check `build.yaml` on the target branch/tag you're curious about. ## Building diff --git a/README-helm-locker.md b/cmd/helm-locker/README.md similarity index 95% rename from README-helm-locker.md rename to cmd/helm-locker/README.md index 072958da..e3ea0559 100644 --- a/README-helm-locker.md +++ b/cmd/helm-locker/README.md @@ -11,7 +11,11 @@ Once created, the Helm Locker controllers will watch all resources tracked by th ## Getting Started -For more information, see the [Getting Started guide](docs/gettingstarted.md). +For more information, see the [Getting Started guide](../../docs/helm-locker/gettingstarted.md). + +> [!WARN] +> These directions are intended for development workflows/debugging. +> They are not meant for standalone usage and come with no support. ## Who needs Helm Locker? diff --git a/README-helm-project-operator.md b/cmd/helm-project-operator/README.md similarity index 75% rename from README-helm-project-operator.md rename to cmd/helm-project-operator/README.md index 80d80872..40efaadc 100644 --- a/README-helm-project-operator.md +++ b/cmd/helm-project-operator/README.md @@ -8,13 +8,18 @@ This repo contains a set of two interlinked projects: **Note: These project are not intended for standalone use.** -For more info on _Helm Locker_, see the [dedicated README file](README-helm-locker.md). +For more info on _Helm Locker_, see the [dedicated README file](../helm-locker/README.md). Helm Project Operator is intended to be implemented by a Project Operator (e.g. [`rancher/prometheus-federator`](https://github.com/rancher/prometheus-federator)) but provides a common definition for all Project Operators to use in order to support deploy specific, pre-bundled Helm charts (tied to a unique registered `spec.helmApiVersion` associated with the operator) across all project namespaces detected by this operator. ## Getting Started -For more information, see the [Getting Started guide](docs/helm-project-operator/gettingstarted.md). +For more information, see the [Getting Started guide](../../docs/helm-project-operator/gettingstarted.md). + +> [!WARN] +> These directions are intended for development workflows/debugging. +> They are not meant for standalone usage and come with no support. + ## Developing @@ -22,15 +27,15 @@ For more information, see the [Getting Started guide](docs/helm-project-operator Helm Project Operator is built and released off the contents of the `main` branch. To make a contribution, open up a PR to the `main` branch. -For more information, see the [Developing guide](docs/helm-project-operator/developing.md). +For more information, see the [Developing guide](../../docs/helm-project-operator/developing.md). ## Design -Helm Project Operator is built on top of [k3s-io/helm-controller](https://github.com/k3s-io/helm-controller) and [rancher/helm-locker](https://github.com/rancher/helm-locker). For more information on the design of the underlying components, please see the `README.md` on their respective repositories. +Helm Project Operator is built on top of [k3s-io/helm-controller](https://github.com/k3s-io/helm-controller) and [rancher/helm-locker](https://github.com/rancher/prometheus-federator/tree/main/internal/helm-locker). For more information on the design of the underlying components, please see the `README.md` on their respective repositories. For an example of how Helm Project Operator can be implemented, please see [`rancher/prometheus-federator`](https://github.com/rancher/prometheus-federator). -For more information in general, please see [docs/design.md](docs/helm-project-operator/design.md). +For more information in general, please see [docs/design.md](../../docs/helm-project-operator/design.md). ## Building diff --git a/docs/prometheus-federator/developing.md b/docs/prometheus-federator/developing.md index 04d743cf..397cd21d 100644 --- a/docs/prometheus-federator/developing.md +++ b/docs/prometheus-federator/developing.md @@ -1,68 +1,59 @@ # Developing Prometheus Federator -The Prometheus Federator repository is primarily comprised of just two things: -- A simple `main.go` that implements [Helm Project Operator](https://github.com/rancher/helm-project-operator) for the [`rancher-project-monitoring` chart](charts/rancher-project-monitoring) -- A `packages/` directory that corresponds to a [`rancher/charts-build-scripts`](https://github.com/rancher/charts-build-scripts) repository +The Prometheus Federator project is primarily composed of two components: +- The golang code that implements a [Helm Project Operator](../../cmd/helm-project-operator/README.md), and +- The charts used for `rancher-project-monitoring` which are ultimately based on `rancher-monitoring` + - This component heavily relies on [`rancher/charts-build-scripts`](https://github.com/rancher/charts-build-scripts) and mimics a smaller `rancher/charts` for O&B team. -In **most** circumstances, you will only ever have to make changes to the `packages/` directory; if you need to make changes to the underlying code of the operator that is deployed, it is likely that you intend to make this change in [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator) instead. +The golang half can be found here in this repo and the Charts half in our [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo. -## Repository Structure - -```bash -## This directory is a [`rancher/charts-build-scripts`](https://github.com/rancher/charts-build-scripts) packages directory. See below for more details. -packages/ +In **most** circumstances, you will primarily make changes to the charts half and work in [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo first. +Then, after that bump versions here in `build.yaml` and create your RC/alpha release after that. Finally, you can land that change in `rancher/charts`. -## This directory contains **auto-generated** Helm chart archives that can be used to deploy Prometheus Federator in a Kubernetes cluster in -## the cattle-monitoring-system namespace, which deploys rancher-project-monitoring (located under charts/rancher-project-monitoring) -## on seeing a ProjectHelmChart with spec.helmApiVersion: monitoring.cattle.io/v1alpha1. -## -## IMPORTANT: You should never modify the contents of this directory directly; you should always modify `packages` since that will -## overwrite the changes that are observed in this directory on running a `make charts`. -## -assets/ +When you want to make changes to Prometheus Federator directly you do not need to interact with [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo. -## This file is an **auto-generated** Helm index.yaml identifying this repository as a valid Helm repository that contains Helm charts. -## -## IMPORTANT: You should never modify the contents of this file directly; you should always modify `packages` since that will -## overwrite the changes that are observed in this directory on running a `make charts` or `make index`. -## -index.yaml +## Repository Structure -## This directory contains **auto-generated** Helm charts that can be used to deploy Prometheus Federator in a Kubernetes cluster in -## the cattle-monitoring-system namespace, which deploys rancher-project-monitoring (located under charts/rancher-project-monitoring) -## on seeing a ProjectHelmChart with spec.helmApiVersion: monitoring.cattle.io/v1alpha1. +```bash +## This directory contains the source chart for the Prometheus Federator chart. ## -## IMPORTANT: You should never modify the contents of this directory directly; you should always modify `packages` since that will -## overwrite the changes that are observed in this directory on running a `make charts`. -charts/ - - ## The main chart that deploys Prometheus Federator in the cluster. - prometheus-federator/* - - ## A chart based on https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack that deploys a Project - ## Monitoring Stack onto the cluster on seeing a valid ProjectHelmChart (which means that it is contained within a Project Registration Namespace - ## with spec.helmApiVersion set to monitoring.cattle.io/v1alpha1) - ## - ## This chart is not expected to ever be deployed standalone; it is embedded into the Prometheus Federator binary itself. - rancher-project-monitoring/* - -## This directory will contain additional docs to assist users in getting started with using Helm Project Operator. +## At build time it is used as a template to generate a 1:1 release chart to the image tag. +## If you modify the Prometheus Federator chart you should consider if it needs to be back ported from `main` to other release branches. +charts/prometheus-federator + +## This directory contains all CLI entry points of the Prometheus Federator (and internal projects) +cmd/ + ## The directory contains the helm-locker cli entrypoint used by devs. + helm-locker + ## The directory contains the helm-project-operator cli entrypoint used by devs. + helm-project-operator + ## The directory contains the prometheus-federator cli entrypoint + prometheus-federator + +## This directory will contain additional docs to assist users in getting started with using Prometheus Federator. docs/ ## This directory contains an example ProjectHelmChart that can be deployed to create an example Project Monitoring Stack ## Note: the namespace needs to be modified to be a valid Project Registration Namespace, depending on how you deployed the operator. examples/ -## This directory contains the image that is used to build rancher/helm-project-operator, which is hosted on hub.docker.com. +## This directory contains all the internal code used by Prometheus Federator +internal/ + ## The directory contains the helm-locker internal project code. + helm-locker + ## The directory contains the helm-project-operator internal project code. + helm-project-operator + +## This directory contains Dockerfile* to produce images for Prod and Dev package/ - Dockerfile + Dockerfile-helm-locker + Dockerfile-helm-project-operator + Dockerfile-prometheus-federator +``` -## The main entrypoint into Prometheus Federator that implements Helm Project Operator. -main.go +--- -## The Dockerfile used to run CI and other scripts executed by make in a Docker container (powered by https://github.com/rancher/dapper) -Dockerfile.dapper -``` +> TODO: Migrate the following content to [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo. ## Making changes to the Helm Charts (`packages/`)