kubekanvas configure
Discover Kubernetes clusters from your kubeconfig files, test connectivity, configure access credentials, generate encryption keys, and register clusters with your KubeKanvas organization.
Usage
kubekanvas configure [options]Options
| Flag | Description | Default |
|---|---|---|
--scan <path> | Scan a specific file or directory for kubeconfig files | ~/.kube |
--reset | Reset configured clusters and optionally delete encryption keys | — |
--suppress-keys | Skip encryption key creation or deletion during configuration | — |
-y, --yes | Skip all confirmation prompts (non-interactive mode) | — |
What Happens During Configuration
1. Authentication Check
The CLI verifies that you are logged in with a valid authentication session. If not, it prompts you to run kubekanvas login first.
2. Organization Selection
If you belong to a single organization, it is selected automatically. If you belong to multiple, an interactive prompt lets you choose which KubeKanvas organization to register clusters under.
3. Encryption Key Setup
Unless --suppress-keys is provided, the CLI ensures you have an encryption keypair for Kubernetes Secret encryption. If no key exists, a new one is generated and the public key is uploaded to your organization. See kubekanvas keys for more on key management.
4. Kubeconfig Discovery
The CLI scans the specified directory (default ~/.kube) for YAML files that contain valid Kubernetes cluster configurations. It recursively searches subdirectories and validates each file.
5. Cluster Connectivity Testing
For each discovered cluster, the CLI:
- Displays the cluster name, API server URL, and kubeconfig context
- Asks for confirmation before proceeding (unless
--yes) - Tests connectivity by running
kubectl get namespace kube-system - Retrieves a unique cluster UID for de-duplication
6. User Access Configuration
For each reachable cluster, you choose how the CLI will authenticate with Kubernetes:
- Use existing kubeconfig user: The CLI stores a mapping between the cluster and your existing kubeconfig context credentials
- Create a custom KubeKanvas user: The CLI creates a new
kubekanvas-agentuser with a Certificate Signing Request (CSR), binds it to a Kubernetes cluster role of your choice (e.g.,edit,admin,cluster-admin), and stores the client certificate locally
Role selection matters: The view role is read-only and will cause deployments to fail. The cluster-admin role grants full cluster access — use with caution.
7. Server Registration
Each confirmed cluster is registered with the KubeKanvas server under your organization, associated with your CLI's connection ID. If a cluster was already registered, the CLI skips gracefully.
Examples
kubekanvas configurekubekanvas configure --scan /etc/kubernetes/configskubekanvas configure --yeskubekanvas configure --resetkubekanvas configure --reset --suppress-keysFiles Modified
| File | Purpose |
|---|---|
~/.kubekanvas/config.json | Stores connection ID |
~/.kubekanvas/config | Custom kubeconfig with KubeKanvas agent credentials (if created) |
~/.kubekanvas/cluster-mapping.json | Maps cluster names to kubeconfig file paths and contexts |
Next: Connect to KubeKanvas to start receiving deployment commands from the visual IDE.