apiOperatorIstio module

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

This module is part of the ODA Canvas, specifically tailored for environments adopting the Apisix 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 Apisix API Gateway, facilitating the creation and management of ApisixRoute configurations to expose APIs.

Key Features: - Automatically handles the lifecycle of ODA APIs including creation, update, and deletion of corresponding ApisixRoute resources to expose APIs through Apisix. - Manages ApisixPluginConfig resources to apply and enforce various plugins and policies on APIs routed through Apisix. - 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 Apisix API Gateway is used to expose APIs. It simplifies the management of API exposure and security by interfacing directly with Apisix, providing a robust and scalable API management solution.

apiOperatorApisix.configure(settings: OperatorSettings, **_)

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

Manages the lifecycle of an API by creating or updating the ApisixRoute, managing plugins, and handling error logging.

Args: spec (dict): Contains the specification for the API lifecycle, including ingress configurations and plugin templates. name (str): The name of the API. namespace (str): The Kubernetes namespace where the API is deployed. status (str): The current status of the API lifecycle management. meta (dict): Metadata related to the API lifecycle management. logger (logging.Logger): Logger for logging messages about the process. kwargs: Arbitrary keyword arguments that may be used for additional configurations.

Returns: None: This function does not return any value

Description: - First, attempts to create or update an ApisixRoute based on the provided ‘spec’, ‘name’, ‘namespace’, and ‘meta’. - If the ApisixRoute cannot be created or updated, it logs a failure message and the function returns early. - Checks if a template URL is provided in ‘spec’ and verifies its validity. - If valid, attempts to apply plugins based on the template. Logs the success or failure of this operation. - If plugins are successfully applied, updates the ApisixRoute with the plugin configuration. - Throughout the function, various informational and error logs are generated based on the operations performed.

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

Creates or updates an ApisixRoute ingress in a specified Kubernetes namespace based on the provided specifications.

Args: spec (dict): Specifications for creating or updating the ingress, including the paths and backends. name (str): Name of the API for which the ingress is being managed. namespace (str): The initial namespace passed to the function. meta (dict): Metadata information used during the creation or update process. kwargs: Arbitrary keyword arguments for potential future use or custom extensions.

Returns: bool: True if the ApisixRoute is successfully created or updated, False otherwise.

Description: - Checks if the implementation status is ‘ready’. If not, logs a message and skips ingress creation or update. - Constructs an ApisixRoute manifests using provided ‘spec’ details like path, backend service information. - Tries to find an existing ApisixRoute. If found, it updates the route using the existing ‘resourceVersion’. - If no existing route is found and it’s a case of a missing resource, it tries to create a new ApisixRoute and logs the outcome. - Catches and logs any API exceptions during the process, providing feedback on the success or failure of the operation.

apiOperatorApisix.create_rate_limiting_policy(spec)

Constructs a rate limiting policy configuration from provided specifications.

Args: spec (dict): Specifications containing the details of the rate limiting policy.

Returns: dict or None: A dictionary representing the rate limiting policy if ‘enabled’ is True; otherwise, returns None.

Description: - Extracts rate limiting configuration from the input specification. - If rate limiting is enabled, it configures a policy based on the specified limit and identifier. - Currently supports only per-second rate limiting. Ignores any interval settings and assumes rates are per second. - Constructs and returns a dictionary with the configuration for the rate limiting policy. The dictionary includes the rate, burst setting, key for identifying the rate limit scope, and whether to delay processing when under burst limit. - If rate limiting is not enabled, returns None.

Note: - Default limit is set to 5 requests per second if not specified. - The default identifier is ‘remote_addr’.

apiOperatorApisix.create_quota_policy(spec)

Constructs a quota policy configuration from provided specifications.

Args: spec (dict): Specifications containing the details of the quota policy.

Returns: dict or None: A dictionary representing the quota policy if both ‘identifier’ and ‘limit’ are present and not empty; otherwise, returns None.

Description: - Extracts quota configuration from the input specification. - Constructs a quota policy if both an identifier and a limit are defined in the specification. - Configures the policy with count limits, time window, identification key, and HTTP status code for rejection. - Constructs and returns a dictionary with the configuration for the quota policy. This includes count limits, time windows for the count, key for identifying the scope, and the rejection code. - Returns None if the necessary quota configuration is not completely defined.

