You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ki...@apache.org on 2020/07/29 09:30:28 UTC
[trafficserver-ingress-controller] branch master updated: Clean up
README and fix label typo (#22)
This is an automated email from the ASF dual-hosted git repository.
kichan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new 915de22 Clean up README and fix label typo (#22)
915de22 is described below
commit 915de22124fa34e4cae125b45e74c5aa1a39f314
Author: Kit Chan <ki...@apache.org>
AuthorDate: Wed Jul 29 02:30:20 2020 -0700
Clean up README and fix label typo (#22)
* Fix label typo
* Add Badges for actions
* Add K8s / Minikube support version
* Update README.md
* README cleanup
* More README cleanup
---
.asf.yaml | 2 +-
README.md | 200 +++++++++++++++-----------------------------------------------
2 files changed, 50 insertions(+), 152 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index 90f77fa..1845fce 100644
--- a/.asf.yaml
+++ b/.asf.yaml
@@ -11,7 +11,7 @@ github:
- kubernetes
- kubernetes-ingress
- ingress
- - kubernetes-ingress-controlle
+ - kubernetes-ingress-controller
- k8s
- apache
features:
diff --git a/README.md b/README.md
index 05cde09..e31354a 100644
--- a/README.md
+++ b/README.md
@@ -19,54 +19,42 @@
ATS Kubernetes Ingress Controller
=================================
-
-## Prerequisites
-It is assumed that you understand conceptually, [docker containers](https://www.docker.com/resources/what-container), [kubernetes](https://kubernetes.io/), and [proxy servers](https://en.wikipedia.org/wiki/Proxy_server)
-
-*Throughout ALL documentations, this project is referred to as "**ingress controller**" or "**the controller**"
+
+
## Contents
-- [ATS Kubernetes Ingress Controller](#ats-kubernetes-ingress-controller)
- - [Prerequisites](#prerequisites)
- - [Contents](#contents)
- - [Abstract](#abstract)
- - [What is Ingress Controller?](#what-is-ingress-controller)
- - [Versions](#versions)
- - [How to use](#how-to-use)
- - [Required Software](#required-software)
- - [Download project](#download-project)
- - [Example Walkthrough](#example-walkthrough)
- - [Proxy](#proxy)
- - [ConfigMap](#configmap)
- - [Snippet](#snippet)
- - [Ingress Class](#ingressclass)
- - [Development](#development)
- - [Develop with Go-Lang in Linux](#develop-with-go-lang-in-linux)
- - [Compilation](#compilation)
- - [Text-Editor](#text-editor)
- - [Documentation](#documentation)
-
-## Abstract
-[Apache Traffic Server (ATS)](https://trafficserver.apache.org/) is a high performance, open-source, caching proxy server that is scalable and configurable. This project integrates ATS as the ingress resource to a [Kubernetes(K8s)](https://kubernetes.io/) cluster, then acts as the ingress resource's custom controller.
-
+- [Introduction](#Introduction)
+- [Versions of Software Used](#versions-of-software-used)
+- [How to use](#how-to-use)
+ - [Requirements](#requirements)
+ - [Download project](#download-project)
+ - [Example Walkthrough](#example-walkthrough)
+ - [Proxy](#proxy)
+ - [ConfigMap](#configmap)
+ - [Snippet](#snippet)
+ - [Ingress Class](#ingressclass)
+ - [Logging and Monitoring](#logging-and-monitoring)
+ - [Fluentd](#fluend)
+ - [Prometheus and Grafana](#prometheus-and-grafana)
+- [Development](#development)
+ - [Develop with Go-Lang in Linux](#develop-with-go-lang-in-linux)
+ - [Compilation](#compilation)
+ - [Unit Tests](#unit-tests)
+ - [Text-Editor](#text-editor)
+- [Documentation](#documentation)
+
+## Introduction
+[Apache Traffic Server (ATS)](https://trafficserver.apache.org/) is a high performance, open-source, caching proxy server that is scalable and configurable. This project uses ATS as a [Kubernetes(K8s)](https://kubernetes.io/) [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-
-From high-level, the ingress controller talks to K8s' API and sets up `watchers` on specific resources that are interesting to ATS. Then, the controller _controls_ ATS by either (1) relay the information from K8s API to ATS, or (2) configure ATS directly.
-
+From high-level, the ingress controller talks to K8s' API and sets up `watchers` on specific resources that are interesting to ATS. Then, the controller _controls_ ATS by either(1) relay the information from K8s API to ATS, or (2) configure ATS directly.
-
-
-## What is Ingress Controller?
-As defined by [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx#what-is-an-ingress-controller):
->An Ingress Controller is a daemon, deployed as a Kubernetes Pod, that watches the apiserver's `/ingresses` endpoint for updates to the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/). Its job is to satisfy requests for Ingresses.
-
-## Versions
+## Versions of Software Used
- Alpine 3.11
-- Apache Traffic Server 8.0.6
+- Apache Traffic Server 8.0.8
- LuaJIT 2.0.4
- Lua 5.1.4
- Go 1.12.8
@@ -76,9 +64,9 @@ As defined by [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-n
## How to use
-### Required Software
+### Requirements
- Docker
-- Kubernetes (Minikube)
+- Kubernetes 1.18 (Minikube 1.11)
To install Docker, visit its [official page](https://docs.docker.com/) and install the correct version for your system.
@@ -96,27 +84,26 @@ Once you have cloned the project repo and started Docker and Minikube, in the te
2. `$ cd trafficserver-ingress-controller`
3. `$ git submodule update --init`
4. `$ docker build -t ats_alpine .`
- - wait for Docker finish building the image
5. `$ docker build -t tsexporter k8s/backend/trafficserver_exporter/`
- - wait for Docker finish building the image
6. `$ docker build -t node-app-1 k8s/backend/node-app-1/`
- - wait for Docker finish building the image
7. `$ docker build -t node-app-2 k8s/backend/node-app-2/`
- - wait for Docker finish building the image
+8. `$ docker pull fluent/fluentd:v1.6-debian-1`
- At this point, we have created necessary images for our example. Let's talk about what each step does:
- - Step 2 builds an image to create a Docker container that will contain the Apache Traffic Server (ATS) itself, the kubernetes ingress controller, along with other software required for the controller to do its job.
- - Step 3 builds an image for the trafficserver exporter. This exports the ATS statistics over HTTP for Prometheus to read.
- - Steps 4 and 5 build 2 images that will serve as backends to [kubernetes services](https://kubernetes.io/docs/concepts/services-networking/service/) which we will shortly create
+ - Step 4 builds an image to create a Docker container that will contain the Apache Traffic Server (ATS) itself, the kubernetes ingress controller, along with other software required for the controller to do its job.
+ - Step 5 builds an image for the trafficserver exporter. This exports the ATS statistics over HTTP for Prometheus to read.
+ - Steps 6 and 7 build 2 images that will serve as backends to [kubernetes services](https://kubernetes.io/docs/concepts/services-networking/service/) which we will shortly create
-8. `$ kubectl create namespace trafficserver-test`
+9. `$ kubectl create namespace trafficserver-test`
- Create a namespace for ATS pod
-9. `$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=atssvc/O=atssvc"`
+10. `$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=atssvc/O=atssvc"`
- Create a self-signed certificate
-10. `$ kubectl create secret tls tls-secret --key tls.key --cert tls.crt -n trafficserver-test --dry-run=client -o yaml | kubectl apply -f -`
+11. `$ kubectl create secret tls tls-secret --key tls.key --cert tls.crt -n trafficserver-test --dry-run=client -o yaml | kubectl apply -f -`
- Create a secret in the namespace just created
-11. `$ kubectl apply -f k8s/traffic-server/`
- - will define a new [kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) named `trafficserver-test` and deploy a single ATS pod to said namespace. The ATS pod is also where the ingress controller lives. Additionally, this will expose your local machine's port `30000` to the outside world.
+12. `$ kubectl apply -f k8s/configmaps/fluentd-confmap.yaml`
+ - Create config map for fluentd
+13. `$ kubectl apply -f k8s/traffic-server/`
+ - will define a new [kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) named `trafficserver-test` and deploy a single ATS pod to said namespace. The ATS pod is also where the ingress controller lives.
#### Proxy
@@ -127,7 +114,6 @@ The following steps can be executed in any order, thus list numbers are not used
- creates kubernetes services and [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for `appsvc1` and `appsvc2`
- deploy 2 of each `appsvc1`, and `appsvc2` pods in `trafficserver-test-2`, totally 4 pods in said namespace.
- similarly, deploy 2 of each `appsvc1`, and `appsvc2` pods in `trafficserver-test-3`, totally 4 pods in this namespace. We now have 8 pods in total for the 2 services we have created and deployed in the 2 namespaces.
- - in addition to the ATS pod, we have created and deployed 9 pods.
- `$ kubectl apply -f k8s/ingresses/`
- creates namespaces `trafficserver-test-2` and `trafficserver-test-3` if not already exist
@@ -136,9 +122,7 @@ The following steps can be executed in any order, thus list numbers are not used
- both ingress resources define domain name `test.edge.com`; however, `test.edge.com/app1` is only defined in `trafficserver-test-2` and `test.edge.com/app2` is only defined in `trafficserver-test-3`
- Addtionally, an ingress resources defines HTTPS access for `test.edge.com/app2` in namespace `trafficserver-test-3`
-When both steps _above_ have executed at least once, ATS proxying will have started to work.
-
-In kubernetes, ingress resources are necessary to enable proxying since it is where domain names are defined. However, given _only_ domain names, ATS cannot proxy requests when it doesn't have backend(s) to handle requests. Thus, only when both service pods and ingress are defined can ATS start proxying. To see proxy in action, we can use [curl](https://linux.die.net/man/1/curl) to "fake" external requests:
+When both steps _above_ have executed at least once, ATS proxying will have started to work. To see proxy in action, we can use [curl](https://linux.die.net/man/1/curl):
1. `$ curl -vH "HOST:test.media.com" "$(minikube ip):30000/app1"`
2. `$ curl -vH "HOST:test.media.com" "$(minikube ip):30000/app2"`
@@ -146,78 +130,6 @@ In kubernetes, ingress resources are necessary to enable proxying since it is wh
4. `$ curl -vH "HOST:test.edge.com" "$(minikube ip):30000/app2"`
5. `$ curl -vH "HOST:test.edge.com" -k "https://$(minikube ip):30043/app2"`
-With above curl commands, outputs from number 1 and 3 should be the same; outputs from number 2 and 4 should be same. The corresponding pairs are the same because all `/app1` use the same backend service _image_, and the same goes for `/app2`. Number 5 illustrates the https version for number 4 and the result is similar.
-
-Expected received packet from `/app1` resembles:
-```html
-< HTTP/1.1 200 OK
-< X-Powered-By: Express
-< Accept-Ranges: bytes
-< Cache-Control: public, max-age=0
-< Last-Modified: Tue, 06 Aug 2019 16:31:53 GMT
-< ETag: W/"be-16c67c5d0a8"
-< Content-Type: text/html; charset=UTF-8
-< Content-Length: 190
-< Date: Mon, 19 Aug 2019 18:39:14 GMT
-< Age: 1
-< Connection: keep-alive
-< Server: ATS/7.1.6
-<
-<!DOCTYPE html>
-<HTML>
-
-<HEAD>
- <TITLE>
- Hello from app1
- </TITLE>
-</HEAD>
-
-<BODY>
- <H1>Hi</H1>
- <P>This is very minimal "hello world" HTML document.</P>
-</BODY>
-
-</HTML>
-* Connection #0 to host localhost left intact
-```
-
-Expected received packet from `/app2` resembles:
-```html
-< HTTP/1.1 200 OK
-< X-Powered-By: Express
-< Accept-Ranges: bytes
-< Cache-Control: public, max-age=0
-< Last-Modified: Fri, 14 Jun 2019 18:18:51 GMT
-< ETag: W/"bc-16b5736b2f8"
-< Content-Type: text/html; charset=UTF-8
-< Content-Length: 188
-< Date: Mon, 19 Aug 2019 18:39:10 GMT
-< Age: 0
-< Connection: keep-alive
-< Server: ATS/7.1.6
-<
-<!DOCTYPE html>
-<HTML>
-
-<HEAD>
- <TITLE>
- A Small Hello
- </TITLE>
-</HEAD>
-
-<BODY>
- <H1>Hi</H1>
- <P>This is very minimal "hello world" HTML document.</P>
-</BODY>
-
-</HTML>
-* Connection #0 to host localhost left intact
-```
-
-The curl commands demonstrate that, with the help of the ingress controller, ATS can not only resolve domain names while routing requests to various namespaces based on path, but also, is capable of handling the case where domain's paths existing across different namespaces.
-
-Of course there are checks in place by the ingress controller so that any path corresponding to a domain name can only be defined in one namespace, and domain names are resolved across all namespace.
-
#### ConfigMap
Below is an example of configuring Apache Traffic Server [_reloadable_ configurations](https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/files/records.config.en.html#reloadable) using [kubernetes configmap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) resource:
@@ -228,11 +140,10 @@ Below is an example of configuring Apache Traffic Server [_reloadable_ configura
1. `proxy.config.output.logfile.rolling_enabled: "1"`
2. `proxy.config.output.logfile.rolling_interval_sec: "3000"`
3. `proxy.config.restart.active_client_threshold: "0"`
- - feel free to add other reloadable configurations, and/or change the above 3 to other valid values. Checks are in place so that mistakes are tolerated.
#### Snippet
-You can attach [ATS lua script](https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/lua.en.html) to an ingress object and ATS will execute it for requests matching the routing rules defined in the ingress object. See an example in k8s/ingresses/ats-ingress-2.yaml
+You can attach [ATS lua script](https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/lua.en.html) to an ingress object and ATS will execute it for requests matching the routing rules defined in the ingress object. See an example in annotation section of yaml file [here](k8s/ingresses/ats-ingress-2.yaml)
#### Ingress Class
@@ -242,35 +153,24 @@ You can provide an environment variable called `INGRESS_CLASS` in the deployment
#### Fluentd
-Fluentd is an open source data collector for a unified logging layer. You can read more about Fluentd [here](https://docs.fluentd.org/).
-
-This project ships with Fluentd already integrated with the Apache Traffic Server. The configuration file used for the same can be found [here](k8s/configmaps/fluentd-configmap.yaml)
-
-##### What does it do?
+This project ships with [Fluentd](https://docs.fluentd.org/) already integrated with the Apache Traffic Server. The configuration file used for the same can be found [here](k8s/configmaps/fluentd-configmap.yaml)
As can be seen from the default configuration file, Fluentd reads the Apache Traffic Server access logs located at `/usr/local/var/log/trafficserver/squid.log` and outputs them to `stdout`. The ouput plugin for Fluentd can be changed to send the logs to any desired location supported by Fluentd including Elasticsearch, Kafka, MongoDB etc. You can read more about output plugins [here](https://docs.fluentd.org/output).
#### Prometheus and Grafana
-Prometheus is an open-source systems monitoring and alerting toolkit originally built at SoundCloud. You can read more about it [here](https://prometheus.io/docs/prometheus/latest/getting_started/).
-
-Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. You can read more about Grafana [here](https://grafana.com/docs/grafana/latest/)
+Use the following steps to install [Prometheus](https://prometheus.io/docs/prometheus/latest/getting_started/) and [Grafana](https://grafana.com/docs/grafana/latest/) and use them to monitor the Apache Traffic Server statistics:
-##### How to use?
-
-Use the following steps to install Prometheus and Grafana and use them to monitor the Apache Traffic Server statistics:
-
-1. `$ kubectl apply -f k8s/traffic-server/ats-stats.yaml`
+1. `$ kubectl apply -f k8s/prometheus/ats-stats.yaml`
- Creates a new service which connects to the ATS pod on port 9122. This service will be used by Prometheus to read the Apache Traffic Server stats.
2. `$ kubectl apply -f k8s/configmaps/prometheus-configmap.yaml`
- Creates a new configmap which holds the configuration file for Prometheus. You can modify this configuration file to suit your needs. More about that can be read [here](https://prometheus.io/docs/prometheus/latest/configuration/configuration/)
-3. `$ kubectl apply -f k8s/traffic-server/prometheus-deployment.yaml`
+3. `$ kubectl apply -f k8s/prometheus/prometheus-deployment.yaml`
- Creates a new deployment consisting of Prometheus and Grafana. Also creates two new services to access prometheus and grafana.
4. Open `192.168.x.x:30090` in your web browser to access Prometheus where `192.168.x.x` is the IP returned by the command: `$ minikube ip`
5. Open `192.168.x.x:30030` in your web browser to access the Grafana dashboard where `192.168.x.x` is the IP returned by the command: `$ minikube ip`.
6. To use Prometheus as a datasource for Grafana, please read [this](https://prometheus.io/docs/visualization/grafana/#using). The URL on which Grafana can access Prometheus is `localhost:9090`
-
## Development
### Develop with Go-Lang in Linux
@@ -280,16 +180,14 @@ Use the following steps to install Prometheus and Grafana and use them to monito
4. Add Go workspace to your PATH: `export PATH=$PATH:$(go env GOPATH)/bin`
5. Define Go import Paths
- Go's import path is different from other languages in that all import paths are _absolute paths_. Due to this reason, it is important to set up your project paths correctly
- - define the base path: `mkdir -p $GOPATH/src/github.com/<your user name>/`
+ - define the base path: `mkdir -p $GOPATH/src/github.com/`
6. Clone the project:
- - `cd $GOPATH/src/github.com/<your user name>/`
+ - `cd $GOPATH/src/github.com/`
- `git clone <project>`
7. As of Go 1.12 in order to have `go.mod` within Go paths, you must export: `export GO111MODULE=on` to be able to compile locally.
-*Above steps are a very short summary of [Getting Started](https://golang.org/doc/install) and [How to Write Go Code](https://golang.org/doc/code.html) from official Go-lang documentation. For more detailed info and/or assistance, it is recommended to checkout these 2 links first.
-
### Compilation
-To compile, while in `ingress-ats/` directory: `go build -o ingress_ats main/main.go`
+To compile, type: `go build -o ingress_ats main/main.go`
### Unit Tests
The project includes unit tests for the controller written in Golang and the plugin written in Lua.