Skip to content
This repository has been archived by the owner on Feb 27, 2023. It is now read-only.

Latest commit

 

History

History
196 lines (137 loc) · 6.92 KB

README.md

File metadata and controls

196 lines (137 loc) · 6.92 KB
Raw

Deployment

Prerequisites

  • A copy of this repository. Download, or clone:

    $ git clone git@github.com:projectcontour/gimbal.git

  • A single Kubernetes cluster to deploy Gimbal

  • Kubernetes or Openstack clusters with flat networking. That is, each Pod has a routable IP address on the network.

Deploy Contour

# Navigate to deployment directory
$ cd deployment

# Deploy Contour
$ kubectl create -f contour/

The deployment includes sample Network Policies that restrict access to Contour and Envoy. The policies explicitly allow access from Prometheus to scrape for metrics.

NOTE: The current configuration exposes the /stats path from the Envoy Admin UI so that Prometheus can scrape for metrics.

For additional information about Contour, see the Gimbal architecture doc.

Deploy Discoverers

Service discovery is enabled with Discoverers, which have both Kubernetes and Openstack implementations.

# Create gimbal-discoverer namespace
kubectl create -f gimbal-discoverer/01-common.yaml

Kubernetes

The Kubernetes Discoverer is responsible for looking at all services and endpoints in a Kubernetes cluster and synchronizing them to the host cluster.

Credentials to the remote cluster must be created as a Secret.

# Kubernetes secret
$ kubectl -n gimbal-discovery create secret generic remote-discover-kubecfg \
    --from-file=config=./config \
    --from-literal=backend-name=node02

# Deploy Discoverer
$ kubectl apply -f gimbal-discoverer/02-kubernetes-discoverer.yaml

For more information, see the Kubernetes Discoverer doc.

Openstack

The Openstack Discoverer is responsible for looking at all LBaaS and members in an Openstack cluster and synchronizing them to the host cluster.

Credentials to the remote cluster must be created as a secret.

# Openstack secret
$ kubectl -n gimbal-discovery create secret generic remote-discover-openstack \
    --from-file=certificate-authority-data=./ca.pem \
    --from-literal=backend-name=openstack \
    --from-literal=username=admin \
    --from-literal=password=abc123 \
    --from-literal=auth-url=https://api.openstack:5000/ \
    --from-literal=tenant-name=team1

# Deploy Discoverer
$ kubectl apply -f gimbal-discoverer/02-openstack-discoverer.yaml

For more information, see the OpenStack Discoverer doc.

Deploy Prometheus

A sample deployment of Prometheus and Alertmanager is provided that uses temporary storage. This deployment can be used for testing and development, but might not be suitable for all environments.

Stateful Deployment

A stateful deployment of Prometheus should use persistent storage with Persistent Volumes and Persistent Volume Claims to maintain a correlation between a data volume and the Prometheus Pod. Persistent volumes can be static or dynamic and depends on the backend storage implementation utilized in environment in which the cluster is deployed. For more information, see the Kubernetes documentation on types of persistent volumes.

Quick start

# Deploy 
$ kubectl apply -f prometheus

Access the Prometheus web UI

$ kubectl -n gimbal-monitoring port-forward $(kubectl -n gimbal-monitoring get pods -l app=prometheus -l component=server -o jsonpath='{.items[0].metadata.name}') 9090:9090

then go to http://localhost:9090 in your browser.

Access the Alertmanager web UI

$ kubectl -n gimbal-monitoring port-forward $(kubectl -n gimbal-monitoring get pods -l app=prometheus -l component=alertmanager -o jsonpath='{.items[0].metadata.name}') 9093:9093

then go to http://localhost:9093 in your browser.

Deploy Grafana

A sample deployment of Grafana is provided that uses temporary storage.

Quick start

# Deploy
$ kubectl apply -f grafana/

# Create secret with grafana credentials
$ kubectl create secret generic grafana -n gimbal-monitoring \
    --from-literal=grafana-admin-password=admin \
    --from-literal=grafana-admin-user=admin

Access the Grafana UI

$ kubectl port-forward $(kubectl get pods -l app=grafana -n gimbal-monitoring -o jsonpath='{.items[0].metadata.name}') 3000 -n gimbal-monitoring

then go to http://localhost:3000 in your browser. The username and password are from when you defined the Grafana secret in the previous step.

Validation

Discovery cluster

This example deploys a sample application in the default namespace of the discovered Kubernetes cluster that you created.

# Deploy sample apps
$ kubectl apply -f example-workload/deployment.yaml

Gimbal cluster

Run the following commands on the Gimbal cluster to verify its components:

# Verify Discoverer Components
$ kubectl get po -n gimbal-discovery
NAME                                         READY     STATUS    RESTARTS   AGE
k8s-kubernetes-discoverer-55899dcb66-lgvnk   1/1       Running   0          5m

# Verify Contour
$ kubectl get po -n gimbal-contour
NAME            READY     STATUS    RESTARTS   AGE
contour-lq6mm   2/2       Running   0          5h

# Verify discovered services
$ kubectl get svc -l gimbal.projectcontour.io/backend
NAME                TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
nginx-node02        ClusterIP   None         <none>        80/TCP    17m
kuard-node02        ClusterIP   None         <none>        80/TCP    17m

# Deploy an Ingress route
$ kubectl apply -f example-workload/ingressroute.yaml

# Port forward to the Envoy pod
$ kubectl port-forward $(kubectl get pods -n gimbal-contour -l app=envoy -o jsonpath='{.items[0].metadata.name}') 9000:80 -n gimbal-contour

# Make a request to Gimbal cluster which will proxy traffic to the secondary cluster
# The curl should respond with the kuard and nginx alternating between requests
$ curl -i -H "Host: mixed.local" localhost:9000