Manage APIs from CRDs

This page demonstrates how to manage and publish an API with CRDs (Custom Resource Definitions).

This is a more advanced topic and requires deeper knowledge of Kubernetes!

Introduction¶

In Traefik Hub, you can manage APIs through Custom Resource Definitions.

This enables full GitOps automation for API management like publishing of APIs, setting permissions, creating API Gateways and Portals.

Publishing an API requires the following CRDs.

• API
• APIAccess
• APIGateway
• APIPortal

Custom Resource Definitions¶

See the detailed reference guide, below, to learn more about CRD configurations related to API management.

API¶

This CRD binds an API specification to a service that implements it.

Example

---
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: customer-api
  namespace: apps
  labels:
    area: customers
    module: crm
spec:
  pathPrefix: "/customers"
  service:
    name: customer-app
    port:
      number: 3000
    openApiSpec:
      path: /openapi.yaml
      port:
        number: 3000

metadata.labels

Labels and Selectors are used by API Access and API Collections to select APIs with APIAccess.Spec.apiSelector and APICollection.Spec.apiSelector respectively.

Path prefix¶

Required

spec.pathPrefix

The path prefix of the API, for example /customers.

The path prefix will append the URL of the API Gateway.

For example, if the URL of the Gateway is api.example.com, the prefix /customers will be added, resulting in the URL api.example.com/customers.

Name¶

Required

spec.service.name

Name of the service.
This must be an IANA_SVC_NAME (following RFC6335).

Port¶

Required

spec.service.port.number

Defines the port of the Kubernetes service defined in spec.service.name.

OpenAPI¶

Path¶

spec.service.openApiSpec.path

• YAML and JSON are supported file formats for OpenAPI files
• Can be part of a service (/openapi.yaml), or a URL, pointing to a valid OpenAPI file

Port¶

Not required for external URLs

spec.service.openApiSpec.port.number

In most cases, the same as spec.service.port.number.

APIAccess¶

This CRD binds which APIs are made available with who can access them.

With the usage of Label selectors, it is possible to configure access to APIs and collections.

It is possible to use apiCollectionSelector and apiSelector together.

spec:
  // no apiSelector

spec:
  apiSelector: {}

spec:
  apiSelector:
    key: value

The example below configures different access levels depending on Label selectors for multiple APIs and API collections.

Example

---
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: customer-admin
spec:
  groups:
    - ignored-atm
  apiSelector:
    matchLabels:
      area: customers

---
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: crm-apis
spec:
  groups:
    - ignored-atm
  apiSelector:
    matchLabels:
      module: crm

---
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: crm-collections
spec:
  groups:
    - crm-group
  apiCollectionSelector:
    matchLabels:
      module: crm

Groups¶

Required

spec.groups

Name of the user group with permissions for this API.

API collection selector¶

spec.apiCollectionSelector.matchLabels

Select an API collection by matching labels, for example crm.

In the example above, all user who are part of the group /crm-group will have access to all APIs with the matching label crm.

spec.apiCollectionSelector.matchExpressions

Labels and Selectors are used for adding APIAccess groups to APIs.

API selector¶

spec.apiSelector

Select one or multiple APIs based on labels.

It is possible to use Kubernetes Labels and Selectors for more fine-grained settings.

APIGateway¶

This CRD configures an end point where APIs provided by an API Access object should be available.

In Traefik Hub, an API Gateway is the main entry point to all your APIs. This is where you define the public domains for your APIs and which APIs and API collections you want to expose via an API Access.

To publish an API, the API must be present in an API Access policy and have an API Gateway endpoint.

Example

---
apiVersion: hub.traefik.io/v1alpha1
kind: APIGateway
metadata:
  name: my-gateway
  labels:
    area: crm
spec:
  apiAccesses:
    - customer-admin
    - crm-collections
    - crm-apis
    - custom-pick
  customDomains:
    - api.example.com
    - www.api.example.com

API Access¶

Required

spec.apiAccesses

List of allowed API Accesses for the Gateway.

Custom Domains¶

spec.customDomains

Configure custom domain name for the API Gateway, for example api.example.com.

This is an optional setting, if not configured, Traefik Hub will generate a random domain under the traefikhub.io namespace.

APIPortal¶

This CRD configures an API portal in Traefik Hub.

In Traefik Hub, the API Portal is the landing page for consumers of APIs or API collections. In the Portal, the consumer can view a representation of the OpenAPI specification and effortlessly interact and try out every API operation.

Example

---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: my-api-portal
spec:
  title: "The Portal"
  description: "The Ultimate Portal NG Digital Deluxe Edition"
  apiGateway: my-gateway
  customDomains:
    - "dev.example.com"

Description¶

spec.title

Name of the API Portal, for example The Portal.

spec.description

Description of the API Portal, for example my-api-portal.

Required

Gateway¶

spec.apiGateway

Name of the APIGateway used by the Portal.

Custom Domains¶

spec.customDomains

Configure custom domain name for the API Portal, for example dev.example.com.

This is an optional setting, if not configured, Traefik Hub will generate a random domain under the traefikhub.io namespace.

APICollection¶

This CRD configures API collections.

Collections are used to logically group APIs based on their labels.

Example

apiVersion: hub.traefik.io/v1alpha1
kind: APICollection
metadata:
  name: crm-all
  labels:
    module: crm
spec:
  pathPrefix: "/crm"
  apiSelector:
    matchLabels:
      module: crm

PathPrefix¶

spec.pathPrefix

PathPrefix used by the collection, for example /crm.

The PathPrefix will append the URL of the API Gateway.

This would make the API collection accessible under api.example.com/crm.

Labels¶

Select APIs multiple APIs based on Labels and selectors.

spec.apiSelector.matchLabels

For example

apiSelector:
  matchLabels:
    module: crm

spec.apiCollectionSelector.matchExpressions

For example

apiSelector:
  matchExpressions:
    - key: area
      operator: In
      values:
        - flights
        - support

What's next¶

• Follow the tutorial about publishing APIs from CRDs