Kubernetes Provider
Generic Kubernetes resource management for Pragmatiks using lightkube.
Declaratively manage Kubernetes workloads, networking, configuration, and cluster-scoped resources. Workload resources authenticate through a shared kubernetes/config resource and use server-side apply for idempotent operations.
Prerequisites
- A reachable Kubernetes cluster -- managed by the GCP provider (
gcp/gke), external, or the cluster the controller itself runs in - Credentials for that cluster: a GKE cluster dependency, a mounted kubeconfig file, or in-cluster pod service-account credentials
- RBAC permissions on the target cluster for the resources you want to manage (typically
cluster-adminor namespace-scoped roles)
Installation
pragma providers install kubernetes
Resources
| Resource | Type Slug | Description |
|---|---|---|
| Config | kubernetes/config |
Authenticated cluster access shared by every workload resource |
| Namespace | kubernetes/namespace |
Cluster-scoped namespace isolation |
| Deployment | kubernetes/deployment |
Stateless workload with rolling updates |
| StatefulSet | kubernetes/statefulset |
Stateful workload with persistent storage and stable pod identity |
| Service | kubernetes/service |
Network exposure (ClusterIP, NodePort, LoadBalancer, Headless) |
| ConfigMap | kubernetes/configmap |
Non-sensitive configuration data |
| Secret | kubernetes/secret |
Sensitive data (credentials, tokens, TLS certs) |
All workload resources require a config dependency pointing to a kubernetes/config resource for authentication.
Config
Authenticated cluster access used by every other resource in this provider. Supports three modes, letting you target existing clusters without owning their lifecycle:
in_cluster-- use the pod's mounted service account at/var/run/secrets/kubernetes.io/serviceaccount. Fails at validation if no credentials are mounted.gke_cluster-- build credentials from agcp/gkedependency.kubeconfig_file-- read a kubeconfig YAML from/etc/pragma-kubeconfig/. The path must be absolute, under the allowed root, and not a symlink.
Config:
mode("in_cluster"|"gke_cluster"|"kubeconfig_file") -- Authentication mode (immutable)cluster(dependency, required forgke_cluster) -- GKE cluster dependency (immutable)kubeconfig_path(string, required forkubeconfig_file) -- Absolute path under/etc/pragma-kubeconfig/(immutable)
Outputs:
mode-- Mode the config is operating in
resources:
in-cluster-config:
provider: kubernetes
resource: config
config:
mode: in_cluster
gke-config:
provider: kubernetes
resource: config
config:
mode: gke_cluster
cluster: ${{ my-cluster }}
file-config:
provider: kubernetes
resource: config
config:
mode: kubeconfig_file
kubeconfig_path: /etc/pragma-kubeconfig/staging.yaml
Namespace
Cluster-scoped resource for workload isolation. Namespaces do not belong to another namespace.
Config:
config(dependency) --kubernetes/configresource for cluster accesslabels(dict, optional) -- Labels to apply to the namespace
Outputs:
name-- Namespace name
resources:
dev-namespace:
provider: kubernetes
resource: namespace
config:
config: ${{ my-config }}
labels:
environment: development
team: platform
Deployment
Manages stateless workloads with configurable replicas, rolling update strategy, health probes, environment variables, and resource limits. Waits for all replicas to be ready before reporting success (timeout: 300s).
Config:
config(dependency) --kubernetes/configresource for cluster accessnamespace(string, default:"default") -- Target namespace (immutable)replicas(int, default:1) -- Desired pod replicasselector(dict) -- Label selector for pods (immutable)labels(dict, optional) -- Pod labels; defaults toselectorif not setcontainers(list) -- Container specs: image, ports, env, probes, resourcesstrategy("RollingUpdate"|"Recreate", default:"RollingUpdate") -- Update strategy
Outputs:
name,namespace,replicas
resources:
api-deployment:
provider: kubernetes
resource: deployment
config:
config: ${{ my-config }}
namespace: production
replicas: 3
selector:
app: api
containers:
- name: api
image: gcr.io/my-project/api:latest
ports:
- container_port: 8080
name: http
env:
LOG_LEVEL: info
env_from_secret:
DATABASE_URL: db-credentials.url
resources:
cpu: "250m"
memory: "512Mi"
cpu_limit: "1000m"
memory_limit: "1Gi"
readiness_probe:
http_get:
path: /healthz
port: 8080
initial_delay_seconds: 5
period_seconds: 10
StatefulSet
Manages stateful workloads with stable pod identity, persistent storage via PVC templates, and ordered deployment. Associates with a headless service for DNS-based pod discovery. Waits for all replicas to be ready before reporting success. Deleting a StatefulSet also deletes the PersistentVolumeClaims created from its templates, with their data.
Config:
config(dependency) --kubernetes/configresource for cluster accessnamespace(string, default:"default") -- Target namespace (immutable)replicas(int, default:1) -- Desired pod replicasservice_name(string) -- Headless service for pod DNS (immutable)selector(dict, optional) -- Label selector; defaults to{"app": "<name>"}(immutable)containers(list) -- Container specs: image, ports, env, volume mounts, probesvolume_claim_templates(list, optional) -- PVC templates for persistent storage (immutable)
Outputs:
name,namespace,replicas,service_name
resources:
postgres:
provider: kubernetes
resource: statefulset
config:
config: ${{ my-config }}
namespace: data
replicas: 3
service_name: postgres-headless
containers:
- name: postgres
image: postgres:16
ports:
- container_port: 5432
name: postgres
env:
- name: POSTGRES_DB
value: myapp
volume_mounts:
- name: data
mount_path: /var/lib/postgresql/data
resources:
requests:
cpu: "500m"
memory: "1Gi"
limits:
cpu: "2000m"
memory: "4Gi"
readiness_probe:
tcp_socket_port: 5432
initial_delay_seconds: 15
period_seconds: 10
volume_claim_templates:
- name: data
storage_class: premium-rwo
access_modes:
- ReadWriteOnce
storage: 50Gi
Service
Exposes workloads via ClusterIP, NodePort, LoadBalancer, or Headless service types. Services are immediately ready after apply (no polling). Headless services automatically set clusterIP: None. An update cannot make the service in the cluster headless, or stop it being headless, whether through type: Headless or cluster_ip: "None": the cluster IP of an existing service cannot change.
Config:
config(dependency) --kubernetes/configresource for cluster accessnamespace(string, default:"default") -- Target namespace (immutable)type("ClusterIP"|"NodePort"|"LoadBalancer"|"Headless", default:"ClusterIP") -- Service typeselector(dict) -- Label selector for target podsports(list) -- Port mappings: port, target_port, protocol, namecluster_ip(string, optional) -- Explicit cluster IP (immutable)
Outputs:
name,namespace,cluster_ip,type
resources:
api-service:
provider: kubernetes
resource: service
config:
config: ${{ my-config }}
namespace: production
type: ClusterIP
selector:
app: api
ports:
- name: http
port: 80
target_port: 8080
postgres-headless:
provider: kubernetes
resource: service
config:
config: ${{ my-config }}
namespace: data
type: Headless
selector:
app: postgres
ports:
- name: postgres
port: 5432
ConfigMap
Stores non-sensitive configuration data as key-value pairs. ConfigMaps can be mounted as files or exposed as environment variables in pods.
Config:
config(dependency) --kubernetes/configresource for cluster accessnamespace(string, default:"default") -- Target namespace (immutable)data(dict) -- Key-value pairs to store
Outputs:
name,namespace,data
resources:
app-config:
provider: kubernetes
resource: configmap
config:
config: ${{ my-config }}
namespace: production
data:
APP_ENV: production
LOG_FORMAT: json
MAX_CONNECTIONS: "100"
Secret
Stores sensitive data (credentials, tokens, TLS certificates). Data values are automatically base64-encoded. Supports both pre-encoded data and plain-text string_data fields.
Config:
config(dependency) --kubernetes/configresource for cluster accessnamespace(string, default:"default") -- Target namespace (immutable)type(string, default:"Opaque") -- Secret type (e.g.,Opaque,kubernetes.io/tls)data(dict, optional) -- Key-value pairs (will be base64-encoded)string_data(dict, optional) -- Plain-text key-value pairs (Kubernetes encodes them)
Outputs:
name,namespace,type,data
resources:
db-credentials:
provider: kubernetes
resource: secret
config:
config: ${{ my-config }}
namespace: production
type: Opaque
string_data:
url: postgresql://user:pass@postgres:5432/myapp
username: user
password: pass
Cross-Provider Usage
The Kubernetes provider is designed to work alongside the GCP provider. A typical pattern is: GCP provisions the cluster, a kubernetes/config resource authenticates to it, and the workload resources depend on the config.
resources:
# GCP creates the cluster
my-cluster:
provider: gcp
resource: gke
config:
project_id: my-project
location: europe-west4
name: prod-cluster
credentials: ${{ secrets.gcp_credentials }}
# kubernetes/config mediates cluster access for all workload resources
my-config:
provider: kubernetes
resource: config
config:
mode: gke_cluster
cluster: ${{ my-cluster }}
# Kubernetes workload resources depend on the config
app-namespace:
provider: kubernetes
resource: namespace
config:
config: ${{ my-config }}
labels:
environment: production
app-config:
provider: kubernetes
resource: configmap
config:
config: ${{ my-config }}
namespace: ${{ app-namespace.name }}
data:
APP_ENV: production
app-secrets:
provider: kubernetes
resource: secret
config:
config: ${{ my-config }}
namespace: ${{ app-namespace.name }}
string_data:
api_key: ${{ secrets.api_key }}
app:
provider: kubernetes
resource: deployment
config:
config: ${{ my-config }}
namespace: ${{ app-namespace.name }}
replicas: 3
selector:
app: my-app
containers:
- name: app
image: gcr.io/my-project/app:latest
ports:
- container_port: 8080
env_from_secret:
API_KEY: app-secrets.api_key
app-service:
provider: kubernetes
resource: service
config:
config: ${{ my-config }}
namespace: ${{ app-namespace.name }}
type: LoadBalancer
selector:
app: my-app
ports:
- port: 80
target_port: 8080
Resources are applied in dependency order. The platform resolves ${{ my-cluster }}, ${{ my-config }}, and ${{ app-namespace.name }} references automatically, ensuring the GKE cluster and kubernetes/config resources are ready before any workload resources are created.
Metadata
Release files for pragmatiks-kubernetes-provider 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pragmatiks_kubernetes_provider-2.1.0.tar.gz | 23.2 kB | Without provenance | Details for pragmatiks_kubernetes_provider-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pragmatiks_kubernetes_provider-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for pragmatiks_kubernetes_provider-2.1.0-py3-none-any.whl |
Total release size: 57.3 kB
Release files / pragmatiks_kubernetes_provider-2.1.0.tar.gz
| Download URL | pragmatiks_kubernetes_provider-2.1.0.tar.gz |
|---|---|
| Size | 23.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc22fb72198e4bff43c856b48957b02af4af548670d3f8d3d8c5ada0f158f2ad
|
|
BLAKE2b-256 checksum How to use checksums |
ef0511687ce94eb79a04ce4ae8824d8f2f5f9bea0a0716fe5b9f33ac2514aad2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pragmatiks_kubernetes_provider-2.1.0-py3-none-any.whl
| Download URL | pragmatiks_kubernetes_provider-2.1.0-py3-none-any.whl |
|---|---|
| Size | 34.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
58d5b6e129e813033dc0777fe52f23e0c9cd8814a7f543b328295fa585596e66
|
|
BLAKE2b-256 checksum How to use checksums |
6e147815a1aa551b6f377b8fe84e13968df33255a3344df760be3dfbba1b75af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for pragmatiks-kubernetes-provider 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.