Install Kuadrant on an OpenShift cluster¶
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.
Procedure¶
Step 1 - Set up your environment¶
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 REDIS_URL=redis://user:xxxxxx@some-redis.com:10340 # A Redis cluster URL
Step 2 - Install Gateway API v1¶
Before you can use Kuadrant, you must install Gateway API v1 as follows:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
Step 3 - Install cert-manager¶
Before you can use Kuadrant, you must install cert-manager.
The minimum supported version of cert-manager is v1.12.1.
Install one of the different flavours of the Cert-Manager.
Install community version of the cert-manager¶
Consider installing cert-manager via OperatorHub, which you can do from the OpenShift web console.
More installation options at cert-manager.io
Install cert-manager Operator for Red Hat OpenShift¶
You can install the cert-manager Operator for Red Hat OpenShift by using the web console.
Step 4 - 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 the Istio Gateway provider, run the following commands:
kubectl apply -f - <<EOF
kind: OperatorGroup
apiVersion: operators.coreos.com/v1
metadata:
name: sail
namespace: istio-system
spec:
upgradeStrategy: Default
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: sailoperator
namespace: istio-system
spec:
channel: 3.0-dp1
installPlanApproval: Automatic
name: sailoperator
source: community-operators
sourceNamespace: openshift-marketplace
EOF
Check the status of the installation as follows:
When ready, the status will change from installing to complete.
Configure Istio¶
To configure the Istio Gateway API provider, run the following command:
kubectl apply -f - <<EOF
apiVersion: operator.istio.io/v1alpha1
kind: Istio
metadata:
name: default
spec:
version: v1.21.0
namespace: istio-system
# Disable autoscaling to reduce dev resources
values:
pilot:
autoscaleEnabled: false
EOF
Wait for Istio to be ready as follows:
Step 5 - Optional: Configure observability and metrics¶
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.
You can set up user-facing monitoring by following the steps in the OpenShift documentation on configuring the monitoring stack.
If you have user workload monitoring enabled, it is best to configure remote writes to a central storage system such as Thanos:
The example dashboards and alerts 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:
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 must create a telemetry resource as follows:
kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/config/observability/openshift/telemetry.yaml
If you have Grafana installed in your cluster, you can import the example dashboards and alerts.
For example installation details, see installing Grafana on OpenShift. 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.
Step 6 - 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:
Set up a CatalogSource as follows:
kubectl apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
name: kuadrant-operator-catalog
namespace: kuadrant-system
spec:
sourceType: grpc
image: quay.io/kuadrant/kuadrant-operator-catalog:v0.7.1
displayName: Kuadrant Operators
publisher: grpc
updateStrategy:
registryPoll:
interval: 45m
EOF
AWS Route 53 credentials for TLS¶
Set the AWS Route 53 credentials for TLS verification as follows:
kubectl -n kuadrant-system 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
Redis credentials for rate limiting counters¶
Set the Redis credentials for shared multicluster counters for the Kuadrant Limitador component as follows:
AWS Route 53 credentials for DNS¶
Set the AWS Route 53 credentials for managing DNS records as follows:
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
Step 7 - Install the Kuadrant Operator¶
To install the Kuadrant Operator, enter the following command:
kubectl apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: kuadrant-operator
namespace: kuadrant-system
spec:
channel: preview
installPlanApproval: Automatic
name: kuadrant-operator
source: kuadrant-operator-catalog
sourceNamespace: kuadrant-system
---
kind: OperatorGroup
apiVersion: operators.coreos.com/v1
metadata:
name: kuadrant
namespace: kuadrant-system
spec:
upgradeStrategy: Default
EOF
Wait for the Kuadrant Operators to be installed as follows:
After some time, this command should return complete.
Step 8 - Configure Kuadrant¶
To configure your Kuadrant deployment, enter the following command:
kubectl apply -f - <<EOF
apiVersion: kuadrant.io/v1beta1
kind: Kuadrant
metadata:
name: kuadrant
namespace: kuadrant-system
spec:
limitador:
storage:
redis-cached:
configSecretRef:
name: redis-config
EOF
Wait for Kuadrant to be ready as follows:
Kuadrant is now ready to use.