Skip to content

Latest commit

 

History

History
227 lines (143 loc) · 6.83 KB

README.md

File metadata and controls

227 lines (143 loc) · 6.83 KB

kfilt

Build Status Code Coverage Go Report Card LICENSE Releases

kfilt can filter Kubernetes resources.

What is kfilt?

kfilt is a tool that lets you filter specific resources from a stream of Kubernetes YAML manifests. It can read manifests from a file, URL, or from stdin.

kfilt was primarily created to assist developers who are creating Helm charts or Kustomize bases. Often, when making changes, it is helpful to narrow down focus to a specific resource or set of resources in the output. Without kfilt, you might redirect output to a file for inspection in your text editor or to write complicated grep commands. kfilt makes it easy to filter the output to see just the resources you are currently interested in. Or, to exclude specific resources.

You can also use kfilt to selectively apply (or delete) resources with kubectl.

It is easiest to understand with some examples.

Examples

Working with Files or URLs

Only output a ServiceAccount named "test":

kfilt -f ./pkg/decoder/test.yaml -i kind=ServiceAccount,name=test

Output all Service Accounts:

kfilt -f http://bit.ly/2xSiCJL -i kind=ServiceAccount

Working with Helm charts

kfilt can be used as a more flexible alternative to the -x option of helm template. In this example, we will only output rendered Service resources from a Helm chart:

helm template chart | kfilt -i kind=service

We also have the ability to exclude resources. Here we will exclude all Secrets before applying a Chart to a cluster.

helm template chart | kfilt -x kind=secret | kubectl apply -f -

Working with Kustomize

Only output the ConfigMaps in a Kustomize base.

kustomize build github.com/kubernetes-sigs/kustomize//examples/helloWorld | kfilt -i kind=ConfigMap

Output only the resources named "the-deployment".

kustomize build github.com/kubernetes-sigs/kustomize//examples/helloWorld | kfilt -i name=the-deployment

Working with kubectl

Find all resources named "nginx-ingress-controller" regardless of kind.

kubectl get all -A -oyaml | kfilt -i name=nginx-ingress-controller

Installation

kfilt is available on Linux, Mac, and Windows 1 and binaries are available on the releases page.

Docker

You can also run kfilt as a Docker container. Make sure you include -i in your docker run command.

kustomize build base | docker run --rm -i ryane/kfilt -k ConfigMap

AUR

kfilt is on the Arch User Repository (AUR).

asdf Plugin

@feniix created an asdf plugin.

nix flake

nix run github:ryane/kfilt#kfilt -- -f ./pkg/decoder/test.yaml -k serviceaccount

Running as a Kustomize Plugin (experimental)

See plugin/kustomize for an experimental Kustomize plugin.

Usage

Including Resources

You can use --include or -i to control which resources to include in the kfilt output. This argument takes a list of simple key value pairs that make up your query. The following keys are currently supported:

Key Field Example
kind, k kind ServiceAccount
name, n metadata.name my-app
group, g apiVersion rbac.authorization.k8s.io
version, v apiVersion v1
namespace, ns metadata.namespace kube-system
labels, l metadata.labels app=my-app

Note that it is possible to use wildcards (*, and ?) when filtering by name.

Examples

Filter by kind
kfilt -f ./pkg/decoder/test.yaml -i kind=configmap
Filter by group
kfilt -f ./pkg/decoder/test.yaml -i g=config.istio.io
Filter by name and kind

You can combine keys in a single --include by separating them with a comma. In this example, we are filtering to match ServiceAccount resources named "test":

kfilt -f ./pkg/decoder/test.yaml -i k=ServiceAccount,n=test
Filter by name using wildcards
kfilt -f ./pkg/decoder/test.yaml -n "test*"

You can use * and ? wildcard characters.

Filter by multiple kinds

You can use multiple --include flags. kfilt will output resources that match any one of the includes. For example, to output ServiceAccounts and ConfigMaps you could use:

kfilt -f ./pkg/decoder/test.yaml -i k=serviceaccount -i k=configmap
Filter with Label Selectors
kfilt -f ./pkg/decoder/test.yaml -i labels=app=test

Excluding Resources

The --exclude or -x flag will allow you to exclude resources. This supports the same key value pairs as the --include flag.

Examples

Exclude by kind
kfilt -f ./pkg/decoder/test.yaml -x kind=configmap
Exclude by name
kfilt -f ./pkg/decoder/test.yaml -x name=test
Exclude multiple kinds
kfilt -f ./pkg/decoder/test.yaml -x kind=configmap -x k=serviceaccount
Exclude with Label Selectors
kfilt -f ./pkg/decoder/test.yaml -x labels=app=test

Shortcuts

Because "kind", "name", and "labels" are the most commonly used fields to filter by, kfilt has special flags allowing you to save some typing.

You can include by "kind" by using the --kind (or -k) flag with just the name of the kind you want to filter by. You can use --exclude-kind (or -K) for exclusions.

The corresponding flags for "name" queries are --name (-n) and --exclude-name (-N).

Finally, you can use label selectors with the --labels (-l) and --exclude-labels (L) flags.

Include ConfigMaps and Service Accounts

kfilt -f ./pkg/decoder/test.yaml -k configmap -k serviceaccount

Exclude resources named "test"

kfilt -f ./pkg/decoder/test.yaml -N test

Include resources labeled with "app=test"

kfilt -f ./pkg/decoder/test.yaml -l app=test

1 note: kfilt has not been tested extensively on Windows. Please file an issue if you run into any problems.