Note: - Default time window for the count limit is 60 seconds. - Default HTTP rejection code is 429.

apiOperatorApisix.create_oas_validation_policy(spec)

Constructs an OpenAPI Specification (OAS) validation policy configuration based on the provided specifications.

Args: spec (dict): Specifications containing the details for the OAS validation policy.

Returns: dict or None: A dictionary representing the OAS validation policy if either request or response validation is enabled; otherwise, returns None.

Description: - Extracts the OAS validation configuration from the input specification. - Checks if either request or response validation is explicitly enabled. - If either validation is enabled, prints a notice about the availability of the OAS validation policy only through API7, a commercial extension of APISIX, and does not create the policy. Refer to the official documentation for more information. - If the policy were to be created, it would be configured with settings for validating requests and responses, along with allowances for unspecified headers, query parameters, and cookies. - Returns None as the creation of the policy is not supported outside of API7, as per the function’s current implementation.

Note: - The function currently acts to inform about the commercial availability of the feature in enterprise version and does not return a policy configuration.

apiOperatorApisix.create_cors_policy(spec)

Constructs a Cross-Origin Resource Sharing (CORS) policy configuration based on the provided specifications.

Args: spec (dict): Specifications containing the details for the CORS policy.

Returns: dict or None: A dictionary representing the CORS policy if enabled; otherwise, returns None.

Description: - Extracts CORS configuration from the input specification. - Constructs a CORS policy if CORS is enabled in the specification. This policy includes configurations such as allowed origins, credentials, and preflight request handling. - The preflight request handling includes settings for allowed methods, headers, and the maximum age for caching preflight responses. - Returns a dictionary with the complete configuration for the CORS policy. - If CORS is not enabled in the specification, returns None.

Note: - Default settings include allowing all origins, a standard set of headers and methods for preflight requests, and a default max age of 3600 seconds for preflight caching.

apiOperatorApisix.create_api_key_verification_policy(spec)

Constructs an API key verification policy configuration based on the provided specifications.

Args: spec (dict): Specifications containing the details for the API key verification policy.

Returns: dict or None: A dictionary representing the API key verification policy if enabled; otherwise, returns None.

Description: - Extracts API key verification configuration from the input specification. - Constructs an API key verification policy if API key verification is enabled in the specification. - Returns a dictionary with the configuration for the API key verification policy. - If API key verification is not enabled in the specification, returns None.

Note: - The ‘location’ field specifies where the API key is expected to be found in the request, typically in headers.

apiOperatorApisix.check_url(url)

Checks the accessibility of a URL by making a HEAD request.

Args: url (str): The URL to be checked.

Returns: bool: True if the URL is accessible, False if any error occurs.

Description: - Attempts to make a HEAD request to the specified URL to check its accessibility. - Raises an HTTP error if the request returns an unsuccessful status code, indicating that the URL is not reachable or valid. - If an exception occurs during the request, logs an error message detailing the issue and returns False.

Note: - This function is used to validate URLs in scenarios where URLs are required for further processing, such as downloading content or validating links in configurations.

apiOperatorApisix.download_and_append_plugin_names(url, plugin_names)

Downloads plugin configurations from a specified URL and appends their names to a provided list.

Args: url (str): The URL from where to download the plugin configurations. plugin_names (list): A list of plugin names to which new names will be appended.

Returns: tuple: A tuple containing the updated list of plugin names and the downloaded plugins, or (None, None) if an error occurs.

Description: - Makes a request to the specified URL with caching disabled to download plugin configurations. - Parses the response as YAML to extract plugin details. - Appends the names of the plugins to the provided list and prints the updated list and the combined plugin details. - Returns the updated list of plugin names and the list of plugins. - If an error occurs during the download or parsing, logs an error and returns (None, None).

Note: - This function is useful for dynamically configuring API gateways by downloading and integrating external plugin configurations.

apiOperatorApisix.combine_all_policies_with_plugins(spec, plugin_names, plugins)

Combines API management policies created from specifications with existing plugin configurations.

Args: spec (dict): Specifications that may include settings for various API management policies. plugin_names (list): A list of plugin names initially provided or derived from another part of the system. plugins (list): A list of existing plugin configurations.

