Skip to content

Commit

Permalink
Improved readme (#411)
Browse files Browse the repository at this point in the history
  • Loading branch information
Bharath Nallapeta authored Jan 12, 2024
1 parent d3434c7 commit d4e6587
Showing 1 changed file with 125 additions and 122 deletions.
247 changes: 125 additions & 122 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,24 @@
- [Introduction](#introduction)
- [Problem](#problem)
- [Solution](#solution)
- [Deployment Guide](#deployment-guide)
- [Features](#features)
- [Admin Guide](#admin-guide)
- [Vanilla Manifests](#vanilla-manifests)
- [Helm Charts](#helm-charts)
- [Configuration](#configuration)
- [Ingresses](#ingresses)
- [Forecastle](#forecastle)
- [Configuration](#configuration)
- [NamespaceSelector](#namespaceselector)
- [Custom Apps](#custom-apps)
- [ForecastleApp CRD](#forecastleapp-crd)
- [Automatically discover URL's from Kubernetes Resources](#automatically-discover-urls-from-kubernetes-resources)
- [Example Config](#example-configuration)
- [Features](#features)
- [Scaling with Multiple Instances](#scaling-with-multiple-instances)
- [Help](#help)
- [Talk to us on Slack](#talk-to-us-on-slack)
- [Contributing](#contributing)
- [Scaling with Multiple Instances](#scaling-with-multiple-instances)
- [User Guide](#user-guide)
- [Ingresses](#ingresses)
- [ForecastleApp CRD](#forecastleapp-crd)
- [Automatically discover URL's from Kubernetes Resources](#automatically-discover-urls-from-kubernetes-resources)
- [Developer Guide](#developer-guide)
- [Bug Reports & Feature Requests](#bug-reports--feature-requests)
- [Developing](#developing)
- [Help](#help)
- [Talk to us on Slack](#talk-to-us-on-slack)
- [Changelog](#changelog)
- [License](#license)
- [About](#about)
Expand All @@ -46,9 +46,33 @@ Forecastle provides a unified control panel, serving as a convenient gateway to

![Screenshot](assets/forecastle.png)

## Deployment Guide
## Features

Forecastle boasts a range of functionalities designed to streamline the management and accessibility of applications in Kubernetes environments. Key features include:

1. **Comprehensive App Listing**: Forecastle aggregates and displays apps from all namespaces specified in the ConfigMap, providing a centralized view of your resources.

2. **Search Functionality**: Quickly locate specific applications with an intuitive search feature, enhancing user experience and efficiency.

3. **Namespace Grouping**: Apps are neatly organized and grouped by their respective namespaces, making navigation and management more straightforward.

4. **Customizable Header**: Tailor the look and feel of your Forecastle dashboard with configurable header options, including title customization and color schemes.

5. **Support for Multiple Instances**: Forecastle is designed to support multiple instances, accommodating varied and complex deployment scenarios.

6. **Custom Apps Integration**: Easily add non-Kubernetes or external applications to your dashboard for a more comprehensive overview of your tools and resources.

7. **ForecastleApp CRD**: Utilize the ForecastleApp Custom Resource Definition to dynamically add custom applications, further enhancing the dashboard’s flexibility.

Forecastle can be seamlessly deployed on both Kubernetes and OpenShift platforms. You have the option to use either vanilla Kubernetes manifests or Helm charts for deployment. Below are the step-by-step instructions for each method.
8. **Custom Grouping and URLs**: Organize your applications into custom groups and assign specific URLs for tailored navigation and accessibility.

9. **Detailed App Information**: Each application comes with detailed information, offering insights and essential details at a glance.

## Admin Guide

This section is intended for Administrators aiming to deploy Forecastle in Kubernetes environments. Forecastle offers flexible deployment options, accommodating both Kubernetes and OpenShift platforms with ease.

You have the choice of deploying Forecastle using traditional Kubernetes manifests or through Helm charts. Detailed instructions for both methods are provided below to guide you through the deployment process.

### Vanilla Manifests

Expand All @@ -74,29 +98,10 @@ Adjust the configuration in values.yaml if required and run the following comman
helm install forecastle ./deployments/kubernetes/chart/forecastle
```

## Configuration
### Configuration

Forecastle simplifies the discovery and management of applications on Kubernetes and OpenShift. It utilizes specific annotations on ingresses and offers various configuration options for customization.

### Ingresses

Forecastle identifies applications through annotations added to Kubernetes ingresses. Here’s a guide to the necessary annotations:

To be discovered by Forecastle, add the following annotations to your ingresses:

| Annotation | Description | Required |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `forecastle.stakater.com/expose` | Add this with value `true` to the ingress of the app you want to show in Forecastle | `true` |
| `forecastle.stakater.com/icon` | Icon/Image URL of the application; An icons/logos/images collection repo [Icons](https://github.com/stakater/ForecastleIcons) | `false` |
| `forecastle.stakater.com/appName` | A custom name for your application. Use if you don't want to use name of the ingress | `false` |
| `forecastle.stakater.com/group` | A custom group name. Use if you want the application to show in a different group than the namespace it is running in | `false` |
| `forecastle.stakater.com/instance` | A comma separated list of name/s of the forecastle instance/s where you want this application to appear. Use when you have multiple forecastle dashboards | `false` |
| `forecastle.stakater.com/url` | A URL for the forecastle app (This will override the ingress URL). It MUST begin with a scheme i.e., `http://` or `https://` | `false` |
| `forecastle.stakater.com/properties` | A comma separate list of `key:value` pairs for the properties. This will appear as an expandable list for the app | `false` |
| `forecastle.stakater.com/network-restricted` | Specify whether the app is network restricted or not (true or false) | `false` |

### Forecastle

You can customize Forecastle using either a ConfigMap or the values.yaml file when deploying with Helm. Below are the configurable fields:

| Field | Description | Default | Type |
Expand Down Expand Up @@ -136,9 +141,81 @@ Allows adding non-Kubernetes or external apps to Forecastle. This is an extremel
| properties | Additional Properties of the app as a map | map[string]string |
| networkRestricted | Whether app is network restricted or not | bool |

#### ForecastleApp CRD
#### Example Configuration

Below is an example of how you might configure Forecastle using a combination of namespace selectors and custom apps:

```yaml
namespaceSelector:
labelSelector:
matchLabels:
component: redis
matchExpressions:
- {key: tier, operator: In, values: [cache]}
matchNames:
- test
title:
headerBackground:
headerForeground: "#ffffff"
instanceName: "Hello"
crdEnabled: false
customApps:
- name: Hello
icon: http://hello
url: http://helloicon
group: Test
properties:
Version: 1.0
```
This configuration demonstrates how to set namespace selectors, customize the header's appearance, enable or disable the CRD feature, and add a custom app with specific properties.
### Scaling with Multiple Instances
Forecastle's design allows for running multiple instances, providing scalability and flexibility in diverse environments. Here's how you can effectively scale Forecastle.
#### Deploying Multiple Instances
*Basic Deployment*: To run multiple Forecastle instances, deploy each instance in a separate namespace. Specify a list of namespaces for each instance to monitor ingresses.
#### Configuring Named Instances for Enhanced Flexibility
*Named Instance Configuration*: For greater control over which applications are displayed in specific instances (irrespective of their namespaces), configure each Forecastle instance with a unique name using the `instanceName` setting in the Forecastle configuration.

#### Controlling Application Display Across Instances

*Application-Specific Instance Display*: After naming your instances, use the `forecastle.stakater.com/instance` annotation on your ingresses. This annotation dictates which application appears in which Forecastle instance.

*Multiple Instance Display*: It's possible for a single application (ingress) to appear in multiple Forecastle dashboards. For instance, if you have two instances named dev-dashboard and prod-dashboard, adding `dev-dashboard,prod-dashboard` in the ingress's instance annotation will ensure the application is visible on both dashboards.

#### Helm Deployment Considerations

*Unique Naming in Helm*: When deploying Forecastle instances via Helm, ensure each instance has a unique `nameOverride` value (default is forecastle). This step is crucial to avoid conflicts between global resources like ClusterRole and ClusterRoleBinding.

With Forecastle, you can dynamically integrate applications into the dashboard using the ForecastleApp Custom Resource Definition (CRD). This feature allows for greater flexibility and decouples application configuration from both Ingresses and the Forecastle configuration.
## User Guide

This section is intended for Users aiming to use Forecastle in their Kubernetes environments.

### Ingresses

Forecastle identifies applications through annotations added to Kubernetes ingresses. Here’s how you would add the necessary annotations:

| Annotation | Description | Required |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `forecastle.stakater.com/expose` | Add this with value `true` to the ingress of the app you want to show in Forecastle | `true` |
| `forecastle.stakater.com/icon` | Icon/Image URL of the application; An icons/logos/images collection repo [Icons](https://github.com/stakater/ForecastleIcons) | `false` |
| `forecastle.stakater.com/appName` | A custom name for your application. Use if you don't want to use name of the ingress | `false` |
| `forecastle.stakater.com/group` | A custom group name. Use if you want the application to show in a different group than the namespace it is running in | `false` |
| `forecastle.stakater.com/instance` | A comma separated list of name/s of the forecastle instance/s where you want this application to appear. Use when you have multiple forecastle dashboards | `false` |
| `forecastle.stakater.com/url` | A URL for the forecastle app (This will override the ingress URL). It MUST begin with a scheme i.e., `http://` or `https://` | `false` |
| `forecastle.stakater.com/properties` | A comma separate list of `key:value` pairs for the properties. This will appear as an expandable list for the app | `false` |
| `forecastle.stakater.com/network-restricted` | Specify whether the app is network restricted or not (true or false) | `false` |


### ForecastleApp CRD

Another way Forecastle enhances your ability to dynamically integrate applications is by using ForecastleApp Custom Resource Definition (CRD). This feature adds a layer of flexibility, allowing you to separate the application configuration from the Ingress settings and Forecastle's own configuration.

**Creating a ForecastleApp:**

Expand Down Expand Up @@ -166,10 +243,8 @@ ForecastleApp CRD supports automatic URL discovery from certain Kubernetes resou

- Ingress: Ensures the application's URL is automatically retrieved from the Ingress resource in the same namespace.

To utilize this feature, add the urlFrom field to your ForecastleApp specification like so:
*Please note that the type of resource that you want to discover has be be in the same namespace as the `ForecastleApp` CR.*
*Please note that the type of resource that you want to discover has to be in the same namespace as the `ForecastleApp` CR.*

```yaml
apiVersion: forecastle.stakater.com/v1alpha1
Expand All @@ -187,80 +262,26 @@ spec:

This configuration instructs Forecastle to fetch the app URL directly from the specified Ingress resource, simplifying deployment and configuration.

*Note: To use the CRD feature, ensure it's enabled by setting `crdEnabled: true` in the Forecastle configuration or enabling it in the Helm chart.*

#### Example Configuration

Below is an example of how you might configure Forecastle using a combination of namespace selectors and custom apps:

```yaml
namespaceSelector:
labelSelector:
matchLabels:
component: redis
matchExpressions:
- {key: tier, operator: In, values: [cache]}
matchNames:
- test
title:
headerBackground:
headerForeground: "#ffffff"
instanceName: "Hello"
crdEnabled: false
customApps:
- name: Hello
icon: http://hello
url: http://helloicon
group: Test
properties:
Version: 1.0
```

This configuration demonstrates how to set namespace selectors, customize the header's appearance, enable or disable the CRD feature, and add a custom app with specific properties.

## Features

Forecastle boasts a range of functionalities designed to streamline the management and accessibility of applications in Kubernetes environments. Key features include:

1. **Comprehensive App Listing**: Forecastle aggregates and displays apps from all namespaces specified in the ConfigMap, providing a centralized view of your resources.

2. **Search Functionality**: Quickly locate specific applications with an intuitive search feature, enhancing user experience and efficiency.

3. **Namespace Grouping**: Apps are neatly organized and grouped by their respective namespaces, making navigation and management more straightforward.

4. **Customizable Header**: Tailor the look and feel of your Forecastle dashboard with configurable header options, including title customization and color schemes.

5. **Support for Multiple Instances**: Forecastle is designed to support multiple instances, accommodating varied and complex deployment scenarios.

6. **Custom Apps Integration**: Easily add non-Kubernetes or external applications to your dashboard for a more comprehensive overview of your tools and resources.

7. **ForecastleApp CRD**: Utilize the ForecastleApp Custom Resource Definition to dynamically add custom applications, further enhancing the dashboard’s flexibility.

8. **Custom Grouping and URLs**: Organize your applications into custom groups and assign specific URLs for tailored navigation and accessibility.
*Note: To use the CRD feature, ensure it's enabled by setting `crdEnabled: true` in the Forecastle configuration or by enabling it in the Helm chart.*

9. **Detailed App Information**: Each application comes with detailed information, offering insights and essential details at a glance.

## Scaling with Multiple Instances

Forecastle's design allows for running multiple instances, providing scalability and flexibility in diverse environments. Here's how you can effectively scale Forecastle.
## Developer Guide

### Deploying Multiple Instances

**Basic Deployment**: To run multiple Forecastle instances, deploy each instance in a separate namespace. Specify a list of namespaces for each instance to monitor ingresses.

### Configuring Named Instances for Enhanced Flexibility

**Named Instance Configuration**: For greater control over which applications are displayed in specific instances (irrespective of their namespaces), configure each Forecastle instance with a unique name using the `instanceName` setting in the Forecastle configuration.
### Bug Reports & Feature Requests

### Controlling Application Display Across Instances
Please use the [issue tracker](https://github.com/stakater/Forecastle/issues) to report any bugs or file feature requests.

**Application-Specific Instance Display**: After naming your instances, use the `forecastle.stakater.com/instance` annotation on your ingresses. This annotation dictates which application appears in which Forecastle instance.
### Developing

**Multiple Instance Display**: It's possible for a single application (ingress) to appear in multiple Forecastle dashboards. For instance, if you have two instances named dev-dashboard and prod-dashboard, adding `dev-dashboard,prod-dashboard` in the ingress's instance annotation will ensure the application is visible on both dashboards.
PRs are most welcome. In general, we follow the "fork-and-pull" Git workflow.

### Helm Deployment Considerations
1. **Fork** the repo on GitHub.
2. **Clone** the project to your own machine.
3. **Commit** changes to your own branch.
4. **Push** your work back up to your fork.
5. Submit a **Pull request** so that we can review your changes.

**Unique Naming in Helm**: When deploying Forecastle instances via Helm, ensure each instance has a unique `nameOverride` value (default is forecastle). This step is crucial to avoid conflicts between global resources like ClusterRole and ClusterRoleBinding.
*NOTE: Be sure to merge the latest from "upstream" before making a pull request!*

## Help

Expand All @@ -274,24 +295,6 @@ Join and talk to us on the #tools-imc channel for discussing Forecastle
[![Join Slack](https://stakater.github.io/README/stakater-join-slack-btn.png)](https://slack.stakater.com/)
[![Chat](https://stakater.github.io/README/stakater-chat-btn.png)](https://stakater-community.slack.com/messages/CBM7Q80KX)

## Contributing

### Bug Reports & Feature Requests

Please use the [issue tracker](https://github.com/stakater/Forecastle/issues) to report any bugs or file feature requests.

### Developing

PRs are welcome. In general, we follow the "fork-and-pull" Git workflow.

1. **Fork** the repo on GitHub
2. **Clone** the project to your own machine
3. **Commit** changes to your own branch
4. **Push** your work back up to your fork
5. Submit a **Pull request** so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

## Changelog

View our closed [Pull Requests](https://github.com/stakater/Forecastle/pulls?q=is%3Apr+is%3Aclosed).
Expand Down

0 comments on commit d4e6587

Please sign in to comment.