kctl

Rancher Kubernetes API compatible with RKE, RKE2 and maybe others?

---

Documentation is WIP.

---

Quickstart

pip install --upgrade kctl

Usage

from lazycls.envs import set_env_from_dict


"""
---
Primary Configuration that takes env variables first.
---

host = envToStr('KCTL_HOST', 'http://localhost')
api_key = envToStr('KCTL_API_KEY')
api_key_prefix = envToStr('KCTL_API_KEY_PREFIX', 'token:')
api_token = envToStr('KCTL_API_TOKEN')
username = envToStr('KCTL_API_USERNAME')
password = envToStr('KCTL_API_PASSWORD')
auth_prefix = envToStr('KTCL_AUTH_PREFIX', 'authorization')

---
Rancher Specific Configuration
---

host: str = KctlCfg.host,
api_version: str = 'v1',
api_token: str = KctlCfg.api_token,
ssl_verify: bool = True,
strict: bool = False,
cache_time: int = 86400,
cache_dir: Union[Path, str] = DefaultCacheDir,
rancher_default_cluster: str = None,
rancher_fleet_name: str = 'fleet-default',
clusters_enabled: List[str] = [],
clusters_disabled: List[str] = []

---
Then validates against env variables during initialization, prioritizing env variables.
---

api_version = envToStr('KCTL_API_VERSION', api_version or 'v1')
ssl_verify = envToBool('KCTL_SSL_VERIFY', str(ssl_verify))
strict = envToBool('KCTL_STRICT', str(strict))
cache_time = envToInt('KCTL_CACHE_TIME', cache_time)
cache_dir = to_path(envToStr('KCTL_CACHE_DIR', None) or cache_dir)

rancher_default_cluster = envToStr('KCTL_RANCHER_DEFAULT_CLUSTER', rancher_default_cluster)
rancher_fleet_name = envToStr('KCTL_RANCHER_FLEET_NAME', rancher_fleet_name)

# If both are empty, then it will assume all clusters are enabled.
clusters_enabled = envToList('KCTL_CLUSTERS_ENABLED', clusters_enabled)
clusters_disabled = envToList('KCTL_CLUSTERS_DISABLED', clusters_disabled)

"""

data = {
    'KCTL_HOST': 'https://ranchercluster.com',
    'KCTL_API_TOKEN': 'token-xxxx:yyyyyyyyyyyyyyyyyyyyyyyyyyyy'
}

set_env_from_dict(data, override=True)
from kctl.client import KctlClient

## Rancher Specific
## This will build the object class dynamically
## enabling v1/v3 api methods.
## v3 is typically the management cluster
## v1 is cluster specific

KctlClient.build_rancher_ctx()

## KctlClient is a Class that doesnt require initialization

## Sync Method
cs = KctlClient.v3.list_cluster()

## Async Method
cs = await KctlClient.v3.async_list_cluster()

cs.data[-1].name

"""
local
"""

## Change Cluster Context

KctlClient.set_cluster('staging-cluster')

KctlClient.v1.url
"""
Now the primary api url will be called using the proper k8s path

-> https://ranchercluster.com/k8s/clusters/c-m-xxxxxx

"""

KctlClient.v1.list_apps_deployment()

"""
All v1 methods will now return the specified cluster context

{
    'type': 'collection', 
    'links': {'self': 'https://ranchercluster.com/k8s/clusters/c-m-xxxxxx/v1/apps.deployments/fleet-default'}, 
    'createTypes': {'apps.deployment': 'https://ranchercluster.com/k8s/clusters/c-m-xxxxxx/v1/apps.deployments'}, 
    'actions': {}, 
    'resourceType': 'apps.deployment', 
    'revision': '6671325', 
    'data': []
}
"""

---

Enhancements

This library borrows the dynamic initialization method from the primary rancher-client python library with several enhancements.

• Async and Sync support via httpx / lazyapi, which can be initialized from a sync environment.

• All async methods are accessed with async_ prefix of the same sync methods.

• Inclusion of kubernetes python client which can be called via KctlClient.api, allowing setting of credentials once. Although this use case has not been extensively tested. (or rather, at all.)

• Dynamic Access of downstream clusters without requiring reinitialization of the client

• Enables context switching between clusters

• Lazy caching of the api schema in kctl/kctl/.kctlcache

• Enables access of v1/v3 api methods within the same client.

• All returned results are objects, allowing dynamic access of object attributes, rather than strictly dict based.

• Adds support for fleet namespaces to ensure proper url handling

---

Credits / Libraries Used

• rancher-client: inspired dynamic schema initialization

• kubernetes: included to manage credentials

• lazyapi: personal library that is used to create the httpx clients.

• lazycls: personal library that contains a lot of utility functions that enables this library to be as slim as possible.