This is an automated email from the ASF dual-hosted git repository.
kvn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new 5ffd0cc doc: optimize develop.md and add user-guide (#170)
5ffd0cc is described below
commit 5ffd0cca28b039208800e5faf6d574d11790bfae
Author: Alex Zhang <[email protected]>
AuthorDate: Tue Jan 12 13:59:09 2021 +0800
doc: optimize develop.md and add user-guide (#170)
* doc: optimize develop.md and add user-guide
* fix: remove duplicated empty lines
* fix: code review comments
* fix: markdown lint errors
---
docs/develop.md | 227 ------------------------------------------------
docs/development.md | 90 +++++++++++++++++++
docs/samples/httpbin.md | 94 ++++++++++++++++++++
3 files changed, 184 insertions(+), 227 deletions(-)
diff --git a/docs/develop.md b/docs/develop.md
deleted file mode 100644
index d2502a5..0000000
--- a/docs/develop.md
+++ /dev/null
@@ -1,227 +0,0 @@
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-# Document for developer
-
-## Dependencies
-
-1. Kubernetes
-2. Apache APISIX
-3. golang >= 1.13 (go mod)
-
-## Prepare development environment
-
-### 1. Kubernetes
-
-[Install minikube](https://kubernetes.io/docs/tasks/tools/install-minikube)
-
-Tips: The Kubernetes cluster deployment method is recommended for production
and test environments.
-
-### 2. Apache APISIX
-
-[Install Apache APISIX in
Kubernetes](https://github.com/apache/apisix/tree/master/kubernetes)
-
-### 3. httpbin service
-
-Deploy [httpbin](https://github.com/postmanlabs/httpbin) to your Kubernetes
cluster and expose it as a Service. For instance:
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: httpbin
-spec:
- replicas: 1
- selector:
- matchLabels:
- app: httpbin
- template:
- metadata:
- labels:
- app: httpbin
- spec:
- terminationGracePeriodSeconds: 0
- containers:
- - name: httpbin
- image: "kennethreitz/httpbin"
- imagePullPolicy: IfNotPresent
- ports:
- - containerPort: 80
- name: "http"
- protocol: "TCP"
----
-apiVersion: v1
-kind: Service
-metadata:
- name: httpbin
-spec:
- selector:
- app: httpbin
- ports:
- - name: http
- port: 8080
- protocol: TCP
- targetPort: 80
- type: ClusterIP
-```
-
-## Configuration
-
-### Configure the kubeconfig file locally to facilitate local debugging
-
-1. Start minikube.
-
-2. Location: ~/.kube/config
-
-3. Copy the config file to your local development environment, the path should
be configured in apisix-ingress-controller by specifying `--kubeconfig` option.
-
-### Configure APISIX service address
-
-Your APISIX service address should be configured in apisix-ingress-controller
by specifying `--apisix-base-url` option.
-
-## Start ingress-controller locally
-
-* Build and run apisix-ingress-controller
-
-```shell
-$ make build
-$ ./apisix-ingress-controller ingress \
- --kubeconfig /path/to/kubeconfig \
- --http-listen :8080 \
- --log-output stderr \
- --apisix-base-url http://apisix-service:port/apisix
-```
-
-Tips: The program may print some error logs, indicating that the resource
cannot be found. Continue with the following steps to define the route through
CRDs.
-
-### Define ApisixRoute
-
-Take the backend service `httpbin` as an example (you can choose any other
upstream services for test).
-
-In fact, in order to reduce the trouble caused by ingress migration, we try to
keep the structure of ApisixRoute consistent with the original ingress.
-
-The configuration differences with nginx-ingress are
-
-1. `apiVersion` and `kind` are different.
-2. Path uses wildcards for prefix matching, such as `/hello*`.
-
-```yaml
-kubectl apply -f - <<EOF
-apiVersion: apisix.apache.org/v1
-kind: ApisixRoute
-metadata:
- name: httpserver-route
-spec:
- rules:
- - host: test.apisix.apache.org
- http:
- paths:
- - backend:
- serviceName: httpbin.default.svc.cluster.local
- servicePort: 8080
- path: /hello*
-EOF
-```
-
-Here we use the FQDN `httpbin.default.svc.cluster.local` as the `serviceName`,
and the service port is 8080, change them if your `httpbin` service has a
different name, namespace or port.
-
-In addition, `ApisixRoute` also continues to support the definition with
annotation, you can also define as below.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixRoute
-metadata:
- annotations:
- k8s.apisix.apache.org/cors-allow-headers:
DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,openID,audiotoken
- k8s.apisix.apache.org/cors-allow-methods: HEAD,GET,POST,PUT,PATCH,DELETE
- k8s.apisix.apache.org/cors-allow-origin: '*'
- k8s.apisix.apache.org/enable-cors: "true"
- k8s.apisix.apache.org/ssl-redirect: "false"
- k8s.apisix.apache.org/whitelist-source-range: 1.2.3.4,2.2.0.0/16
- name: httpserver-route
-spec:
- rules:
- - host: test1.apisix.apache.org
- http:
- paths:
- - backend:
- serviceName: httpbin.default.svc.cluster.local
- servicePort: 8080
- path: /hello*
- plugins:
- - enable: true
- name: proxy-rewrite
- config:
- regex_uri:
- - '^/(.*)'
- - '/voice-copy-outer-service/$1'
- scheme: http
- host: internalalpha.talkinggenie.com
- enable_websocket: true
-```
-
-The definition in config needs to follow the schema definition of the plugin
[proxy-rewrite](https://github.com/apache/apisix/blob/master/doc/plugins/proxy-rewrite.md).
-
-If the plug-in schema is an array, you need to change the `config` field to
`config_set`.
-
-### Define ApisixService
-
-```yaml
-kubectl apply -f - <<EOF
-apiVersion: apisix.apache.org/v1
-kind: ApisixService # apisix service
-metadata:
- name: httpserver
-spec:
- upstream: httpserver # upstream = default/httpserver
(namespace/upstreamName)
- port: 8080 # set port on service
- plugins:
- - name: aispeech-chash
- enable: true
- config:
- uri_args:
- - "userId"
- - "productId|deviceName"
- key: "apisix-chash-key"
-EOF
-```
-
-`ApisixService` supports plug-ins similar to `ApisixRoute`.
-
-### Define ApisixUpstream
-
-```yaml
-kubectl apply -f - <<EOF
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream # apisix upstream
-metadata:
- name: httpbin # default/httpbin
-spec:
- ports:
- - port: 8080
- loadbalancer:
- type: chash
- hashOn: header
- key: hello
-EOF
-```
-
-Now, you can try to modify these yaml according to the CRD format and see if
it will be synchronized to Apache APISIX.
-
-Enjoy! If you have any questions, please report to the
[issue](https://github.com/apache/apisix-ingress-controller/issues).
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..8d883d2
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,90 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# Developing for Apache APISIX Ingress Controller
+
+This document explains how to get started with developing for Apache APISIX
Ingress controller.
+
+## Prerequisites
+
+* Install [Go 1.13](https://golang.org/dl/) or later, and we use go module to
manage the go package dependencies.
+* Prepare an available Kubernetes cluster in your workstation, we recommend
you to use [Minikube](https://github.com/kubernetes/minikube).
+* [Install Apache APISIX in Kubernetes by Helm
Chart](https://github.com/apache/apisix-helm-chart).
+
+## Fork and Clone
+
+* Fork the repository from
[apache/apisix-ingress-controller](https://github.com/apache/apisix-ingress-controller)
to your own GitHub account.
+* Clone the forked repository to your workstation.
+* Run `go mod download` to download modules to local cache. By the way, if you
are a developer in China, we suggest you setting `GOPROXY` to
`https://goproxy.cn` to speed up the downloading.
+
+## Build
+
+```shell
+cd /path/to/apisix-ingress-controller
+make build
+./apisix-ingress-controller version
+```
+
+## Test
+
+### Run unit test cases
+
+```shell
+cd /path/to/apisix-ingress-controller
+make unit-test
+```
+
+### Run e2e test cases
+
+```shell
+cd /path/to/apisix-ingress-controller
+make e2e-test
+```
+
+Note the running of e2e cases is somewhat slow, so please be patient.
+
+### Build docker image
+
+```shell
+cd /path/to/apisix-ingress-controller
+make build-image IMAGE_TAG=a.b.c
+```
+
+The Dockerfile in this repository is only for development, not for release.
+
+## Run apisix-ingress-controller locally
+
+We assume all prerequisites abovementioned are met, what's more, since we want
to run apisix-ingress-controller in bare-metal environment, please make sure
both the proxy service and admin api service of Apache APISIX are exposed
outside of the Kubernetes cluster, e.g. configuring them as
[NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport)
services.
+
+Let's assume the Admin API service address of Apache APISIX is
`http://192.168.65.2:31156`. Next launch the ingress-apisix-controller by the
following command.
+
+```shell
+cd /path/to/apisix-ingress-controller
+./apisix-ingress-controller ingress \
+ --kubeconfig /path/to/kubeconfig \
+ --http-listen :8080 \
+ --log-output stderr \
+ --apisix-base-url http://192.168.65.2:31156/apisix/admin
+ --apisix-admin-key edd1c9f034335f136f87ad84b625c8f1
+```
+
+Something you need to pay attention to:
+
+* configuring of `--kubeconfig`, if you are using Minikube, the file path
should be `~/.kube/config`.
+* configuring of `--apisix-admin-key`, if you have changed the admin key in
Apache APISIX, also changing it here, if you disable the authentication if
Apache APISIX, just removing this option.
diff --git a/docs/samples/httpbin.md b/docs/samples/httpbin.md
new file mode 100644
index 0000000..5c63b9e
--- /dev/null
+++ b/docs/samples/httpbin.md
@@ -0,0 +1,94 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# Proxy the httpbin service
+
+This document explains how apisix-ingress-controller guides Apache APISIX
routes traffic to httpbin service correctly.
+
+## Prerequisites
+
+* Prepare an available Kubernetes cluster in your workstation, we recommend
you to use [Minikube](https://github.com/kubernetes/minikube).
+* [Install Apache APISIX in Kubernetes by Helm
Chart](https://github.com/apache/apisix-helm-chart).
+* Install
[apisix-ingress-controller](https://github.com/apache/apisix-ingress-controller/blob/master/docs/install.md).
+
+## Deploy httpbin service
+
+We use [kennethreitz/httpbin](https://hub.docker.com/r/kennethreitz/httpbin/)
as the service image, See its overview page for details.
+
+Now, try to deploy it to your Kubernetes cluster:
+
+```shell
+kubectl run httpbin --image kennethreitz/httpbin --port 80
+kubectl expose pod httpbin --port 80
+```
+
+## Resource Delivery
+
+In order to let Apache APISIX proxies requests to httpbin, we need to create
an `ApisixRoute` resource, if you're not familiar with it, see the
[reference](https://github.com/apache/apisix-ingress-controller/blob/master/docs/CRD-specification.md#apisixroute)
for the details.
+
+```yaml
+# httpbin-route.yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixRoute
+metadata:
+ name: httpserver-route
+spec:
+ rules:
+ - host: local.httpbin.org
+ http:
+ paths:
+ - backend:
+ serviceName: httpbin
+ servicePort: 8080
+ path: /hello*
+```
+
+The YAML snippet shows a simple `ApisixRoute` configuration, which tells
Apache APISIX to route all requests with Host `local.httpbin.org` to the
`httpbin` service.
+Now try to create it.
+
+```shell
+kubectl apply -f httpbin-route.yaml
+```
+
+## Test
+
+Run curl call in one of Apache APISIX Pods to check whether the resource was
delivered to it. Note you should replace the value of `--apisix-admin-key` to
the real `admin_key` value in your Apache APISIX cluster.
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${Pod name of Apache APISIX}
-- curl http://127.0.0.1:9180/apisix/admin/routes --apisix-admin-key
edd1c9f034335f136f87ad84b625c8f1
+```
+
+And request to Apache APISIX to verify the route.
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${Pod name of Apache APISIX}
-- curl http://127.0.0.1:9080/headers -H 'Host: local.httpbin.org'
+```
+
+In case of success, you'll see a JSON string which contains all requests
headers carried by `curl` like:
+
+```json
+{
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ "User-Agent": "curl/7.64.1",
+ "X-Amzn-Trace-Id": "Root=1-5ffc3273-2928e0844e19c9810d1bbd8a"
+ }
+}
+```
