Skip to content

Latest commit

 

History

History
334 lines (305 loc) · 9.04 KB

README.md

File metadata and controls

334 lines (305 loc) · 9.04 KB
Raw

OpenAPI Provider

The provider translates OpenAPI Specification (OAS) 3.x documents to Kubernetes Gateway API resources – Gateway, HTTPRoutes and ReferenceGrants.

Usage

./ingress2gateway print --providers=openapi3 --input-file=FILEPATH

Where FILEPATH is the path to a file containing a valid OpenAPI Specification in YAML or JSON format.

Gateway class name

To specify the name of the gateway class for the Gateway resources, use --openapi3-gateway-class-name=NAME.

Gateways with TLS configuration

If one or more servers specified in the OAS start with https, TLS configuration will be added to the corresponding gateway listener.

To specify the reference to the gateway TLS secret, use --openapi3-gateway-tls-secret=SECRET-NAME or --openapi3-gateway-tls-secret=SECRET-NAMESPACE/SECRET-NAME.

Backend references

All routes generated will point to a single backend service.

To specify the backend reference, use --openapi3-backend=[namespace/]name[:port]. Examples of valid values:

  • my-service
  • my-namespace/my-service
  • my-service:3000
  • my-namespace/my-service:3000

Resource names

Gateway and HTTPRoute names are prefixed with the title of the OAS converted to Kubernetes object name format.

In case of multiple resources of a kind, the names are suffixed with the corresponding sequential number from 1.

In all cases, ensure the title of the OAS is not long enough that would cause invalid Kubernetes object names.

Examples

The examples below are based on the Swagger Petstore Sample API.

./ingress2gateway print --providers=openapi3 \
                        --openapi3-gateway-class-name=istio \
                        --openapi3-backend=my-app:3000 \
                        --input-file=petstore3-openapi.json
Expected output 
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  creationTimestamp: null
  name: swagger-petstore-openapi-3-0-gateway
  namespace: default
spec:
  gatewayClassName: istio
  listeners:
  - hostname: '*'
    name: http
    port: 80
    protocol: HTTP
status: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  creationTimestamp: null
  name: swagger-petstore-openapi-3-0-route
  namespace: default
spec:
  parentRefs:
  - name: swagger-petstore-openapi-3-0-gateway
  rules:
  - backendRefs:
    - name: my-app
      port: 3000
    matches:
    - method: POST
      path:
        type: Exact
        value: /api/v3/pet
    - method: PUT
      path:
        type: Exact
        value: /api/v3/pet
    - method: GET
      path:
        type: Exact
        value: /api/v3/pet/findByStatus
    - method: GET
      path:
        type: Exact
        value: /api/v3/pet/findByTags
    - method: DELETE
      path:
        type: Exact
        value: /api/v3/pet/{petId}
    - method: GET
      path:
        type: Exact
        value: /api/v3/pet/{petId}
    - method: POST
      path:
        type: Exact
        value: /api/v3/pet/{petId}
    - method: POST
      path:
        type: Exact
        value: /api/v3/pet/{petId}/uploadImage
  - backendRefs:
    - name: my-app
      port: 3000
    matches:
    - method: GET
      path:
        type: Exact
        value: /api/v3/store/inventory
    - method: POST
      path:
        type: Exact
        value: /api/v3/store/order
    - method: DELETE
      path:
        type: Exact
        value: /api/v3/store/order/{orderId}
    - method: GET
      path:
        type: Exact
        value: /api/v3/store/order/{orderId}
    - method: POST
      path:
        type: Exact
        value: /api/v3/user
    - method: POST
      path:
        type: Exact
        value: /api/v3/user/createWithList
    - method: GET
      path:
        type: Exact
        value: /api/v3/user/login
    - method: GET
      path:
        type: Exact
        value: /api/v3/user/logout
  - backendRefs:
    - name: my-app
      port: 3000
    matches:
    - method: DELETE
      path:
        type: Exact
        value: /api/v3/user/{username}
    - method: GET
      path:
        type: Exact
        value: /api/v3/user/{username}
    - method: PUT
      path:
        type: Exact
        value: /api/v3/user/{username}
status:
  parents: null

ReferenceGrants are only generated if a namespace is specified and/or the references to gateway TLS secrets or backends do not match the target namespace, which can occasionally unspecified. E.g.:

./ingress2gateway print --providers=openapi3 \
                        --namespace=networking \
                        --openapi3-gateway-class-name=istio \
                        --openapi3-backend=apps/my-app \
                        --input-file=petstore3-openapi.json
Expected output 
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  creationTimestamp: null
  name: swagger-petstore-openapi-3-0-gateway
  namespace: networking
spec:
  gatewayClassName: istio
  listeners:
  - hostname: '*'
    name: http
    port: 80
    protocol: HTTP
status: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  creationTimestamp: null
  name: swagger-petstore-openapi-3-0-route
  namespace: networking
spec:
  parentRefs:
  - name: swagger-petstore-openapi-3-0-gateway
  rules:
  - backendRefs:
    - name: my-app
      namespace: apps
    matches:
    - method: POST
      path:
        type: Exact
        value: /api/v3/pet
    - method: PUT
      path:
        type: Exact
        value: /api/v3/pet
    - method: GET
      path:
        type: Exact
        value: /api/v3/pet/findByStatus
    - method: GET
      path:
        type: Exact
        value: /api/v3/pet/findByTags
    - method: DELETE
      path:
        type: Exact
        value: /api/v3/pet/{petId}
    - method: GET
      path:
        type: Exact
        value: /api/v3/pet/{petId}
    - method: POST
      path:
        type: Exact
        value: /api/v3/pet/{petId}
    - method: POST
      path:
        type: Exact
        value: /api/v3/pet/{petId}/uploadImage
  - backendRefs:
    - name: my-app
      namespace: apps
    matches:
    - method: GET
      path:
        type: Exact
        value: /api/v3/store/inventory
    - method: POST
      path:
        type: Exact
        value: /api/v3/store/order
    - method: DELETE
      path:
        type: Exact
        value: /api/v3/store/order/{orderId}
    - method: GET
      path:
        type: Exact
        value: /api/v3/store/order/{orderId}
    - method: POST
      path:
        type: Exact
        value: /api/v3/user
    - method: POST
      path:
        type: Exact
        value: /api/v3/user/createWithList
    - method: GET
      path:
        type: Exact
        value: /api/v3/user/login
    - method: GET
      path:
        type: Exact
        value: /api/v3/user/logout
  - backendRefs:
    - name: my-app
      namespace: apps
    matches:
    - method: DELETE
      path:
        type: Exact
        value: /api/v3/user/{username}
    - method: GET
      path:
        type: Exact
        value: /api/v3/user/{username}
    - method: PUT
      path:
        type: Exact
        value: /api/v3/user/{username}
status:
  parents: null
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  creationTimestamp: null
  name: from-networking-to-service-my-app
  namespace: apps
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: networking
  to:
  - group: ""
    kind: Service
    name: my-app

Limitations

  • Only offline translation supported – i.e. --input-file is required
  • An input file can only declare one OpenAPI Specification
  • All API operation paths are treated as Exact type – i.e. no support for path templating, therefore no PathPrefix, nor RegularExpression path types output
  • Limited support for parameters – only required header and query parameters supported
  • Limited support to server variables – only limited sets (enum) supported
  • No support to references ($ref)
  • No support to external documents
  • OpenAPI Specification with a large number of server combinations may generate Gateway resources with more listeners than allowed

Additionally, no support to any OpenAPI feature with no direct equivalent to core Gateway API fields, such as request bodies, examples, security schemes, callbacks, extensions, etc.