pkcli

What is pkcli?

A CLI tool written in Rust that secures private keys in exported Keycloak realm files for GitOps workflows with ArgoCD, argocd-vault-plugin (AVP), and HashiCorp Vault.

• Replace privateKey values with argocd-vault-plugin inline path references pointing to secrets in Vault
• Convert exported realm data to a KeycloakRealmImport CR (k8s.keycloak.org/v2alpha1) ready for cluster import
• Save extracted private keys to Vault with diff-based updates (only writes when changes are detected)

Why?

Because I wanted an excuse to learn a bit of Rust and I had a usecase for it.

And I finally got an excuse to generate a fancy Github picture. ☝️

Installation

Pre-built binaries

Download the latest binary from GitHub Releases.

Build from source

cargo build --release

The binary will be at target/release/pkcli.

Usage

Prerequisites

pkcli requires a Vault token for authentication. Provide it via environment variable or the -t flag:

export VAULT_TOKEN=<your-vault-token>

Examples

# Full workflow: parse keycloak export, replace private keys with AVP paths, update Vault
./pkcli -f exported_keycloak_data.json -c <CLUSTER> -t <VAULT_TOKEN>

# Only replace privateKeys with argocd-vault-plugin paths (writes YAML, no Vault interaction)
./pkcli -f exported_keycloak_data.json -c <CLUSTER> -t <VAULT_TOKEN> update-avp

# Only update Vault with secrets (no YAML output)
./pkcli -f exported_keycloak_data.json -c <CLUSTER> -t <VAULT_TOKEN> update-vault

# Read from stdin and write YAML to stdout
cat exported_keycloak_data.json | ./pkcli -f- -c <CLUSTER> -k <KEYCLOAK-CR-NAME> -t <VAULT_TOKEN> > realm.yaml

# Process all JSON files in a directory
./pkcli -d exported_keycloak_data/ -c <CLUSTER> -t <VAULT_TOKEN>

# Write output YAML to a specific directory
./pkcli -f exported_keycloak_data.json -c <CLUSTER> -t <VAULT_TOKEN> -o /path/to/output/

How it works

When run without a subcommand, pkcli performs the following steps:

1. Reads the Keycloak realm export JSON and extracts privateKey values from components.org.keycloak.keys.KeyProvider entries.
2. Replaces each private key with an AVP inline path reference: <path:secret/data/<vault-path>#<id>> (where vault-path defaults to argocd/<cluster>).
3. Wraps the modified realm data in a KeycloakRealmImport CRD and writes it as YAML.
4. Compares extracted keys with what is currently in Vault at the same path and only updates if changes are detected.

CLI Reference

Run pkcli --help for all available options:

Option	Short	Description	Default
--cluster	-c	Cluster name (used to derive the default Vault path)	cluster01
--filename	-f	Input file (use - for stdin)
--directory	-d	Process all JSON files in directory
--output-directory	-o	Output directory for YAML files	.
--vault-addr	-a	Vault server address	http://127.0.0.1:8200
--vault-token	-t	Vault token (or VAULT_TOKEN env var)
--vault-mount	-m	Vault mount path	secret
--vault-path	-p	Override the Vault path, making --cluster unused (used for both Vault storage and AVP path references)	argocd/<cluster>
--keycloak-cr-name	-k	Custom name for the Keycloak CR

Roadmap

• Authenticate with Vault AppRole
• Support other Secret Managers (GCP, Azure, AWS)
• Run the kc.sh export script in a Kubernetes pod and grab the realm data

License

This project is licensed under the Beerware License. If you like it, feel free to buy me a beer if we ever meet!