Skip to content

README.md

Latest commit

 

History

History
99 lines (79 loc) · 4.21 KB

README.md

File metadata and controls

99 lines (79 loc) · 4.21 KB
Raw

Sample Custom Resources

This document provides a detailed explanation of the sample OpenAPIAggregator and SwaggerServer custom resources.

OpenAPIAggregator Sample

The OpenAPIAggregator custom resource tells the operator how to discover services and aggregate their OpenAPI specifications.

File: config/samples/observability_v1alpha1_openapiaggregator.yaml

apiVersion: observability.aggregator.io/v1alpha1
kind: OpenAPIAggregator
metadata:
  name: openapi-aggregator-sample
  # The namespace where this CR is created is important.
  # The generated openapi-specs ConfigMap will be created in this same namespace.
  namespace: default # Or any namespace where you want the ConfigMap
spec:
  # To watch services in the same namespace as this OpenAPIAggregator CR:
  # watchNamespaces: [] # or leave it undefined

  # To watch services in ALL namespaces (requires ClusterRole permissions for the operator):
  watchNamespaces: [""] # or ["*"]

  # Default values for service annotations if not specified on the service itself
  defaultPath: "/v2/api-docs"
  defaultPort: "8080"

  # Annotation keys used to discover and configure services
  swaggerAnnotation: "openapi.aggregator.io/swagger" # Service annotation to mark it for discovery
  pathAnnotation: "openapi.aggregator.io/path"         # Service annotation for custom OpenAPI path
  portAnnotation: "openapi.aggregator.io/port"         # Service annotation for custom OpenAPI port
  allowedMethodsAnnotation: "openapi.aggregator.io/allowed-methods" # Service annotation for allowed HTTP methods

Note on watchNamespaces:

  • If watchNamespaces is empty or not provided, the controller watches services in the same namespace as the OpenAPIAggregator CR.
  • If watchNamespaces is [""] or ["*"], the controller watches services in all namespaces. This requires the operator to have cluster-level RBAC permissions to list and watch services across all namespaces.
  • The openapi-specs ConfigMap, which stores the aggregated API information, is always created in the same namespace as the OpenAPIAggregator CR itself.

SwaggerServer Sample

The SwaggerServer custom resource deploys a Swagger UI instance to view the aggregated OpenAPI specifications.

File: config/samples/swagger-server-sample.yaml

# Sample SwaggerServer configuration for hosting the Swagger UI component
apiVersion: observability.aggregator.io/v1alpha1
kind: SwaggerServer
metadata:
  name: swagger-ui-sample
  namespace: default # Should be the same namespace as the OpenAPIAggregator CR and the openapi-specs ConfigMap
  labels:
    app: swagger-ui-sample
spec:
  # Image configuration for the Swagger UI server
  # If not specified, defaults to "ghcr.io/hellices/openapi-multi-swagger:latest".
  # image: ghcr.io/hellices/openapi-multi-swagger:latest  # Example, or leave blank for default
  imagePullPolicy: IfNotPresent
  
  # Port configuration
  port: 9090  # Default port for Swagger UI
  
  # ConfigMap reference for OpenAPI specs
  # This should match the ConfigMap generated by an OpenAPIAggregator instance in the same namespace.
  # The default name used by the OpenAPIAggregator controller is "openapi-specs".
  # If your OpenAPIAggregator CR is named "openapi-aggregator-sample", the ConfigMap will be "openapi-specs".
  configMapName: openapi-specs
  
  # Resource limits and requests
  resources:
    limits:
      cpu: "500m"
      memory: "256Mi"
    requests:
      cpu: "100m"
      memory: "128Mi"

  # WatchIntervalSeconds is the interval in seconds for the server to check for updates to the ConfigMap.
  # Defaults to "10".
  # +optional
  watchIntervalSeconds: "15"

  # LogLevel is the logging level for the Swagger UI server.
  # Valid values are: "trace", "debug", "info", "warn", "error", "fatal", "panic".
  # Defaults to "info".
  # +optional
  logLevel: "debug"

  # DevMode enables or disables development mode for the Swagger UI server, which provides more verbose logging.
  # Valid values are: "true", "false".
  # Defaults to "false".
  # +optional
  # devMode: "true"

Ensure the namespace and configMapName in the SwaggerServer spec align with your OpenAPIAggregator setup. The configMapName is hardcoded to openapi-specs in the OpenAPIAggregator controller.