apiOperatorIstio module

Kubernetes Kong API Lifecycle Management Operator for ODA API Custom Resources.

This module is part of the ODA Canvas, specifically tailored for environments adopting the Kong API Gateway. It utilizes the Kopf Kubernetes operator framework (https://kopf.readthedocs.io/) to manage API custom resources. The operator is designed to seamlessly integrate with the Kong API Gateway, facilitating the creation and management of HTTPRoute configurations to expose APIs.

Key Features: * Automatically handles the lifecycle of ODA APIs including creation, update, and deletion of corresponding HTTPRoute resources to expose APIs through Kong. * Manages KongPlugin resources to apply and enforce various plugins and policies on APIs routed through Kong. * Configures an API gateway to act as a front aligning with recommended production architectures.

Usage: This operator can be deployed as part of the ODA Canvas in Kubernetes clusters where the Kong API Gateway is used to expose APIs. It simplifies the management of API exposure and security by interfacing directly with Kong, providing a robust and scalable API management solution.

apiOperatorKong.manage_api_lifecycle(spec, name, namespace, status, meta, logger, **kwargs)

Handles the lifecycle events (creation and updates) for API resources. This function creates or updates HTTPRoute based on the provided spec, and manages associated plugins like rate limiting, API key verification, and CORS settings based on their enabled status along with check file path if plugin are provided in form on template. It also updates the HTTPRoute with annotations corresponding to the plugins applied.

Parameters:

spec (dict): The specification dictionary containing settings like path, plugins configuration etc. name (str): The name of the resource triggering this handler. namespace (str): The Kubernetes namespace where the resource resides. meta (dict): Metadata dictionary containing information eg. uid which is useful for managing resources. logger (logging.Logger): Logger instance for logging information or errors. kwargs: Arbitrary keyword arguments which might include additional context needed for plugins.

Returns:

Nothing

apiOperatorKong.create_or_update_ingress(spec, name, namespace, meta, **kwargs)

Creates or updates an HTTPRoute for the given API resource. It configures the route based on the specified path and attaches it to defined service. The function also manages Kubernetes ownership metadata to ensure resources are cleaned up appropriately when the parent resource is deleted. see kopf.adopt()

Parameters:

spec (dict): The specification dictionary which should contain the path and other related settings. name (str): The name of the resource. namespace (str): The namespace where the HTTPRoute will be created or updated. meta (dict): Metadata about the resource, used to set ownership in Kubernetes. kwargs: Arbitrary keyword arguments, typically unused but available for future extensions.

Returns:

True if the HTTPRoute was successfully created or updated, False otherwise.

apiOperatorKong.manage_ratelimit(spec, name, namespace, meta, **kwargs)

Configures a rate limiting plugin for an API if rate limiting is enabled in the spec. It creates or updates the plugin configuration in the specified namespace.

Parameters:

spec (dict): The specification dictionary containing rate limiting configuration details. name (str): The name of the API resource. namespace (str): The Kubernetes namespace where the plugin will be configured. meta (dict): Metadata containing information eg. uid . kwargs: Arbitrary keyword arguments, used for logging or other contextual operations.

Returns:

str or None: The name of the authentication plugin on success, or None if the setup is skipped

apiOperatorKong.manage_apiauthentication(spec, name, namespace, meta, **kwargs)

Configures or updates an API authentication plugin (JWT) , for the specified API resource based on its specification. This is configured and tested as per CE version of kong. If using paid version ,can use template option to pass authenication plugin yaml and authentication will be configured on route.

This function checks if API key verification (authentication) is enabled and sets up or updates the JWT plugin accordingly. The function also handles the lifecycle of the plugin, ensuring it is properly adopted and managed within the Kubernetes environment.

Parameters:

spec (dict): The specification dictionary containing the API key verification settings. name (str): The name of the API resource. namespace (str): The Kubernetes namespace where the plugin will be configured. meta (dict): Metadata about the resource. kwargs: Arbitrary keyword arguments, primarily used for additional logging or context.

Returns:

str or None: The name of the authentication plugin on success, or None if the setup is skipped.

Raises:

ApiException: An error from the Kubernetes API if the plugin update or creation fails.

apiOperatorKong.manage_cors(spec, name, namespace, meta, **kwargs)

Manages the creation or update of a CORS (Cross-Origin Resource Sharing) configuration for an API.

This function sets up or updates a CORS plugin based on the CORS settings specified in the API resource’s spec. It checks if CORS is enabled and configures the KongPlugin accordingly, handling its lifecycle within the Kubernetes environment.

Parameters:

spec (dict): The specification dictionary containing CORS configuration. name (str): The name of the API resource. namespace (str): The Kubernetes namespace where the plugin will be configured. meta (dict): Metadata about the resource, used for managing ownership in Kubernetes. kwargs: Arbitrary keyword arguments, primarily used for additional logging or context.

Returns:

str or None: The name of the CORS plugin on success, or None if CORS is not enabled.

Raises:

ApiException: An error from the Kubernetes API if the plugin update or creation fails.

apiOperatorKong.update_httproute_annotations(name, namespace, annotations)

Updates the annotations of an HTTPRoute resource to include references to any plugins/policies applied.

This function attempts to patch the existing HTTPRoute with new plugins/policies .This helps in maintaining a clear record of what plugins are associated with which routes.

Parameters:

name (str): The name of the HTTPRoute resource. namespace (str): The Kubernetes namespace where the HTTPRoute is located. annotations (dict): A dictionary containing the annotations to be added or updated on the HTTPRoute.

Returns:

bool: True if the update is successful, False otherwise.

Raises:

ApiException: Error if the update fails.

apiOperatorKong.check_url(url)

Checks the accessibility of a URL to ensure it is reachable. This function sends a HEAD request to the URL to verify if the URL is accessible without downloading the content. It logs an error if the URL is not reachable or returns an unsuccessful status code.

Parameters:

url (str): The URL to check for its accessibility.

Returns:

bool: True for accessible URL else its False

apiOperatorKong.download_template(url)

Downloads and parses a YAML template from a given URL. This function attempts to fetch content from a specified URL expecting it to be a YAML format. It parses the content into a list of documents. Using ‘no-cache’ headers to make sure fresh content is fetched always.

Parameters:

url (str): The URL from which to download the YAML template.

Returns:

list or None: A list of YAML documents or None if the download fails or content is invalid.

apiOperatorKong.apply_plugins_from_template(templates, namespace, owner_references)

Applies plugin configurations to the Kubernetes cluster using the provided templates. Each template is expected to define a Kubernetes custom object for a plugin. This function manages the lifecycle of these plugins, updating existing ones and creating new ones as per requirement.

Parameters:

templates (list): A list of dictionaries, each representing a plugin configuration in YAML format. namespace (str): The Kubernetes namespace in which the plugins should be managed. owner_references (list): A list of owner references to ensure Kubernetes garbage collection is linked to the parent resource.

Returns:

list: A list of names of the plugins that were successfully created or updated.

apiOperatorKong.manage_plugins_from_url(spec, name, namespace, meta)

Manages the download and application of plugins from a URL specified in the API resource specification. This function checks if a URL is provided and reachable, downloads the corresponding templates, and applies them as plugins in the specified namespace. It also handles setting up ownership for automatic cleanup and logs the results.

Parameters:

spec (dict): The specification dictionary that may contain a ‘template’ URL. name (str): The name of the API resource. namespace (str): The Kubernetes namespace where plugins will be applied. meta (dict): Metadata about the resource, used for managing ownership in Kubernetes.

Returns:

list: A list of plugin names that were applied from the URL in template in CR.

apiOperatorKong.delete_api_lifecycle(meta, name, namespace, **kwargs)

Handles the deletion event of an API resource and logs the expected cascading deletions. This function logs the deletion of an ‘ExposedAPI’ resource and the expected automatic deletion of its associated ‘HTTPRoute’ due to Kubernetes ownership links that were created using kopf.adopt().

Parameters:

meta (dict): Metadata about the resource, which includes details like the resource’s unique identifier. name (str): The name of the API resource that was deleted. namespace (str): The Kubernetes namespace from which the resource was deleted. kwargs: Arbitrary keyword arguments, primarily used for additional logging or context.

Returns:

None