Skip to content

Commit

Permalink
docs: add numbering to headers to help navigation and readability (#639)
Browse files Browse the repository at this point in the history 
* docs: add numbering to headers to help navigation and readability, minor edits

* docs: add line break to fix bullet list format on kuadrant docs site

* Update doc/user-guides/secure-protect-connect-single-multi-cluster.md

Co-authored-by: Craig Brookes <[email protected]>

---------

Co-authored-by: Craig Brookes <[email protected]>
  • Loading branch information
@smccarthy-ie @maleck13
smccarthy-ie and maleck13 authored May 13, 2024
1 parent 5f72dcf commit 39ecfe8
Show file tree
Hide file tree
Showing 3 changed files with 194 additions and 151 deletions.
98 changes: 57 additions & 41 deletions doc/install/install-openshift.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,39 @@
# Install Kuadrant on an OpenShift cluster

NOTE: You must perform these steps on each cluster that you want to use Kuadrant on.
NOTE: You must perform these steps on each OpenShift cluster that you want to use Kuadrant on.

## Prerequisites

- OpenShift Container Platform 4.14.x or later with community Operator catalog available
- AWS account with Route 53 and zone
- Accessible Redis Instance
- OpenShift Container Platform 4.14.x or later with community Operator catalog available.
- AWS account with Route 53 and zone.
- Accessible Redis instance.

## Set up your environment

## Procedure

### Step 1 - Set up your environment

```bash
export AWS_ACCESS_KEY_ID=xxxxxxx # Key ID from AWS with Route 53 access
export AWS_SECRET_ACCESS_KEY=xxxxxxx # Access Key from AWS with Route 53 access
export AWS_SECRET_ACCESS_KEY=xxxxxxx # Access key from AWS with Route 53 access
export REDIS_URL=redis://user:[email protected]:10340 # A Redis cluster URL
```

## Install the dependencies

Kuadrant integrates with Istio as a Gateway API provider. Before you can use Kuadrant, you must set up an Istio-based Gateway API provider. For this step, you will use the Sail Operator.
### Step 2 - Install Gateway API v1

### Install v1 of Gateway API:
Before you can use Kuadrant, you must install Gateway API v1 as follows:

```bash
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
```

### Install and configure Istio with the Sail Operator
### Step 3 - Install and configure Istio with the Sail Operator

Kuadrant integrates with Istio as a Gateway API provider. You can set up an Istio-based Gateway API provider by using the Sail Operator.

#### Install Istio

To install Istio, run the following command:
To install the Istio Gateway provider, run the following commands:

```bash
kubectl create ns istio-system
Expand Down Expand Up @@ -58,7 +63,7 @@ spec:
EOF
```

To check the status of the install, you can run:
Check the status of the installation as follows:

```bash
kubectl get installplan -n istio-system -o=jsonpath='{.items[0].status.phase}'
Expand All @@ -68,6 +73,8 @@ When ready, the status will change from `installing` to `complete`.

#### Configure Istio

To configure the Istio Gateway API provider, run the following command:

```bash
kubectl apply -f - <<EOF
apiVersion: operator.istio.io/v1alpha1
Expand All @@ -84,53 +91,52 @@ spec:
EOF
```

Wait for Istio to be ready:
Wait for Istio to be ready as follows:

```bash
kubectl wait istio/default -n istio-system --for="condition=Ready=true"
```

### Step 4 - Optional: Configure observability and metrics

### Best practices for metrics and observability

Kuadrant provides a set of sample dashboards that use known metrics exported by Kuadrant and Gateway components to provide insight into different areas of your APIs and Gateways. While not essential, it is best to set up an observability stack. This section provides links to OpenShift and Thanos documentation on configuring monitoring and metrics storage.
Kuadrant provides a set of example dashboards that use known metrics exported by Kuadrant and Gateway components to provide insight into different components of your APIs and Gateways. While not essential, it is best to set up an OpenShift monitoring stack. This section provides links to OpenShift and Thanos documentation on configuring monitoring and metrics storage.

OpenShift supports a user facing monitoring stack. This can be cofigured and setup this documentation:
You can set up user-facing monitoring by following the steps in the OpenShift documentation on [configuring the monitoring stack](https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html).

https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html
If you have user workload monitoring enabled, it is best to configure remote writes to a central storage system such as Thanos:

If you have user workload monitoring enabled. We Recommend configuring remote write to a central storage system such as Thanos:

- [Remote Write Config](https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html#configuring_remote_write_storage_configuring-the-monitoring-stack)
- [OpenShift remote write configuration](https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html#configuring_remote_write_storage_configuring-the-monitoring-stack)
- [Kube Thanos](https://github.com/thanos-io/kube-thanos)

There are a set of [example dashboards and alerts](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples/) for observing Kuadrant functionality.
These dashboards and alerts make use of low level cpu, metrics and network metrics available from the user monitoring stack in Openshift. They also make use of resource state metrics from Gateway API and Kuadrant resources.
To scrape these additional metrics, you can install a kube-state-metrics instance, with a custom resource config:
The [example dashboards and alerts](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples/) for observing Kuadrant functionality use low-level CPU metrics and network metrics available from the user monitoring stack in OpenShift. They also use resource state metrics from Gateway API and Kuadrant resources.

To scrape these additional metrics, you can install a `kube-state-metrics instance`, with a custom resource configuration as follows:

```bash
kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/config/observability/openshift/kube-state-metrics.yaml
kubectl apply -k https://github.com/Kuadrant/gateway-api-state-metrics?ref=main
```

To enable request metrics in Istio, you will need to create a Telemetry resource:
To enable request metrics in Istio, you must create a `telemetry` resource as follows:

```bash
kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/config/observability/openshift/telemetry.yaml
```

The [dashboards](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples) can be imported into Grafana, if you have it installed in your cluster.
You'll find an example of how to install Grafana on Openshift [here](https://cloud.redhat.com/experts/o11y/ocp-grafana/). Once installed, you will need to add your Thanos instance as a data source to Grafana. Alternatively, if you are just using the user workload monitoring stack in your Openshift cluster (and not writing metrics to an external thanos instance), you can set up a data source to the [thanos-querier route in the Openshift cluster](https://docs.openshift.com/container-platform/4.15/observability/monitoring/accessing-third-party-monitoring-apis.html#accessing-metrics-from-outside-cluster_accessing-monitoring-apis-by-using-the-cli).
If you have Grafana installed in your cluster, you can import the [example dashboards and alerts](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples).

### Install Kuadrant
For example installation details, see [installing Grafana on OpenShift](https://cloud.redhat.com/experts/o11y/ocp-grafana/). When installed, you must add your Thanos instance as a data source to Grafana. Alternatively, if you are using only the user workload monitoring stack in your OpenShift cluster, and not writing metrics to an external Thanos instance, you can [set up a data source to the thanos-querier route in the OpenShift cluster](https://docs.openshift.com/container-platform/4.15/observability/monitoring/accessing-third-party-monitoring-apis.html#accessing-metrics-from-outside-cluster_accessing-monitoring-apis-by-using-the-cli).

To install Kuadrant, use the Kuadrant Operator. Before installing, you will set up some secrets that you will use later:

### Step 5 - Create secrets for your credentials

Before installing the Kuadrant Operator, you must enter the following commands to set up secrets that you will use later:

```bash
kubectl create ns kuadrant-system
```

Setup a catalogsource:
Set up a `CatalogSource` as follows:

```bash
kubectl apply -f - <<EOF
Expand All @@ -150,7 +156,9 @@ spec:
EOF
```

AWS Route 53 credentials for TLS verification:
#### AWS Route 53 credentials for TLS

Set the AWS Route 53 credentials for TLS verification as follows:

```bash
kubectl -n kuadrant-system create secret generic aws-credentials \
Expand All @@ -159,27 +167,33 @@ kubectl -n kuadrant-system create secret generic aws-credentials \
--from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
```

Redis credentials for shared multicluster counters for Kuadrant's Limitador component:
#### Redis credentials for rate limiting counters

Set the Redis credentials for shared multicluster counters for the Kuadrant Limitador component as follows:

```bash
kubectl -n kuadrant-system create secret generic redis-config \
--from-literal=URL=$REDIS_URL
```

#### AWS Route 53 credentials for DNS

Set the AWS Route 53 credentials for managing DNS records as follows:

```bash
kubectl create ns ingress-gateway
```

AWS Route 53 credentials for managing DNS records:

```bash
kubectl -n ingress-gateway create secret generic aws-credentials \
--type=kuadrant.io/aws \
--from-literal=AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
--from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
```

Finally, to install the Kuadrant Operator:
### Step 6 - Install the Kuadrant Operator

To install the Kuadrant Operator, enter the following command:

```bash
kubectl apply -f - <<EOF
Expand All @@ -205,15 +219,17 @@ spec:
EOF
```

Wait for Kuadrant Operators to be installed:
Wait for the Kuadrant Operators to be installed as follows:

```bash
kubectl get installplan -n kuadrant-system -o=jsonpath='{.items[0].status.phase}'
```

After some time, this should return `complete`.
After some time, this command should return `complete`.

### Step 7 - Configure Kuadrant

#### Configure Kuadrant
To configure your Kuadrant deployment, enter the following command:

```bash
kubectl apply -f - <<EOF
Expand All @@ -231,7 +247,7 @@ spec:
EOF
```

Wait for Kuadrant to be ready:
Wait for Kuadrant to be ready as follows:

```bash
kubectl wait kuadrant/kuadrant --for="condition=Ready=true" -n kuadrant-system --timeout=300s
Expand All @@ -240,4 +256,4 @@ kubectl wait kuadrant/kuadrant --for="condition=Ready=true" -n kuadrant-system -
Kuadrant is now ready to use.

## Next steps
- [Secure, protect, and connect APIs on single or multiple clusters](../user-guides/secure-protect-connect-single-multi-cluster.md)
- [Secure, protect, and connect APIs with Kuadrant on OpenShift](../user-guides/secure-protect-connect-single-multi-cluster.md)
Loading

0 comments on commit 39ecfe8

Please sign in to comment.