Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@assafad1
assafad1 committed Nov 14, 2024
1 parent 7389afa commit f7767a3
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 70 deletions.
99 changes: 29 additions & 70 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,57 +5,60 @@
![e2e-tests](https://github.com/coralogix/coralogix-operator/actions/workflows/e2e-tests.yaml/badge.svg?style=plastic)

## Overview
The Coralogix Operator provides Kubernetes native deployment and management of Coralogix and related components. The purpose of this project is to simplify and automate the configuration of a Coralogix APIs for Kubernetes clusters.
The Coralogix Operator offers Kubernetes-native deployment and management for Coralogix,
designed to simplify and automate the configuration of Coralogix APIs through Kubernetes [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

The Coralogix operator includes, but is not limited to, the following features:
The operator integrates with Kubernetes by supporting a variety of custom resources to simplify Coralogix management, including:

Kubernetes Custom Resources: Use Kubernetes custom resources to deploy and manage
- **Custom Resources for Coralogix:** Easily deploy and manage Coralogix features, using custome resources, such as
[Alerts](https://github.com/coralogix/coralogix-operator/tree/master/config/samples/alerts),
[RecordingRuleGroupSets](https://github.com/coralogix/coralogix-operator/tree/master/config/samples/recordingrulegroupset),
[RuleGroups](https://github.com/coralogix/coralogix-operator/tree/master/config/samples/rulegroups) and related components.
[RuleGroups](https://github.com/coralogix/coralogix-operator/tree/master/config/samples/rulegroups), [OutboundWebhooks](https://github.com/coralogix/coralogix-operator/tree/master/config/samples/outboundwebhooks) and others.
For a complete list of available APIs and their details, refer to the [API documentation](https://github.com/coralogix/coralogix-operator/tree/master/docs/api.md).
- **Prometheus Operator Integration:** The Operator leverages [Prometheus Operator](https://prometheus-operator.dev/) CRDs like PrometheusRule and AlertmanagerConfig,
to simplify the transition to Coralogix by utilizing existing monitoring configurations.
For more details on this integration, see the [Prometheus Operator Integration documentation](https://github.com/coralogix/coralogix-operator/tree/master/docs/prometheus-operator-integration.md).

# Guides

- [Contributing](CONTRIBUTING.md)


## Getting Started
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).

### Running on the cluster
1. Install the CRDs into the cluster:
```sh
make install
1. Clone the operator repository and navigate to the project directory:
```
git clone https://github.com/coralogix/coralogix-operator.git
cd coralogix-operator
```

2. Add the api key and region as environment variables (or later as flags):
2. The operator assumes PrometheusRule and AlertmanagerConfig CRDs are present in the cluster.
In case they aren't, run the following command:
```sh
$ export CORALOGIX_API_KEY="<api-key>"
$ export CORALOGIX_REGION="<region>"
make install-prometheus-crds
```
For private domain the `domain` field or the environment variable `CORALOGIX_DOMAIN` have to be defined.

3. Build and push your image to the location specified by `IMG`:
2. Set the Coralogix API key and region as environment variables:
```sh
make docker-build docker-push IMG=<some-registry>/coralogix-operator:tag
$ export CORALOGIX_API_KEY="<api-key>"
$ export CORALOGIX_REGION="<region>"
```
For private domain the environment variable `CORALOGIX_DOMAIN` has to be set.

4. Deploy the controller to the cluster with the image specified by `IMG`:
3. Deploy the operator to the cluster:
```sh
make deploy IMG=<some-registry>/coralogix-operator:tag
make deploy IMG=coralogixoperator/coralogix-operator:latest
```

5. Install custom resources samples into the cluster:
4. For a custom image, build and push your image to the location specified by `IMG`:
```sh
kubectl apply -R -f config/samples/
make docker-build docker-push IMG=<some-registry>/coralogix-operator:tag
```
Then, use this image to deploy the operator to the cluster, as described in step 3.

### Uninstall CRDs
To delete the CRDs from the cluster:

5. Verify that the operator pod is running:
```sh
make uninstall
kubectl get pods -n coralogix-operator-system
```

### Undeploy controller
Expand All @@ -69,50 +72,6 @@ make undeploy
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md)

### How it works
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)

This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
which provides a reconcile function responsible for synchronizing resources untile the Desired state is reached on the cluster

### Test It Out
1. Install the CRDs into the cluster:

```sh
make install
```

2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):

```sh
make run
```

**NOTE:** You can also run this in one step by running: `make install run`

### Modifying the API definitions
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:

```sh
make manifests
```

**NOTE:** Run `make --help` for more information on all potential `make` targets

More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)

## License

Copyright 2023.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

which provides a reconcile function responsible for synchronizing resources until the Desired state is reached on the cluster.
43 changes: 43 additions & 0 deletions docs/prometheus-integration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
## Prometheus Integration

The Coralogix Operator integrates with [Prometheus Operator](https://prometheus-operator.dev/) CRDs, like PrometheusRule and AlertmanagerConfig,
ensuring the smoothest possible integration from existing monitoring setups.
The operator watches for PrometheusRule and AlertmanagerConfig resources and based on their configuration
creates Coralogix custom resources in the cluster, such as Metric Alerts, RecordingRuleGroupSets and OutboundWebhooks.

### PrometheusRule Integration
- **Alerts:** Prometheus alerts can be used to create Coralogix Metric Alerts.
In order to have PrometheusRule's alerts watched by the operator, add the following annotation to the PrometheusRule:
```yaml
app.coralogix.com/track-alerting-rules: "true"
```
The operator will create a Coralogix Metric Alert for each alert in the PrometheusRule.
**Note:** Only certain Coralogix Metric Alert features can be configured in a Prometheus alert, since the Prometheus' alerting system is less comprehensive than Coralogix's.
In order to enjoy the full capabilities of Coralogix Metric Alerts, it is recommended to use this integration for a quick start,
and afterwards to manage the alerts directly from the Coralogix Alert custom resource.
The operator will not overwrite Coralogix Alert properties that are not supported in Prometheus alerts.
- **Recording Rules:** Prometheus recording rules can be used to create Coralogix RecordingRuleGroupSets.
In order to have PrometheusRule's recording rules watched by the operator, add the following annotation to the PrometheusRule:
```yaml
app.coralogix.com/track-recording-rules: "true"
```
The operator will create a Coralogix RecordingRuleGroupSet containing the recording rules, for each group in the PrometheusRule.
### AlertmanagerConfig Integration
- **Receivers:** AlertmanagerConfig's receivers can be used to create Coralogix OutboundWebhooks.
In order to have AlertmanagerConfig's receivers watched by the operator, add the following annotation to the AlertmanagerConfig:
```yaml
app.coralogix.com/track-alertmanager-config: "true"
```
The operator will create a Coralogix OutboundWebhook for each receiver in the AlertmanagerConfig.
### Combine PrometheusRule and AlertmanagerConfig configurations
The operator can link OutboundWebhooks that were created from an AlertmanagerConfig to Metric Alerts that were created from a PrometheusRule,
based on the routes defined in the AlertmanagerConfig.
Those routes are used by the operator to add Notification Groups to the Alerts, containing the OutboundWebhook.
In order to use this functionality, add the following annotation to the PrometheusRule:
```yaml
app.coralogix.com/managed-by-alertmanger-config: "true"
```

0 comments on commit f7767a3

Please sign in to comment.