Skip to content

Commit

Permalink
chore: README updated (#161)
Browse files Browse the repository at this point in the history 
Signed-off-by: Mattia Lavacca <[email protected]>
  • Loading branch information
@mlavacca
mlavacca authored Jun 15, 2024
1 parent 4d67e59 commit 36c89f3
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 43 deletions.
96 changes: 56 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,43 @@ API](https://gateway-api.sigs.k8s.io/) SIG-Network subproject.
Ingress2gateway is primarily focused on translating Ingress and provider-specific
resources(CRDs) to Gateway API resources. Widely used provider-specific annotations
and/or CRDs _may_ still not be supported. Please refer to
[supported providers](#current-supported-providers) for the current supported
[supported providers](#supported-providers) for the current supported
providers and their documentation. Contributions for provider-specific
annotations and/or CRDs support are mostly welcomed as long as they can be
translated to [Gateway API](https://gateway-api.sigs.k8s.io/) directly.

Note: Ingress2gateway is not intended to copy annotations from Ingress to Gateway API.
> **Note:** Ingress2gateway is not intended to copy annotations from Ingress to Gateway
API.

## Supported providers

* [apisix](pkg/i2gw/providers/apisix/README.md)
* [ingress-nginx](pkg/i2gw/providers/ingressnginx/README.md)
* [istio](pkg/i2gw/providers/istio/README.md)
* [gce](pkg/i2gw/providers/gce/README.md)
* [kong](pkg/i2gw/providers/kong/README.md)
* [openapi](pkg/i2gw/providers/openapi3/README.md)

If your provider, or a specific feature, is not currently supported, please open
an issue and describe your use case.

To contribute a new provider support - please read [PROVIDER.md](PROVIDER.md).

## Installation

If you have a Go development environment locally, you can install ingress2gateway with `go install github.com/kubernetes-sigs/[email protected]`
### Via go install

If you have a Go development environment locally, you can install ingress2gateway
with `go install github.com/kubernetes-sigs/[email protected]`

This will put `ingress2gateway` binary in `$(go env GOPATH)/bin`

Alternatively, you can download the binary at the [releases page](https://github.com/kubernetes-sigs/ingress2gateway/releases)

### On macOS and linux via Homebrew:
### On macOS and linux via Homebrew

Make sure Homebrew is installed on your system.

```shell
brew install ingress2gateway
```
Expand All @@ -34,8 +54,11 @@ brew install ingress2gateway

1. Ensure that your system meets the following requirements:

- Install Git: Make sure Git is installed on your system to clone the project repository.
- Install Go: Make sure the go language is installed on your system. You can download it from the official website (https://golang.org/dl/) and follow the installation instructions.
* Install Git: Make sure Git is installed on your system to clone the project
repository.
* Install Go: Make sure the go language is installed on your system. You can
download it from the official website (https://golang.org/dl/) and follow the
installation instructions.

1. Clone the project repository

Expand All @@ -51,15 +74,18 @@ brew install ingress2gateway

## Usage

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
to stdout. To run ingress2gateway with default options simply run:
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 to stdout. To run ingress2gateway with default options simply run:

```shell
./ingress2gateway print
```

This above command will:
1. Read your Kube config file to extract the cluster credentials and the current active namespace.
The above command will:

1. Read your Kube config file to extract the cluster credentials and the current
active namespace.
1. Search for ingresses and provider-specific resources in that namespace.
1. Convert them to Gateway-API resources (Currently only Gateways and HTTPRoutes).

Expand All @@ -69,30 +95,40 @@ This above command will:

| Flag | Default Value | Required | Description |
| -------------- | ----------------------- | -------- | ------------------------------------------------------------ |
| namespace | | No | If present, the namespace scope for the invocation. |
| 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. |
| output | yaml | No | The output format, either yaml or json. |
| 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. |
| namespace | | No | If present, the namespace scope for the invocation. |
| openapi3-backend | | No | Provider-specific: openapi3. The name of the backend service to use in the HTTPRoutes. |
| openapi3-gateway-class-name | | No | Provider-specific: openapi3. The name of the gateway class to use in the Gateways. |
| openapi3-gateway-tls-secret | | No | Provider-specific: openapi3. The name of the secret for the TLS certificate references in the Gateways. |
| output | yaml | No | The output format, either yaml or json. |
| providers | all supported providers | No | Comma-separated list of providers. If present, the tool will try to convert only resources related to the specified providers. Otherwise it will default to all the supported providers. |
| kubeconfig | | No | The kubeconfig file to use when talking to the cluster. If the flag is not set, a set of standard locations can be searched for an existing kubeconfig file. |

## Conversion of Ingress resources to Gateway API

### Processing Order and Conflicts

Ingress resources will be processed with a defined order to ensure deterministic generated Gateway API configuration.
This should also determine precedence order of Ingress resources and routes in case of conflicts.
Ingress resources will be processed with a defined order to ensure deterministic
generated Gateway API configuration.
This should also determine precedence order of Ingress resources and routes in case
of conflicts.

Ingress resources with the oldest creation timestamp will be sorted first and therefore given precedence.
If creation timestamps are equal, then sorting will be done based on the namespace/name of the resources.
If an Ingress rule conflicts with another (e.g. same path match but different backends) an error will be reported for the one that sorted later.
Ingress resources with the oldest creation timestamp will be sorted first and therefore
given precedence. If creation timestamps are equal, then sorting will be done based
on the namespace/name of the resources. If an Ingress rule conflicts with another
(e.g. same path match but different backends) an error will be reported for the
one that sorted later.

Since the Ingress v1 spec does not itself have a conflict resolution guide, we have adopted this one.
These rules are similar to the [Gateway API conflict resolution guidelines](https://gateway-api.sigs.k8s.io/concepts/guidelines/#conflicts).
Since the Ingress v1 spec does not itself have a conflict resolution guide, we have
adopted this one. These rules are similar to the [Gateway API conflict resolution
guidelines](https://gateway-api.sigs.k8s.io/concepts/guidelines/#conflicts).

### Ingress resource fields to Gateway API fields

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.
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.

| Ingress Field | Gateway API configuration |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -105,23 +141,6 @@ Given a set of Ingress resources, `ingress2gateway` will generate a Gateway with
| `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. |
| `rules[].http.paths[].backend` | The backend specified here will be translated to a HTTPRoute `rules[].backendRefs[]` element. |

### Provider-Specific Support

Ingress2gateway also supports translating provider-specific resources and ingress annotations to Gateway-API resources.

#### Current supported providers:

- [ingress-nginx](pkg/i2gw/providers/ingressnginx/README.md)
- [kong](pkg/i2gw/providers/kong/README.md)
- [istio](pkg/i2gw/providers/istio/README.md)
- [apisix](pkg/i2gw/providers/apisix/README.md)
- [gce](pkg/i2gw/providers/gce/README.md)

If your provider, or a specific feature, is not currently supported, please open an issue and describe your use case.

To contribute a new provider support - please read [PROVIDER.md](PROVIDER.md).


## Get Involved

This project will be discussed in the same Slack channel and community meetings
Expand All @@ -132,6 +151,3 @@ as the rest of the Gateway API subproject. For more information, refer to the

Participation in the Kubernetes community is governed by the [Kubernetes Code of
Conduct](code-of-conduct.md).

[owners]: https://git.k8s.io/community/contributors/guide/owners.md
[Creative Commons 4.0]: https://git.k8s.io/website/LICENSE
6 changes: 3 additions & 3 deletions pkg/i2gw/providers/openapi3/openapi.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,17 +40,17 @@ func init() {

i2gw.RegisterProviderSpecificFlag(ProviderName, i2gw.ProviderSpecificFlag{
Name: BackendFlag,
Description: "The name of the backend service to use in the HTTPRoutes",
Description: "The name of the backend service to use in the HTTPRoutes.",
})

i2gw.RegisterProviderSpecificFlag(ProviderName, i2gw.ProviderSpecificFlag{
Name: GatewayClassFlag,
Description: "The name of the gateway class to use in the Gateways",
Description: "The name of the gateway class to use in the Gateways.",
})

i2gw.RegisterProviderSpecificFlag(ProviderName, i2gw.ProviderSpecificFlag{
Name: TLSSecretFlag,
Description: "The name of the secret for the TLS certificate references in the Gateways",
Description: "The name of the secret for the TLS certificate references in the Gateways.",
})
}

Expand Down

0 comments on commit 36c89f3

Please sign in to comment.