Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: API specification for CRDs #151

Merged
merged 8 commits into from
Jan 5, 2021
Merged

docs: API specification for CRDs #151

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
154c7b0
docs: API specification for CRDs.
Firstsawyou Jan 3, 2021
00fd45e
add more field explanation.
Firstsawyou Jan 4, 2021
f7fd9f3
fix ci run error.
Firstsawyou Jan 4, 2021
e6fa7e3
update doc.
Firstsawyou Jan 4, 2021
67ac14b
update docs.
Firstsawyou Jan 4, 2021
e3bdaef
docs: update doc desc.
Firstsawyou Jan 5, 2021
f3cefd3
update ApisixTLS desc.
Firstsawyou Jan 5, 2021
bf9497f
update docs desc.
Firstsawyou Jan 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 196 additions & 0 deletions docs/CRD-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
<!--
#
# 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.
#
-->

# CRD specification

In order to control the behavior of the proxy ([Apache APISIX](https://github.com/apache/apisix)), the following CRDs should be defined. Normally, you only need to use ApisixRoute to complete a simple route definition.

## CRD Types

- [ApisixRoute](#apisixroute)
- [ApisixService](#apisixservice)
- [ApisixUpstream](#apisixupstream)
- [ApisixTls](#apisixtls)

## ApisixRoute

`ApisixRoute` corresponds to the `Route` object in Apache APISIX. The `Route` matches the client's request by defining rules,
then loads and executes the corresponding plugin based on the matching result, and forwards the request to the specified Upstream.
To learn more, please check the [Apache APISIX architecture-design docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#route).

Structure example:

```yaml
apiVersion: apisix.apache.org/v1
kind: ApisixRoute
metadata:
name: httpserverRoute
namespace: cloud
spec:
rules:
- host: test.apisix.apache.org
http:
paths:
- backend:
serviceName: httpserver
servicePort: 8080
path: /hello*
plugins:
- name: limit-count
enable: true
config:
count: 2
time_window: 60
rejected_code: 503
key: remote_addr
```
Firstsawyou marked this conversation as resolved.
Show resolved Hide resolved

| Field | Type | Description |
|---------------|----------|----------------------------------------------------|
| rules | array | ApisixRoute's request matching rules. |
| host | string | The requested host. |
| http | object | Route rules are applied to the scope of layer 7 traffic. |
| paths | array | Path-based `route` rule matching. |
| backend | object | Backend service information configuration. |
| serviceName | string | The name of backend service. `namespace + serviceName + servicePort` form an unique identifier to match the back-end service. |
| servicePort | int | The port of backend service. `namespace + serviceName + servicePort` form an unique identifier to match the back-end service. |
| path | string | The URI matched by the route. Supports exact match and prefix match. Example，exact match: `/hello`, prefix match: `/hello*`. |
| plugins | array | Custom plugin collection (Plugins defined in the `route` level). For more plugin information, please refer to the [Apache APISIX plugin docs](https://github.com/apache/apisix/tree/master/doc/plugins). |
| name | string | The name of the plugin. For more information about the example plugin, please check the [limit-count docs](https://github.com/apache/apisix/blob/master/doc/plugins/limit-count.md#Attributes). |
| enable | boolean | Whether to enable the plugin, `true`: means enable, `false`: means disable. |
| config | object | Configuration of plugin information. Note: The check of configuration schema is missing now, so please be careful when editing. |

**Support partial `annotation`**

Structure example:

```yaml
apiVersion: apisix.apache.org/v1
kind: ApisixRoute
metadata:
annotations:
k8s.apisix.apache.org/ingress.class: apisix_group
k8s.apisix.apache.org/ssl-redirect: 'false'
k8s.apisix.apache.org/whitelist-source-range:
- 1.2.3.4/16
- 4.3.2.1/8
name: httpserverRoute
namespace: cloud
spec:
```

| Field | Type | Description |
|------------------------------------------------|------------|--------------------------------------------------------------------|
| `k8s.apisix.apache.org/ssl-redirect` | boolean | Whether to force http to be redirected from https. ture: means forced conversion to https, false: means no conversion. |
tokers marked this conversation as resolved.
Show resolved Hide resolved
| `k8s.apisix.apache.org/ingress.class` | string | Grouping of ingress. |
| `k8s.apisix.apache.org/whitelist-source-range` | array | Whitelist of IPs allowed to be accessed. |

## ApisixService

`ApisixService` corresponds to the `Service` object in Apache APISIX.
A `Service` is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to the upstream service abstraction. Between `Route` and `Service`, usually the relationship of N:1.
To learn more, please check the [Apache APISIX architecture-design docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#service).

Structure example:

```yaml
apiVersion: apisix.apache.org/v1
kind: ApisixService
metadata:
name: httpserver
namespace: cloud
spec:
upstream: httpserver
port: 8080
plugins:
- name: limit-count
enable: true
config:
count: 2
time_window: 60
rejected_code: 503
key: remote_addr
```

| Field | Type | Description |
|---------------|----------|----------------|
| upstream | string | The name of the upstream service. |
| port | int | The port number of the upstream service. |
| plugins | array | Custom plugin collection (Plugins defined in the `service` level). For more plugin information, please refer to the [Apache APISIX plugins docs](https://github.com/apache/apisix/tree/master/doc/plugins). |
| name | string | The name of the plugin. For more information about the example plugin, please check the [limit-count docs](https://github.com/apache/apisix/blob/master/doc/plugins/limit-count.md#Attributes). |
| enable | boolean | Whether to enable the plugin, `true`: means enable, `false`: means disable. |
| config | object | Configuration of plugin information. Note: The check of configuration schema is missing now, so please be careful when editing. |

## ApisixUpstream

`ApisixUpstream` corresponds to the `Upstream` object in Apache APISIX.
Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to configuration rules.
Upstream address information can be directly configured to `Route` (or `Service`). When Upstream has duplicates, you need to use "reference" to avoid duplication.
To learn more, please check the [Apache APISIX architecture-design docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#upstream).

Structure example:

```yaml
apiVersion: apisix.apache.org/v1
kind: ApisixUpstream
metadata:
name: httpserver
namespace: cloud
spec:
ports:
- port: 8080
loadbalancer: roundrobin
```

| Field | Type | Description |
|---------------|----------|----------------|
| ports | array | Custom upstream collection. |
| port | int | Upstream service port number. |
| loadbalancer | string/object | The load balance algorithm of this upstream service, optional value can be `roundrobin` or `chash`. |

## ApisixTls
Firstsawyou marked this conversation as resolved.
Show resolved Hide resolved

`ApisixTls` corresponds to the SSL load matching route in Apache APISIX.
`SSL` loads the matching route. (Default) Use SNI (Server Name Indication) as the primary index.
tokers marked this conversation as resolved.
Show resolved Hide resolved
To learn more, please check the [Apache APISIX architecture-design docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#router).

Structure example:

```yaml
apiVersion: apisix.apache.org/v1
kind: ApisixSSL
metadata:
name: duiopen
spec：
hosts:
- asr.duiopen.com
- tts.duiopen.com
secret:
name: all.duiopen.com
namespace: cloud
```

| Field | Type | Description |
|---------------|----------|---------------------------------|
| hosts | array | The domain list to identify which hosts (matched with SNI) can use the TLS certificate stored in the Secret. |
| secret | object | The definition of the related Secret object with current ApisixTls object. |
| name | string | The name of `secret`. `namespace` and `name` are the unique identifier to match kubernetes secret. |
| namespace | string | The namespace of `secret`. `namespace` and `name` are the unique identifier to match kubernetes secret. |

[Back to top](#crd-types)