Returns: tuple: A tuple containing two lists: updated plugin names and their corresponding plugin configurations.

Description: - Initializes lists to collect names and configurations of plugins derived from custom resource definitions (CRDs). - Iterates over a list of policy creator functions, each designed to generate a specific type of API management policy from the given specifications. - For each policy, if it is successfully created, adds its name to the list of plugin names and its configuration to the list of plugins. - Combines these newly created policy configurations with any existing plugin names and configurations. - Returns the combined lists of plugin names and configurations, reflecting an integrated set of API management tools.

Note: - The function leverages policy creators for rate limiting, quota management, OAS validation, CORS, and API key verification. - This function is crucial for dynamically constructing a comprehensive set of API management plugins based on both static configuration and dynamic specifications.

apiOperatorApisix.apply_plugins_from_template(namespace, api_name, spec, url)

Applies plugin configurations to an API from a specified template URL and CRD-based policies.

Args: namespace (str): The Kubernetes namespace where the plugin configurations will be applied. api_name (str): The name of the API to which the plugins are being applied. spec (dict): Specifications for creating policy-based plugins. url (str, optional): The URL from which to download additional plugin configurations.

Returns: list or None: A list containing the name of the modified plugin configuration if successful, None otherwise.

Description: - Initializes empty lists for plugin names and plugins. - If a URL is provided, downloads and appends additional plugin configurations. - Combines these plugins with CRD-based policies using the combine_all_policies_with_plugins function. - Constructs an ApisixPluginConfig Kubernetes custom object and attempts to either create or update it in the specified namespace. - Handles Kubernetes API exceptions by logging errors and providing feedback on the success or failure of the operation.

Note: - This function is critical for deploying combined plugin configurations to APIs, facilitating dynamic API gateway management.

apiOperatorApisix.patch_apisixroute_with_plugin_config(namespace, apisixroute_name, plugin_config_name)

Updates an existing ApisixRoute to include a specific plugin configuration.

Args: namespace (str): The Kubernetes namespace where the ApisixRoute is located. apisixroute_name (str): The name of the ApisixRoute to be patched. plugin_config_name (str): The name of the plugin configuration to apply to the ApisixRoute.

Returns: None: This function does not return a value but logs the outcome of the operation.

Description: - Connects to the Kubernetes API and attempts to fetch the existing ApisixRoute specified by apisixroute_name. - If the route is successfully retrieved, it updates the ‘plugin_config_name’ within the ‘http’ blocks of the route’s specification. - Applies the updated configuration using a strategic merge patch to the existing ApisixRoute. - Logs informational messages regarding the successful patching of the route, or error messages if any part of the process fails.

Note: - Uses error handling to manage and log exceptions related to fetching or patching the ApisixRoute, ensuring that all potential issues are reported. - The strategic merge patch method is used to ensure that changes are applied correctly without replacing the entire route configuration.

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

Deletes API lifecycle resources, including ApisixRoutes and ApisixPluginConfigs, for a specified API in a Kubernetes namespace.

Args: meta (dict): Metadata associated with the API lifecycle resources. name (str): The name of the API whose lifecycle resources are to be deleted. namespace (str): The Kubernetes namespace where the resources are located. Though provided, not directly used due to predefined ‘istio-ingress’. kwargs: Arbitrary keyword arguments that can be used for additional configurations or extensions.

Returns: None: This function does not return a value but logs the outcome of the deletion operations.

Description: - Logs the initiation of the deletion process for the API. - Defines the names of the resources associated with the API (ApisixRoute and ApisixPluginConfig) using a naming convention based on the API’s name. - Attempts to delete the ApisixRoute and ApisixPluginConfig from the ‘istio-ingress’ namespace. - Handles exceptions related to Kubernetes API interactions, logging errors if deletions fail.

Note: - Once referencegrant feature becomes available than this deletion function will be removed as it will be automatically handled using kopf.adopt and garbage collection - All deletions are attempted within the ‘istio-ingress’ namespace, regardless of the ‘namespace’ argument provided, reflecting a typical use case in an Istio-managed environment. - The function uses the ‘apisix.apache.org’ group and ‘v2’ version for Kubernetes custom objects, which are common in APISIX integrations. - This function is vital for cleaning up resources when an API is decommissioned or when its lifecycle management needs to be reset.