Skip to content

Commit 49108b3

Browse files
LiorLiebermanLiorLieberman
committed
update documentations
1 parent 320d336 commit 49108b3

File tree

3 files changed

+60
-39
lines changed

3 files changed

+60
-39
lines changed

‎provider.md ‎PROVIDER.md

File renamed without changes.

‎README.md

+45-39
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
# Ingress to Gateway
22

3-
This project helps translate Ingress resources to Gateway API resources,
4-
specifically HTTPRoutes. This project is managed by the [Gateway
3+
Ingress2gateway helps translate Ingress resources to Gateway API resources,
4+
specifically HTTPRoutes. Ingress2gateway is managed by the [Gateway
55
API](https://gateway-api.sigs.k8s.io/) SIG-Network subproject.
66

7-
## Status
8-
9-
This project is early in the development phase and is still experimental in
10-
nature. Both bugs and breaking changes are likely.
11-
127
## Scope
138

14-
This project is primarily focused on translating Ingress resources to Gateway
15-
API resources. Some widely used annotations and/or CRDs _may_ be supported, as
16-
long as they can be translated to Gateway API directly. This project is not
17-
intended to copy annotations from Ingress to Gateway API.
9+
Ingress2gateway is primarily focused on translating Ingress and provider-specific
10+
resources(CRDs) to Gateway API resources. Widely used provider-specific annotations
11+
and/or CRDs _may_ still not be supported. Please refer to
12+
[supported providers](#current-supported-providers) for the current supported
13+
providers and their documentation. Contributions for provider-specific
14+
annotations and/or CRDs support are mostly welcomed as long as they can be
15+
translated to [Gateway API](https://gateway-api.sigs.k8s.io/) directly.
16+
17+
Note: Ingress2gateway is not intended to copy annotations from Ingress to Gateway API.
1818

1919
## Build from Source
2020

@@ -34,15 +34,27 @@ make build
3434

3535
## Usage
3636

37-
This project reads Ingress resources from a Kubernetes cluster based on your
38-
current Kube Config. It will output YAML for equivalent Gateway API resources
39-
to stdout. Until this project is released, the best way to use this is to run
40-
the following within the repo:
37+
Ingress2gateway reads Ingress resources and/or provider-specifc CRDs from a Kubernetes cluster or a file. It will output the equivalent Gateway API resources in a YAML/JSON format
38+
to stdout. To run ingress2gateway with default options simply run:
4139

4240
```
43-
go run . print
41+
ingress2gateway print
4442
```
4543

44+
This above command will:
45+
1. Read your Kube config file to extract the cluster connection and the current-active namespace.
46+
2. Search for ingresses and for provider specific resources in that namespace.
47+
3. Convert them to Gateway-API resources (Currently only Gateways and HTTPRoutes).
48+
49+
## Options
50+
51+
| Flag | Default Value | Required | Description |
52+
| ----------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
53+
| namespace | | No | If present, the namespace scope for the invocation |
54+
| all-namespaces | False | No | If present, list the requested object(s) across all namespaces. Namespace in the current context is ignored even if specified with --namespace |
55+
| output | yaml | No | The output format, either yaml or json |
56+
| input_file | | No | Path to the manifest file. When set, the tool will read ingresses from the file instead of reading from the cluster. Supported files are yaml and json |
57+
4658
## Conversion of Ingress resources to Gateway API
4759

4860
### Processing Order and Conflicts
@@ -61,35 +73,29 @@ These rules are similar to the [Gateway API conflict resolution guidelines](http
6173

6274
Given a set of Ingress resources, `ingress2gateway` will generate a Gateway with various HTTP and HTTPS Listeners as well as HTTPRoutes that should represent equivalent routing rules.
6375

64-
| Ingress Field | Gateway API configuration |
65-
|---------------|---------------------------|
66-
| `ingressClassName` | If configured on an Ingress resource, this value will be used as the `gatewayClassName` set on the corresponding generated Gateway. |
67-
| `defaultBackend` | If present, this configuration will generate a Gateway Listener with no `hostname` specified as well as a catchall HTTPRoute that references this listener. The backend specified here will be translated to a HTTPRoute `rules[].backendRefs[]` element. |
68-
| `tls[].hosts` | Each host in an IngressTLS will result in a HTTPS Listener on the generated Gateway with the following: `listeners[].hostname` = host as described, `listeners[].port` = `443`, `listeners[].protocol` = `HTTPS`, `listeners[].tls.mode` = `Terminate` |
69-
| `tls[].secretName` | The secret specified here will be referenced in the Gateway HTTPS Listeners mentioned above with the field `listeners[].tls.certificateRefs`. Each Listener for each host in an IngressTLS will get this secret. |
70-
| `rules[].host` | If non-empty, each distinct value for this field in the provided Ingress resources will result in a separate Gateway HTTP Listener with matching `listeners[].hostname`. `listeners[].port` will be set to `80` and `listeners[].protocol` set to `HTTPS`. In addition, Ingress rules with the same hostname will generate HTTPRoute rules in a HTTPRoute with `hostnames` containing it as the single element. If empty, similar to the `defaultBackend`, a Gateway Listener with no hostname configuration will be generated (if it doesn't exist) and routing rules will be generated in a catchall HTTPRoute. |
71-
| `rules[].http.paths[].path` | This field translates to a HTTPRoute `rules[].matches[].path.value` configuration. |
72-
| `rules[].http.paths[].pathType` | This field translates to a HTTPRoute `rules[].matches[].path.type` configuration. Ingress `Exact` = HTTPRoute `Exact` match. Ingress `Prefix` = HTTPRoute `PathPrefix` match. |
73-
| `rules[].http.paths[].backend` | The backend specified here will be translated to a HTTPRoute `rules[].backendRefs[]` element. |
76+
| Ingress Field | Gateway API configuration |
77+
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78+
| `ingressClassName` | If configured on an Ingress resource, this value will be used as the `gatewayClassName` set on the corresponding generated Gateway. `kubernetes.io/ingress.class` annotation has the same behavior. |
79+
| `defaultBackend` | If present, this configuration will generate a Gateway Listener with no `hostname` specified as well as a catchall HTTPRoute that references this listener. The backend specified here will be translated to a HTTPRoute `rules[].backendRefs[]` element. |
80+
| `tls[].hosts` | Each host in an IngressTLS will result in a HTTPS Listener on the generated Gateway with the following: `listeners[].hostname` = host as described, `listeners[].port` = `443`, `listeners[].protocol` = `HTTPS`, `listeners[].tls.mode` = `Terminate` |
81+
| `tls[].secretName` | The secret specified here will be referenced in the Gateway HTTPS Listeners mentioned above with the field `listeners[].tls.certificateRefs`. Each Listener for each host in an IngressTLS will get this secret. |
82+
| `rules[].host` | If non-empty, each distinct value for this field in the provided Ingress resources will result in a separate Gateway HTTP Listener with matching `listeners[].hostname`. `listeners[].port` will be set to `80` and `listeners[].protocol` set to `HTTPS`. In addition, Ingress rules with the same hostname will generate HTTPRoute rules in a HTTPRoute with `hostnames` containing it as the single element. If empty, similar to the `defaultBackend`, a Gateway Listener with no hostname configuration will be generated (if it doesn't exist) and routing rules will be generated in a catchall HTTPRoute. |
83+
| `rules[].http.paths[].path` | This field translates to a HTTPRoute `rules[].matches[].path.value` configuration. |
84+
| `rules[].http.paths[].pathType` | This field translates to a HTTPRoute `rules[].matches[].path.type` configuration. Ingress `Exact` = HTTPRoute `Exact` match. Ingress `Prefix` = HTTPRoute `PathPrefix` match. |
85+
| `rules[].http.paths[].backend` | The backend specified here will be translated to a HTTPRoute `rules[].backendRefs[]` element. |
86+
87+
### Provider-Specific Support
7488

75-
### Implementation-Specific Annotations
89+
Ingress2gateway also supports translating provider-specific resources and ingress annotations to Gateway-API resources.
7690

77-
Although most annotations are ignored, this project includes experimental
78-
support for the following annotations:
91+
#### Current supported providers:
7992

80-
* kubernetes.io/ingress.class: Same behavior as the `ingressClassName` field above, if specified this value will be used as the `gatewayClassName` set on the corresponding generated Gateway.
93+
- [ingress-nginx](pkg/i2gw/providers/ingressnginx/README.md)
8194

82-
#### ingress-nginx:
95+
If your provider is not currently supported, please feel free to open an issue and provide a description of your use case.
8396

84-
* nginx.ingress.kubernetes.io/canary: If set to `true` will enable weighting backends.
85-
* nginx.ingress.kubernetes.io/canary-by-header: If specified, the value of this annotation is the header name that will be added as a HTTPHeaderMatch for the routes generated from this Ingress. If not specified, no HTTPHeaderMatch will be generated.
86-
* nginx.ingress.kubernetes.io/canary-by-header-value: If specified, the value of this annotation is the header value to perform an `HeaderMatchExact` match on in the generated HTTPHeaderMatch.
87-
* nginx.ingress.kubernetes.io/canary-by-header-pattern: If specified, this is the pattern to match against for the HTTPHeaderMatch, which will be of type `HeaderMatchRegularExpression`.
88-
* nginx.ingress.kubernetes.io/canary-weight: If specified and non-zero, this value will be applied as the weight of the backends for the routes generated from this Ingress resource.
89-
* nginx.ingress.kubernetes.io/canary-weight-total
97+
To contribute a new provider support - please read [PROVIDER.md](PROVIDER.md).
9098

91-
If you are reliant on any annotations not listed above, you'll need to manually
92-
find a Gateway API equivalent.
9399

94100
## Get Involved
95101

‎pkg/i2gw/providers/ingressnginx/README.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Ingress Nginx Provider
2+
3+
The project supports translating ingress-nginx specific annotations.
4+
5+
Current supported annotations:
6+
7+
- `nginx.ingress.kubernetes.io/canary`: If set to true will enable weighting backends.
8+
- `nginx.ingress.kubernetes.io/canary-by-header`: If specified, the value of this annotation is the header name that will be added as a HTTPHeaderMatch for the routes
9+
- generated from this Ingress. If not specified, no HTTPHeaderMatch will be generated.
10+
- `nginx.ingress.kubernetes.io/canary-by-header-value`: If specified, the value of this annotation is the header value to perform an HeaderMatchExact match on in the generated HTTPHeaderMatch.
11+
- `nginx.ingress.kubernetes.io/canary-by-header-pattern`: If specified, this is the pattern to match against for the HTTPHeaderMatch, which will be of type HeaderMatchRegularExpression.
12+
- `nginx.ingress.kubernetes.io/canary-weight`: If specified and non-zero, this value will be applied as the weight of the backends for the routes generated from this Ingress resource.
13+
`nginx.ingress.kubernetes.io/canary-weight-total`
14+
15+
If you are reliant on any annotations not listed above, please open an issue. In the meantime you'll need to manually find a Gateway API equivalent.

0 commit comments

Comments
 (0)