kwctl is the go-to CLI tool for Kubewarden users.

Related tags



kwctl is the go-to CLI tool for Kubewarden users.

Think of it as the docker CLI tool if you were working with containers.

How does kwctl help me?

As a policy author

  • e2e testing of your policy. Test your policy against crafted Kubernetes requests, and ensure your policy behaves as you expect. You can even test context-aware policies, that require access to a running cluster.

  • Embed metadata in your Wasm module, so the binary is annotated with the permissions it needs to execute.

  • Publish policies to OCI registries.

  • Generate initial ClusterAdmissionPolicy scaffolding for your policy.

As a cluster administrator

  • Inspect remote policies. Given a policy in an OCI registry, or in an HTTP server, show all static information about the policy.

  • Dry-run of a policy in your cluster. Test the policy against crafted Kubernetes requests, and ensure the policy behaves as you expect given the input data you provide. You can even test context-aware policies, that require access to a running cluster, also in a dry-run mode.

  • Generate ClusterAdmissionPolicy scaffolding for a given policy.


  • The UX of this tool is intended to be as easy and intuitive as possible.
  • kwctl: Initial implementation

    kwctl: Initial implementation

    Create the kwctl tool. This CLI tool is the go-to tool for Kubewarden users. It wil allow to perform:

    • Policy image handling
      • Pull (from OCI registry, HTTP server...) -- akin to docker pull
      • Pull and run -- akin to docker run
      • Push/Publish (to OCI registry) -- akin to docker push
        • Being capability focused, the publishing mechanism will take the Wasm artifact, and a specification of what resources the policy can handle. This information is added to the final artifact, and finally published.
    • Generate Kubernetes CRD scaffolding
      • Given a Wasm artifact with permissions, the Kubernetes CRD scaffolding will generate a ClusterAdmissionPolicy that is ready to be applied to a Kubernetes cluster, assuming it has Kubewarden installed.

    This is a mid-time overview, but the immediate action is to split the policy-server project into different crates and executables:

    opened by ereslibre 3
  • Enforce policy has metadata before pushing it

    Enforce policy has metadata before pushing it

    We should enforce all the policies to have metadata. We need that because we want to have policy-server load only policies that implement a certain version of communication protocol.

    Acceptance criteria

    kwctl push refuses to publish a policy to a container registry if the policy has not been annotated.

    bug enhancement 
    opened by flavio 2
  • Introduce

    Introduce "pretty" inspect output

    The kwctl inspect command now produces colorized and formatted output.

    It's still possible to produce simple YAML outpout by using the -o yaml flag.

    Note well: this branch depends on a currently unreleased version of the policy-evaluator crate, see

    Input metadata

    The next examples take a policy that was annotated using this metadata:

    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations: ["CREATE", "UPDATE"]
    mutating: false
      production: false
      name.castelli.hello: world
      io.kubewarden.policy.title: psp-apparmor
      io.kubewarden.policy.description: Replacement for the Kubernetes Pod Security Policy that controls the usage of AppArmor profiles Flavio Castelli
      io.kubewarden.policy.license: Apache-2.0
      io.kubewarden.policy.usage: |
        This policy works by defining a whitelist of allowed AppArmor profiles. Pods are then inspected at creation and update time, to ensure only approved profiles are used.
        When no AppArmor profile is defined, Kubernetes will leave the final choice to the underlying container runtime. This will result in using the default AppArmor profile provided by Container Runtime. Because of that, the default behaviour of this policy is to accept workloads that do not have an AppArmor profile specified.
        The policy can be configured with the following data structure:
        # list of allowed profiles
        - runtime/default
        - localhost/my-special-workload

    YAML output

    The kwctl inspect --output yaml ... command produces the old yaml output:


    New "pretty" output

    By default this is the output produced by kwctl inspect:


    opened by flavio 2
  • Extend the `push` command

    Extend the `push` command

    Change the push command to take two positional parameters:

    1. The policy to be pushed (source)
    2. The registry destination (destination)

    This allows to push not only local files, but also policies that are inside of the local storage.

    This makes possible to push an upstream policy into a local registry.


    opened by flavio 2
  • Metadata commands

    Metadata commands

    Introduce the annotate and the inspect commands.



    $ kwctl annotate
               -m ../psp-apparmor/metadata.yml \
               -o annotated.wasm \

    This command reads the user-provided metadata file, reads a vanilla Wasm file and produces a Wasm file that has the metadata embedded as a custom Wasm section.


    $ kwctl inspect file:///home/flavio/hacking/kubernetes/kubewarden/kwctl/annotated.wasm
    protocolVersion: v1
      - apiGroups:
          - ""
          - v1
          - pods
          - CREATE
          - UPDATE
      io.kubewarden.policy.url: ""
      io.kubewarden.policy.license: Apache-2.0
      io.kubewarden.policy.source: "" Flavio Castelli

    This command dumps the metadata stored inside of a policy to the stdout.

    The command works also with policies that are inside of the main store, plus it handles policies that do not have metadata:

    $ kwctl inspect 'registry://'`
    Error: No Kubewarden metadata found inside of 'registry://'.
    Policies can be annotated with the `kwctl annotate` command.
    opened by flavio 1
  • Handle the annotatedBy field of policy metadata

    Handle the annotatedBy field of policy metadata

    Ensure kwctl writes its version when annotating a policy.

    At the same time, ensure inspection of a policy shows who annotated it.

    opened by flavio 1
  • Policy testdrive missing features

    Policy testdrive missing features

    This PR brings back two features that got lost during the policy-testdrive -> kwctl rewrite. They are both related with the behaviour of the run command:

    1. Allow user to specify the policy settings on the cli, via the new --settings-json flag. This makes the process of writing bat tests easier
    2. Ensure the settings provided by the user are actually validated. This must happen before the request is evaluated. Invalid settings lead kwctl to exit with an error
    opened by flavio 1
  • feat: allow to skip scheme on `kwctl run` command

    feat: allow to skip scheme on `kwctl run` command

    If kwctl run command is called with a module without a scheme, assume the file:// scheme, rooted on the local directory. This way, it's possible to run modules in the following ways:

    • kwctl run registry:// -s <settings> -r <request>
    • kwctl run file://$(pwd)/safe-labels.wasm -s <settings> -r <request>
    • kwctl run safe-labels.wasm -s <settings> -r <request>
    opened by ereslibre 1
  • Verify policy author workflow

    Verify policy author workflow

    kwctl should assist the policy authors by allowing this workflow:

    • Policy author creates a brand new policy. This is done using the step-by-step instructions provided by our docs
    • Policy author builds the policy. This depends on the programming language, but the end result is always the same: a Wasm file like policy.wasm.
    • Policy author creates a metadata.yaml file. This is done using the editor of choice of the developer
    • Policy author annotates the policy. This is done using kwctl annotate
    • Policy author verifies the policy metadata. This can be done using kwctl inspect
    • Policy author publishes the policy. This can be done using kwctl push
    opened by flavio 1
  • Verify Kubernetes administrator workflow

    Verify Kubernetes administrator workflow

    kwctl should help Kubernetes administrators to embrace Kubewarden by providing this workflow:

    • User discovers policy (via policy hub)
    • User downloads the policy via kwctl pull
    • User experience with different settings of the policy, verifies the policy works as intended. This is done via kwctl run
    • User scaffolds a ClusterAdmissionPolicy resource via the kwctl manifest
    • User enforces policy in production via kubectl apply -f clusteradmissionpolicy.yaml
    opened by flavio 1
  • A docker config without `auth` in the `auths` map breaks config unmarshaling

    A docker config without `auth` in the `auths` map breaks config unmarshaling

    By default, kwctl reads the docker configuration from the user home directory in ~/.docker/config.json. If this map contains something like the following:

      "auths": {
        "some-host": {}

    The unmarshaling of the JSON structure fails, because it expects an auth key inside every auths entry, such as:

      "auths": {
        "some-host": {
          "auth": "auth-info"

    Understand under what circumstances this can happen, and fix kwctl so it doesn't error out with an unmarshaling error.

    opened by ereslibre 0
  • RUSTSEC-2018-0015: term is looking for a new maintainer

    RUSTSEC-2018-0015: term is looking for a new maintainer

    term is looking for a new maintainer

    | Details | | | ------------------- | ---------------------------------------------- | | Status | unmaintained | | Package | term | | Version | 0.5.2 | | URL | | | Date | 2018-11-19 |

    The author of the term crate does not have time to maintain it and is looking for a new maintainer.

    Some maintained alternatives you can potentially switch to instead, depending on your needs:

    See advisory page for additional details.

    opened by github-actions[bot] 0
  • Fix cluster awareness logic

    Fix cluster awareness logic

    Cluster awareness needs to be fixed, so that:

    • When a policy that is not cluster aware is executed, kwctl does not try to initialize a Kubernetes client.
    • When a policy that is cluster context aware is executed, kwctl does the following:
      • Fetch the cluster information
      • Execute policy once the cluster information has been retrieved
      • Exit

    Despite kwctl and policy-server share some cluster aware code, they behave in a different way:

    • kwctl by default does not fetch the cluster context, and thus, does not initialize a Kubernetes client, unless the metadata of the policy signals that the policy is cluster aware.
    • kwctl does not initialize a context refresh loop.
    • If the policy is context aware, kwctl initializes the cluster context with an initial request, and then runs the policy in the Wasm environment. waPC endpoints on the host expose the information to the guest, because the policy is not started until the context is fetchec from the cluster.

    The policy-server initializes the cluster context, and keeps an infinite loop, refreshing the context information on a shared global variable, protected by RwLocks. This ensures that there's only one writer at any given time, and N readers.

    opened by ereslibre 2
  • Simplify the installation process

    Simplify the installation process

    Right now users can go to our GH release page and download the kwctl binary from it.

    We can improve their installation story by integrating with some installers like:


    and similar

    opened by flavio 0
  • Build binary for Windows and macOS

    Build binary for Windows and macOS

    Update the GH release action to build binaries also for Windows and macOS

    opened by flavio 0
  • Annotation and store workflow

    Annotation and store workflow

    Currently, kwctl allows to download policies from OCI registries (with the registry://) scheme, and from HTTP(s) servers (with the https:// and http:// schemes).

    Annotating a policy right now looks as follows: kwctl annotate <wasm-path> --metadata-path <metadata-path> --output-path <output-path>.

    The problem with this annotate approach is that it is non-optimal to download a policy from a registry or an HTTP server, and annotate the policy, to use the annotated version from the store afterwards.

    Here follows a proposal to store policies, so it's easy to download policies, annotate locally on the store, and find out whether a policy is modified locally from what got downloaded from the server in the first place.

    • When doing a kwctl pull, directly or indirectly through other commands that pull a policy to the store, keep the same directory structure, but append the SHA1 sum of the contents of the policy to the filename. If we have:
    > tree ~/.cache/kubewarden/
    └── store
        └── registry
                └── kubewarden
                    └── policies
                        └── safe-labels:v0.1.2
    5 directories, 1 file

    kwctl would have stored this as the following. This is: appending the SHA1 sum of the policy to the filename.

    > tree ~/.cache/kubewarden/
    └── store
        └── registry
                └── kubewarden
                    └── policies
                        └── safe-labels:v0.1.2-91ee66cff609bfc65d18ce7fd35f5b604b7ac0a5
    5 directories, 1 file

    By using this structure, we can check at all times that the safe-labels:v0.1.2 file is unaltered. This implies that the binary data, and thus, the Wasm custom sections are unaltered.

    • It's possible to annotate policies by using kwctl annotate, in the following form:
      • If kwctl annotate misses a -o option, it will annotate the policy in the store, pulling it if necessary. Only registry://, https:// and http:// policies can be annotated this way. If a file:// policy is provided, the original policy file will be overriden with the annotated version in the local path.
      • If kwctl annotate has a -o argument, the annotated policy will be written to the target file, leaving the original untouched; the store will also not be altered. The original could come from a file://, registry://, http:// or https://.

    When policies are listed using kwctl policies we will show policy metadata, and also whether the policy is locally modified by showing an asterisk on the entry, for example: this can be checked by computing the SHA1-sum of the policy contents, and comparing it to the <sha1sum> part of the filename <policy-name>-<sha1sum> in the store.

    Thus, I as a user, can do the following:

    • kwctl annotate registry:// -m /path/to/local/metadata.yaml
      • Pulls policy to memory: computes SHA-1 of the contents: 91ee66cff609bfc65d18ce7fd35f5b604b7ac0a5
      • Writes the policy to the main store, appending the SHA1-sum: ~/.cache/kubewarden/store/registry/
      • Annotates the policy with the metadata, and writes it to ~/.cache/kubewarden/store/registry/<new SHA1-sum>

    Whenever a user refers to a policy from the store, they can refer to the "upstream" one, like: registry://, or a "store" version one: registry://, or registry://<new SHA1-sum> if they want to refer to the locally annotated version of the policy.

    opened by ereslibre 0
  • Add a `login` subcommand

    Add a `login` subcommand

    Right now kwctl reuses the docker credentials to be able to pull and push to OCI registries. However, what if the user doesn't have the credentials for a certain registry?

    Acceptance criteria

    • kwctl keeps looking for the docker credentials, and uses them when available
    • kwctl login creates its own credential files, with the username/password of the registry that was provided to the login subcommand
    opened by flavio 0
  • Add progress bar when pulling

    Add progress bar when pulling

    We should have a nice progress bar that helps understand what is happening behind the scenes. Right now pull doesn't show anything at all

    enhancement good first issue 
    opened by flavio 0
dua (-> Disk Usage Analyzer) is a tool to conveniently learn about the usage of disk space of a given directory

dua (-> Disk Usage Analyzer) is a tool to conveniently learn about the usage of disk space of a given directory. It's parallel by default and will max

Sebastian Thiel 889 Jun 7, 2021
A minimal CLI framework written in Rust

seahorse A minimal CLI framework written in Rust Features Easy to use No dependencies Typed flags(Bool, String, Int, Float) Documentation Here Usage T

Keisuke Toyota 147 Jun 15, 2021
A CLI utility installed as "ansi" to quickly get ANSI escape sequences. Supports the most basic ones, like colors and styles as bold or italic.

'ansi' - a CLI utility to quickly get ANSI escape codes This Rust project called ansi-escape-sequences-cli provides an executable called ansi which ca

Philipp Schuster 5 May 3, 2021
A full featured, fast Command Line Argument Parser for Rust

clap Command Line Argument Parser for Rust It is a simple-to-use, efficient, and full-featured library for parsing command line arguments and subcomma

null 6k Jun 13, 2021
A curated list of replacements for existing software written in Rust

Awesome Alternatives in Rust A curated list of replacements for existing software written in Rust. If you want to contribute, please read CONTRIBUTING

Takayuki Maeda 1.7k Jun 13, 2021
Punic is a remote caching CLI built for Apple's .xcframework

Punic is a remote caching CLI built for Carthage that exclusively supports Apple's .xcframeworks.

Shred Labs 16 Jun 10, 2021
CLI tool to bake your fresh and hot MD files

At least once in your Rust dev lifetime you wanted to make sure all code examples in your markdown files are up-to-date, correct and code is formated, but you couldn't make that done with already existing tools - fear not!

Patryk Budzyński 39 May 8, 2021
CLI calculator app and library

calc Yet another CLI calculator. Inspired by the excellent Installation With a Rust toolchain in place: cargo inst

Peter Goodspeed-Niklaus 25 May 29, 2021
A tactics trainer for the command line

Chess Tactics CLI Practice some chess tactics in your terminal while you wait for your code to compile. Fetches tactics from this tactics API. Built W

Marcus Buffett 11 May 21, 2021
yayagram - Play nonograms/picross in your terminal

yayagram is a puzzle game in which you fill out a grid with cells based on logic and number clues.

r00ster 13 Jun 11, 2021
rip is a command-line deletion tool focused on safety, ergonomics, and performance

rip (Rm ImProved) rip is a command-line deletion tool focused on safety, ergonomics, and performance. It favors a simple interface, and does not imple

Kevin Liu 363 Jun 7, 2021
😱 Panic messages for humans.

human-panic Panic messages for humans. Handles panics by calling std::panic::set_hook to make errors nice for humans. Documentation Why? Whe

Rust CLI WG 794 Jun 7, 2021
Intuitive find & replace CLI (sed alternative)

sd - s[earch] & d[isplace] sd is an intuitive find & replace CLI. The Pitch Why use it over any existing tools? Painless regular expressions sd uses r

Gregory 2.3k Jun 4, 2021
A Text User Interface library for the Rust programming language

Cursive Cursive is a TUI (Text User Interface) library for rust. It uses ncurses by default, but other backends are available. It allows you to build

Alexandre Bury 2.3k Jun 11, 2021