`kubernetes`¶

Kubernetes resource type for Salt’s resources subsystem.

Added in version 2.1.0.

Note

Requires Salt 3008.0 or newer — the resources subsystem (salt.utils.resources / salt.utils.resource_registry) is only present from 3008. On 3006 or 3007 this module’s __virtual__ returns False and the loader skips it.

This module is the Kubernetes-side companion to Salt’s resources subsystem. Every minion declaring a kubernetes resources block in its pillar publishes each cluster’s pods, deployments, nodes, etc. up to the master’s resource registry, where they become first-class targets:

# Target every Pod with label app=nginx, across all clusters every
# minion in the fleet manages:
salt -G 'app:nginx' kubernetes.show_pod

# Drain a node by bare resource ID:
salt 'node:gke-prod-pool-1-abc' kubernetes.drain

The plugin is intentionally dormant on Salt versions earlier than 3008: its __virtual__ returns False unless salt.utils.resources is importable, which is only true on Salt 3008+. On older Salt the module is a no-op — present on the loader path, but never loaded.

Pillar shape — discovery mode (filters apply, API enumerates):

resources:
  kubernetes:
    # discovery mode is selected when ``resources:`` is absent (or
    # ``mode: discover`` is set explicitly). The plug-in connects via
    # ``_setup_conn`` (same auth path the typed kubernetes execution
    # module uses) and lists every matching API object.
    mode: discover                          # optional; the default
    kinds:
      - pod
      - deployment
      - node
      - namespace
    namespaces: ["default", "production"]   # optional scope
    label_selector: "managed-by=salt"       # optional filter

Pillar shape — pillar-only mode (no API call):

resources:
  kubernetes:
    # When ``resources:`` is present the plug-in returns exactly the
    # objects listed there and skips API discovery. Useful for air-
    # gapped clusters, strict RBAC, bootstrap (declare resources
    # before they exist), or to avoid paying the discovery cost on
    # busy clusters. ``kinds:`` / ``namespaces:`` / ``label_selector:``
    # are ignored in this mode.
    mode: pillar                            # optional; inferred from ``resources:``
    resources:
      - {kind: deployment, namespace: prod, name: web}
      - {kind: deployment, namespace: prod, name: api}
      - {kind: namespace, name: prod}
      - {kind: node, name: gke-prod-pool-1-abc}

Pillar shape — merge mode (declared + discovered, union):

resources:
  kubernetes:
    mode: merge
    resources:
      - {kind: namespace, name: bootstrap-only}
    kinds: [deployment, namespace]
    namespaces: [prod]

When the resources subsystem is not loaded, importing this module is a no-op — the public functions are defined but __virtual__ returns (False, ...) so the loader never dispatches into them.

saltext.kubernetes.resources.kubernetes.__virtual__()[source]¶

Available only when Salt’s resources subsystem is loadable.

The resources subsystem ships in Salt 3008.0 and newer; on earlier versions salt.utils.resources does not exist and the loader skips this module. We probe salt.utils.resources rather than salt.loader.resource because the loader function is a Python callable that may be present in unrelated forks; the utils module is more uniquely diagnostic of the resources feature.

saltext.kubernetes.resources.kubernetes.init(opts)[source]¶

Initialise the Kubernetes resource type for this minion.

Called once when the resource type is loaded, before any per- resource operations. Reads the kubernetes block from the pillar’s resources tree and stashes it in __context__["kubernetes_resource"].

saltext.kubernetes.resources.kubernetes.initialized()[source]¶: Return True if init() has run successfully for this type.

saltext.kubernetes.resources.kubernetes.shutdown(opts)[source]¶: Drop type-level context. Called when the resource type unloads.

saltext.kubernetes.resources.kubernetes.discover(opts)[source]¶

Return the list of bare Kubernetes resource IDs this minion manages.

Behaviour is controlled by the pillar mode key (or the inferred mode when omitted — see init()):

mode: discover — connect to the cluster and enumerate every object whose kind / namespace / label matches the configured filters. The historical default.
mode: pillar — return exactly the IDs derived from the pillar resources: list. No API call is made. Useful for air- gapped clusters, strict RBAC where the discovery user lacks list permission, bootstrap (declare resources before they exist), and to avoid discovery cost on busy clusters.
mode: merge — union of the two: declared IDs first, then discovered IDs not already in the declared set.

The return value is a flat list of bare IDs (not SRNs); the resource subsystem prefixes kubernetes: automatically.

saltext.kubernetes.resources.kubernetes.grains()[source]¶

Return a grain dict for the resource currently in scope.

Reads __resource__["id"] (set by the resource dispatch layer), re-fetches the live object, and projects:

kind, namespace, name — identity
label.<key> for each label
annotation.<key> for selected annotations (kubectl-prefixed annotations are excluded — they’re noisy and change on every apply)

saltext.kubernetes.resources.kubernetes.grains_refresh()[source]¶: Equivalent to grains() (no client-side caching today).

kubernetes¶

`kubernetes`¶