kubernetes

Module for handling kubernetes calls.

optdepends:

• kubernetes Python client >= v19.15.0

• PyYAML >= 5.3.1

configuration:

The k8s API settings are provided either in a pillar, in the minion’s config file, or in master’s config file:

kubernetes.kubeconfig: '/path/to/kubeconfig'
kubernetes.kubeconfig-data: '<base64 encoded kubeconfig content'
kubernetes.context: 'context'

The data format for kubernetes.kubeconfig-data value is the content of kubeconfig base64 encoded in one line.

These settings can be overridden by adding context and `kubeconfig or kubeconfig_data parameters when calling a function.

Only kubeconfig or kubeconfig-data should be provided. In case both are provided kubeconfig entry is preferred.

CLI Example:

salt '*' kubernetes.nodes
salt '*' kubernetes.nodes kubeconfig=/etc/salt/k8s/kubeconfig context=minikube

Added in version 2017.7.0.

Changed in version 2019.2.0.

Warning

Configuration options changed in 2019.2.0. The following configuration options have been removed:

• kubernetes.user

• kubernetes.password

• kubernetes.api_url

• kubernetes.certificate-authority-data/file

• kubernetes.client-certificate-data/file

• kubernetes.client-key-data/file

Please use now:

• kubernetes.kubeconfig or kubernetes.kubeconfig-data

• kubernetes.context

saltext.kubernetes.modules.kubernetesmod.__virtual__()

Check dependencies

saltext.kubernetes.modules.kubernetesmod.ping(**kwargs)

Checks connection with the kubernetes API server. Returns True if the API is available.

CLI Example:

salt '*' kubernetes.ping

saltext.kubernetes.modules.kubernetesmod.nodes(**kwargs)

Return the names of the nodes composing the kubernetes cluster

CLI Example:

salt '*' kubernetes.nodes

saltext.kubernetes.modules.kubernetesmod.node(name, **kwargs)

Return the details of the node identified by the specified name

CLI Example:

salt '*' kubernetes.node name='minikube'

saltext.kubernetes.modules.kubernetesmod.node_labels(name, **kwargs)

Return the labels of the node identified by the specified name

name

The name of the node

CLI Example:

salt '*' kubernetes.node_labels name="minikube"

saltext.kubernetes.modules.kubernetesmod.node_add_label(node_name, label_name, label_value, **kwargs)

Set the value of the label identified by label_name to label_value on the node identified by the name node_name. Creates the label if not present.

node_name

The name of the node

label_name

The name of the label

label_value

The value of the label

CLI Example:

salt '*' kubernetes.node_add_label node_name="minikube"             label_name="foo" label_value="bar"

saltext.kubernetes.modules.kubernetesmod.node_remove_label(node_name, label_name, **kwargs)

Removes the label identified by label_name from the node identified by the name node_name.

node_name

The name of the node

label_name

The name of the label

CLI Example:

salt '*' kubernetes.node_remove_label node_name="minikube"             label_name="foo"

saltext.kubernetes.modules.kubernetesmod.namespaces(**kwargs)

Return the names of the available namespaces

CLI Example:

salt '*' kubernetes.namespaces

saltext.kubernetes.modules.kubernetesmod.deployments(namespace='default', **kwargs)

Return a list of kubernetes deployments defined in the namespace

namespace

The namespace to list deployments from. Defaults to default.

CLI Example:

salt '*' kubernetes.deployments
salt '*' kubernetes.deployments namespace=default

saltext.kubernetes.modules.kubernetesmod.services(namespace='default', **kwargs)

Return a list of kubernetes services defined in the namespace

namespace

The namespace to list services from. Defaults to default.

CLI Example:

salt '*' kubernetes.services
salt '*' kubernetes.services namespace=default

saltext.kubernetes.modules.kubernetesmod.pods(namespace='default', **kwargs)

Return a list of kubernetes pods defined in the namespace

namespace

The namespace to list pods from. Defaults to default.

CLI Example:

salt '*' kubernetes.pods
salt '*' kubernetes.pods namespace=default

saltext.kubernetes.modules.kubernetesmod.secrets(namespace='default', **kwargs)

Return a list of kubernetes secrets defined in the namespace

namespace

The namespace to list secrets from. Defaults to default.

CLI Example:

salt '*' kubernetes.secrets
salt '*' kubernetes.secrets namespace=default

saltext.kubernetes.modules.kubernetesmod.configmaps(namespace='default', **kwargs)

Return a list of kubernetes configmaps defined in the namespace

namespace

The namespace to list configmaps from. Defaults to default.

CLI Example:

salt '*' kubernetes.configmaps
salt '*' kubernetes.configmaps namespace=default

saltext.kubernetes.modules.kubernetesmod.show_deployment(name, namespace='default', **kwargs)

Return the kubernetes deployment defined by name and namespace

name

The name of the deployment

namespace

The namespace to look for the deployment. Defaults to default.

CLI Example:

salt '*' kubernetes.show_deployment my-nginx default
salt '*' kubernetes.show_deployment name=my-nginx namespace=default

saltext.kubernetes.modules.kubernetesmod.show_service(name, namespace='default', **kwargs)

Return the kubernetes service defined by name and namespace

name

The name of the service

namespace

The namespace to look for the service. Defaults to default.

CLI Example:

salt '*' kubernetes.show_service my-nginx default
salt '*' kubernetes.show_service name=my-nginx namespace=default

saltext.kubernetes.modules.kubernetesmod.show_pod(name, namespace='default', **kwargs)

Return POD information for a given pod name defined in the namespace

name

The name of the pod

namespace

The namespace to look for the pod. Defaults to default.

CLI Example:

salt '*' kubernetes.show_pod guestbook-708336848-fqr2x
salt '*' kubernetes.show_pod guestbook-708336848-fqr2x namespace=default

saltext.kubernetes.modules.kubernetesmod.show_namespace(name, **kwargs)

Return information for a given namespace defined by the specified name

name

The name of the namespace to show

CLI Example:

salt '*' kubernetes.show_namespace kube-system

saltext.kubernetes.modules.kubernetesmod.show_secret(name, namespace='default', decode=False, **kwargs)

Return the kubernetes secret defined by name and namespace. The secrets can be decoded if specified by the user. Warning: this has security implications.

name

The name of the secret

namespace

The namespace to look for the secret. Defaults to default.

decode

Decode the secret values. Default is False

CLI Example:

salt '*' kubernetes.show_secret confidential default
salt '*' kubernetes.show_secret name=confidential namespace=default
salt '*' kubernetes.show_secret name=confidential decode=True

saltext.kubernetes.modules.kubernetesmod.show_configmap(name, namespace='default', **kwargs)

Return the kubernetes configmap defined by name and namespace.

name

The name of the configmap

namespace

The namespace to look for the configmap. Defaults to default.

CLI Example:

salt '*' kubernetes.show_configmap game-config default
salt '*' kubernetes.show_configmap name=game-config namespace=default

saltext.kubernetes.modules.kubernetesmod.delete_deployment(name, namespace='default', wait=False, timeout=60, **kwargs)

Deletes the kubernetes deployment defined by name and namespace

name

The name of the deployment

namespace

The namespace to delete the deployment from. Defaults to default.

wait

Added in version 2.0.0.

Wait for deployment deletion to complete (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deletion (default: 60)

CLI Example:

salt '*' kubernetes.delete_deployment my-nginx default wait=True

saltext.kubernetes.modules.kubernetesmod.delete_service(name, namespace='default', wait=False, timeout=60, **kwargs)

Deletes the kubernetes service defined by name and namespace

name

The name of the service

namespace

The namespace to delete the service from. Defaults to default.

wait

Added in version 2.0.0.

Wait for service deletion to complete (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deletion (default: 60)

CLI Example:

salt '*' kubernetes.delete_service my-nginx default
salt '*' kubernetes.delete_service name=my-nginx namespace=default

saltext.kubernetes.modules.kubernetesmod.delete_pod(name, namespace='default', wait=False, timeout=60, **kwargs)

Deletes the kubernetes pod defined by name and namespace

name

The name of the pod

namespace

The namespace to delete the pod from. Defaults to default.

wait

Added in version 2.0.0.

Wait for pod deletion to complete (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deletion (default: 60)

CLI Example:

salt '*' kubernetes.delete_pod guestbook-708336848-5nl8c default
salt '*' kubernetes.delete_pod name=guestbook-708336848-5nl8c namespace=default

saltext.kubernetes.modules.kubernetesmod.delete_namespace(name, wait=False, timeout=60, **kwargs)

Deletes the kubernetes namespace defined by name

name

The name of the namespace

wait

Added in version 2.0.0.

Wait for namespace deletion to complete (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deletion (default: 60)

CLI Example:

salt '*' kubernetes.delete_namespace salt
salt '*' kubernetes.delete_namespace name=salt

saltext.kubernetes.modules.kubernetesmod.delete_secret(name, namespace='default', wait=False, timeout=60, **kwargs)

Deletes the kubernetes secret defined by name and namespace

name

The name of the secret

namespace

The namespace to delete the secret from. Defaults to default.

wait

Added in version 2.0.0.

Wait for secret deletion to complete (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deletion (default: 60)

CLI Example:

salt '*' kubernetes.delete_secret confidential default
salt '*' kubernetes.delete_secret name=confidential namespace=default

saltext.kubernetes.modules.kubernetesmod.delete_configmap(name, namespace='default', wait=False, timeout=60, **kwargs)

Deletes the kubernetes configmap defined by name and namespace

name

The name of the configmap

namespace

The namespace to delete the configmap from. Defaults to default.

wait

Added in version 2.0.0.

Wait for configmap deletion to complete (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deletion (default: 60)

CLI Example:

salt '*' kubernetes.delete_configmap settings default
salt '*' kubernetes.delete_configmap name=settings namespace=default

saltext.kubernetes.modules.kubernetesmod.create_deployment(name, namespace, metadata, spec, source=None, template=None, saltenv=None, template_context=None, wait=False, timeout=60, **kwargs)

Creates the kubernetes deployment as defined by the user.

name

The name of the deployment

namespace

The namespace to create the deployment in

metadata

Deployment metadata dict

spec

Deployment spec dict following kubernetes API conventions

source

File path to deployment definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for deployment to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deployment (default: 60)

CLI Example:

salt '*' kubernetes.create_deployment name=nginx namespace=default spec='{"replicas": 1}' wait=True

saltext.kubernetes.modules.kubernetesmod.create_pod(name, namespace, metadata, spec, source=None, template=None, saltenv=None, template_context=None, wait=False, timeout=60, **kwargs)

Creates a kubernetes pod as defined by the user.

name

The name of the pod

namespace

The namespace to create the pod in

metadata

Pod metadata dict

spec

Pod spec dict following kubernetes API conventions

source

File path to pod definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for pod to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for pod (default: 60)

Pod spec must follow kubernetes API conventions:

- spec:
    ports:
    - containerPort: 8080
        name: http
        protocol: TCP

CLI Examples:

salt '*' kubernetes.create_pod name=nginx namespace=default spec='{"containers": [{"name": "nginx", "image": "nginx"}]}'

saltext.kubernetes.modules.kubernetesmod.create_service(name, namespace, metadata, spec, source=None, template=None, saltenv=None, template_context=None, wait=False, timeout=60, **kwargs)

Creates the kubernetes service as defined by the user.

name

The name of the service

namespace

The namespace to create the service in

metadata

Service metadata dict

spec

Service spec dict that follows kubernetes API conventions

source

File path to service definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for service to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for service (default: 60)

Service spec must follow kubernetes API conventions. Port specifications can be:

Simple integer for basic port definition: [80, 443]

Dictionary for advanced configuration:

- spec:
    ports:
      - port: 80
        targetPort: 8080
        name: http    # Required if multiple ports are specified
      - port: 443
        targetPort: web-https  # targetPort can reference container port names
        name: https
        nodePort: 30443       # nodePort must be between 30000-32767

CLI Examples:

salt '*' kubernetes.create_service name=nginx namespace=default spec='{"ports": [80]}'

salt '*' kubernetes.create_service name=nginx namespace=default spec='{
    "ports": [{"port": 80, "targetPort": 8000, "name": "http"}],
    "selector": {"app": "nginx"},
    "type": "LoadBalancer"
}'

saltext.kubernetes.modules.kubernetesmod.create_secret(name, namespace='default', data=None, source=None, template=None, saltenv=None, template_context=None, secret_type=None, metadata=None, wait=False, timeout=60, **kwargs)

Creates the kubernetes secret as defined by the user. Values that are already base64 encoded will not be re-encoded.

Note

Automatic encoding of secret values might cause issues if the values are not correctly identified as base64. If you run into issues - encode the values before passing them to this function.

name

The name of the secret

namespace

The namespace to create the secret in. Defaults to default.

data

A dictionary of key-value pairs to store in the secret

source

File path to secret definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

template_context

Added in version 2.0.0.

Variables to make available in templated files

secret_type

Added in version 2.0.0.

The type of the secret

metadata

Added in version 2.0.0.

Secret metadata dict

wait

Added in version 2.0.0.

Wait for secret to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for secret (default: 60)

CLI Example:

# For regular secrets with plain text values
salt 'minion1' kubernetes.create_secret             passwords default '{"db": "letmein"}'

# For secrets with pre-encoded values
salt 'minion2' kubernetes.create_secret             name=passwords namespace=default data='{"db": "bGV0bWVpbg=="}'

# For docker registry secrets
salt 'minion3' kubernetes.create_secret             name=docker-registry             type=kubernetes.io/dockerconfigjson             data='{".dockerconfigjson": "{"auths":{...}}"}'

# For TLS secrets
salt 'minion4' kubernetes.create_secret             name=tls-secret             type=kubernetes.io/tls             data='{"tls.crt": "...", "tls.key": "..."}'

saltext.kubernetes.modules.kubernetesmod.create_configmap(name, namespace, data, source=None, template=None, saltenv=None, template_context=None, wait=False, timeout=60, **kwargs)

Creates the kubernetes configmap as defined by the user.

name

The name of the configmap

namespace

The namespace to create the configmap in

data

A dictionary of key-value pairs to store in the configmap

source

File path to configmap definition

Changed in version 2.0.0: The configmap definition must be a proper spec with the configmap data in the data key. In previous versions, the rendered output was used as the data directly.

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for configmap to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for configmap (default: 60)

CLI Example:

salt 'minion1' kubernetes.create_configmap             settings default '{"example.conf": "# example file"}'

salt 'minion2' kubernetes.create_configmap             name=settings namespace=default data='{"example.conf": "# example file"}'

saltext.kubernetes.modules.kubernetesmod.create_namespace(name, **kwargs)

Creates a namespace with the specified name.

name

The name of the namespace to create

CLI Example:

salt '*' kubernetes.create_namespace salt
salt '*' kubernetes.create_namespace name=salt

saltext.kubernetes.modules.kubernetesmod.replace_deployment(name, metadata, spec, source=None, template=None, saltenv=None, namespace='default', template_context=None, wait=False, timeout=60, **kwargs)

Replaces an existing deployment with a new one defined by name and namespace, having the specificed metadata and spec.

name

The name of the deployment

metadata

Deployment metadata dict

spec

Deployment spec dict following kubernetes API conventions

source

File path to deployment definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

namespace

The namespace to replace the deployment in. Defaults to default.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for deployment to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for deployment (default: 60)

CLI Example:

salt '*' kubernetes.replace_deployment *args

saltext.kubernetes.modules.kubernetesmod.replace_service(name, old_service, metadata, spec, source=None, template=None, saltenv=None, namespace='default', template_context=None, wait=False, timeout=60, **kwargs)

Changed in version 2.0.0: The old_service parameter was moved to the second position, which pushes metadata, spec, source and template one position further down the parameter list.

Replaces an existing service with a new one defined by name and namespace, having the specified metadata and spec.

name

The name of the service

old_service

The existing service to replace

metadata

Service metadata dict

spec

Service spec dict following kubernetes API conventions

source

File path to service definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

namespace

The namespace to replace the service in. Defaults to default.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for service to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for service (default: 60)

CLI Example:

salt '*' kubernetes.replace_service name=my-service             old_service='{"metadata": {"resource_version": "12345"}, "spec": {"cluster_ip": "10.0.0.1"}}'             metadata='{"labels": {"app": "my-app"}}'             spec='{"ports": [{"port": 80, "targetPort": 8080}], "selector": {"app": "my-app"}}'             source=/path/to/service.yaml             template=jinja             saltenv=base             namespace=default             template_context='{"var1": "value1"}'

saltext.kubernetes.modules.kubernetesmod.replace_secret(name, data, source=None, template=None, saltenv=None, namespace='default', template_context=None, secret_type=None, metadata=None, wait=False, timeout=60, **kwargs)

Replaces an existing secret with a new one defined by name and namespace. Values that are already base64 encoded will not be re-encoded. If a source file is specified, the secret type will be read from the template.

Note

Automatic encoding of secret values might cause issues if the values are not correctly identified as base64. If you run into issues - encode the values before passing them to this function.

name

The name of the secret

data

A dictionary of key-value pairs to store in the secret

source

File path to secret definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

namespace

The namespace to replace the secret in. Defaults to default.

template_context

Added in version 2.0.0.

Variables to make available in templated files

secret_type

Added in version 2.0.0.

The type of the secret

metadata

Added in version 2.0.0.

Secret metadata dict

wait

Added in version 2.0.0.

Wait for secret to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for secret (default: 60)

CLI Example:

# For regular secrets with plain text values
salt 'minion1' kubernetes.replace_secret             name=passwords data='{"db": "letmein"}'

# For secrets with pre-encoded values
salt 'minion2' kubernetes.replace_secret             name=passwords data='{"db": "bGV0bWVpbg=="}'

# For docker registry secrets
salt 'minion3' kubernetes.replace_secret             name=docker-registry             source=/path/to/docker-secret.yaml             secret_type=kubernetes.io/dockerconfigjson

# For TLS secrets
salt 'minion4' kubernetes.replace_secret             name=tls-secret             source=/path/to/tls-secret.yaml             secret_type=kubernetes.io/tls

saltext.kubernetes.modules.kubernetesmod.replace_configmap(name, data, source=None, template=None, saltenv=None, namespace='default', template_context=None, wait=False, timeout=60, **kwargs)

Replaces an existing configmap with a new one defined by name and namespace with the specified data.

name

The name of the configmap

data

A dictionary of key-value pairs to store in the configmap

source

File path to configmap definition

template

Template engine to use to render the source file

saltenv

Salt environment to pull the source file from

Changed in version 2.0.0: Defaults to the value of the saltenv minion option or base.

namespace

The namespace to replace the configmap in. Defaults to default.

template_context

Added in version 2.0.0.

Variables to make available in templated files

wait

Added in version 2.0.0.

Wait for configmap to become ready (default: False)

timeout

Added in version 2.0.0.

Timeout in seconds to wait for configmap (default: 60)

CLI Example:

salt 'minion1' kubernetes.replace_configmap             settings default '{"example.conf": "# example file"}'

salt 'minion2' kubernetes.replace_configmap             name=settings namespace=default data='{"example.conf": "# example file"}'