openapi3

README

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.

Documentation

Index

• Constants
• func NewProvider(conf *i2gw.ProviderConf) i2gw.Provider
• type Converter
  • func NewConverter(conf *i2gw.ProviderConf) Converter
• type Provider
  • func (p *Provider) ReadResourcesFromCluster(_ context.Context) error
  • func (p *Provider) ReadResourcesFromFile(ctx context.Context, filename string) error
  • func (p *Provider) ToGatewayAPI() (i2gw.GatewayResources, field.ErrorList)
• type Storage
  • func NewResourceStorage() Storage

Constants

const (
	HostWildcard   = "*"
	HostSeparator  = ","
	ParamSeparator = ","

	HTTPRouteRulesMax      = 16
	HTTPRouteMatchesMax    = 8
	HTTPRouteMatchesMaxMax = HTTPRouteRulesMax * HTTPRouteMatchesMax
)

const (
	// The ProviderName returned to the provider's registry.
	ProviderName = "openapi3"

	BackendFlag      = "backend"
	GatewayClassFlag = "gateway-class-name"
	TLSSecretFlag    = "gateway-tls-secret" //nolint:gosec
)

Functions

func NewProvider

func NewProvider(conf *i2gw.ProviderConf) i2gw.Provider

NewProvider returns an implementation of i2gw.Provider that converts OpenAPI specs to Gateway API resources.

Types

type Converter

type Converter interface {
	Convert(Storage) (i2gw.GatewayResources, field.ErrorList)
}

func NewConverter

func NewConverter(conf *i2gw.ProviderConf) Converter

NewConverter returns a converter of OpenAPI Specifications 3.x from a storage into Gateway API resources.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

func (*Provider) ReadResourcesFromCluster

func (p *Provider) ReadResourcesFromCluster(_ context.Context) error

ReadResourcesFromCluster reads OpenAPI specs stored in the Kubernetes cluster. UNIMPLEMENTED.

func (*Provider) ReadResourcesFromFile

func (p *Provider) ReadResourcesFromFile(ctx context.Context, filename string) error

ReadResourcesFromFile reads OpenAPI specs from a JSON or YAML file.

func (*Provider) ToGatewayAPI

func (p *Provider) ToGatewayAPI() (i2gw.GatewayResources, field.ErrorList)

ToGatewayAPI converts stored OpenAPI specs to Gateway API resources.

type Storage

type Storage interface {
	AddResource(resource *openapi3.T)
	GetResources() []*openapi3.T
	Clear()
}

func NewResourceStorage

func NewResourceStorage() Storage

NewResourceStorage returns a thread-safe storage for OpenAPI specs.