kubernetes-client / python

Discovery

The dynamic client discovers API resources using the Discovery class in kubernetes/base/dynamic/discovery.py. This class leverages a cache to store discovered resources and optimizes resource retrieval.

Caching:

  • The Discovery class utilizes a cache file, which is specified during initialization.
  • This cache file persists discovered resources for subsequent calls, enhancing performance.

Resource Discovery Process:

  1. Initialization: When the Discovery class is instantiated, it attempts to load the cache file.
  2. Search: To discover a specific resource, the search method is invoked with the desired resource attributes (e.g., group, version, kind).
  3. Cache Check: The search method first checks the cache for the requested resource.
  4. API Retrieval (if not in cache): If the resource is not found in the cache, the Discovery class retrieves the resource information from the Kubernetes API server using the get_api_resources API call.
  5. Cache Update: The retrieved resource information is then added to the cache for future use.

Resource Representation:

  • The discovered resources are represented as Resource objects.
  • Resource objects hold details about the resource, including its group, version, kind, and other metadata.

Example:

To discover all resources of the apps/v1 group:

from kubernetes.client.api import DiscoveryApi
          
          api_instance = DiscoveryApi()
          api_response = api_instance.get_api_resources(group="apps", version="v1")
          
          print(api_response)

API Endpoint:

The get_api_resources API endpoint is used to discover API resources.

HTTP Request:

GET /apis/{group}/{version}

Parameters:

  • group: The group of the API resource.
  • version: The version of the API resource.

Response:

The API response contains a list of resources within the specified group and version.

Discovery Options:

The Discovery class provides the following options for resource discovery:

  • group: The group of the resource.
  • version: The version of the resource.
  • kind: The kind of the resource.
  • prefix: The prefix of the resource path.
  • kwargs: Additional keyword arguments to filter the search results.

Examples:

  • Discover all resources:
    discovery.search()
  • Discover all resources in the “apps” group:
    discovery.search(group='apps')
  • Discover all resources of the “Deployment” kind:
    discovery.search(kind='Deployment')
  • Discover all resources with the “v1” version:
    discovery.search(version='v1')

Cache Invalidation:

  • The invalidate_cache method clears the cache, forcing the discovery of resources from the API server.
  • This is useful when the cluster configuration has changed.

Note: The cache file is located at the path specified during initialization. The default location for the cache file is ~/.kube/cache.

Code Examples:

  • kubernetes/base/dynamic/discovery.py: Implements the Discovery class and defines the resource discovery logic.
  • examples/api_discovery.py: Demonstrates how to use the dynamic client for API discovery.

Documentation:

  • kubernetes/docs/DiscoveryApi.md: Describes the DiscoveryApi class and its methods.
  • kubernetes/docs/DiscoveryV1Api.md: Provides details about the DiscoveryV1Api class and its methods.
  • doc/source/kubernetes.client.api.discovery_api.rst: Contains the documentation for the DiscoveryApi class.

Top-Level Directory Explanations

doc/ - This directory contains documentation files for the project.

doc/source/ - This directory contains the source files for the documentation.

examples/ - This directory contains example usage of the Kubernetes client library.

examples/dynamic-client/ - This directory contains examples of using the dynamic client to interact with Kubernetes.

examples/watch/ - This directory contains examples of using the watch function to monitor Kubernetes resources.

kubernetes/ - This directory contains the main Kubernetes client library.

kubernetes/base/ - This directory contains the base Kubernetes client library.

kubernetes/base/config/ - This directory contains configuration files for the base library.

kubernetes/base/dynamic/ - This directory contains the dynamic client implementation for the base library.

kubernetes/base/hack/ - This directory contains hack files for the base library.

kubernetes/base/leaderelection/ - This directory contains the leader election implementation for the base library.

kubernetes/base/stream/ - This directory contains the stream implementation for the base library.

kubernetes/base/watch/ - This directory contains the watch implementation for the base library.

kubernetes/client/ - This directory contains the top-level client for the Kubernetes client library.

kubernetes/client/api/ - This directory contains the API definitions for the client library.

kubernetes/client/apis/ - This directory contains the API implementations for the client library.

kubernetes/client/models/ - This directory contains the data models used by the client library.

kubernetes/e2e_test/ - This directory contains end-to-end tests for the Kubernetes client library.

kubernetes/e2e_test/test_yaml/ - This directory contains YAML files used in the end-to-end tests.

scripts/ - This directory contains scripts used in the development and build process.

scripts/util/ - This directory contains utility scripts.