Flags Configuration
This document describes how to use the flags configuration feature in furyctl, which allows you to store commonly used command flags directly in your furyctl.yaml configuration file.
Overview
The flags configuration feature helps ensure consistent flag usage across team members and environments by allowing you to define default flag values in your configuration file. This eliminates the need to remember and repeatedly type the same flags.
Priority System
The flags configuration follows a priority system where values can be overridden:
- furyctl.yaml flags (lowest priority) - Values defined in the
flagssection - Environment variables (medium priority) - Values set via
FURYCTL_*environment variables - Command line flags (highest priority) - Values passed directly to the command
This means you can set defaults in your configuration file, but still override them when needed.
Important Limitations
Config Flags Are Not Supported in YAML
⚠️ Critical Note: You cannot specify config flags within the flags section of your furyctl.yaml file. This includes flags like:
--config/-cfor specifying configuration file paths- Any flag that points to configuration files
Why this limitation exists: This prevents recursive loading scenarios where:
furyctlloadsfuryctl.yaml- Finds a
configflag pointing to another configuration file - Attempts to load that file, potentially creating infinite loops or unexpected behavior
What still works:
- CLI config flags work normally:
furyctl apply --config /path/to/config.yaml - Environment variables for config:
FURYCTL_CONFIG=/path/to/config.yaml - All other flags can be configured in YAML without any issues
Example of what NOT to do:
# ❌ This will cause a FATAL error
flags:
apply:
config: "/path/to/other-config.yaml" # NOT SUPPORTED
Example of what works perfectly:
# ✅ All other flags work great
flags:
apply:
dryRun: true
timeout: 3600
distroLocation: "/path/to/distribution"
Configuration Structure
Add a flags section to your furyctl.yaml file:
apiVersion: kfd.sighup.io/v1alpha2
kind: OnPremises
metadata:
name: my-cluster
spec:
# ... your cluster configuration
flags:
global:
# Global flags that apply to all commands
debug: true
apply:
# Flags specific to the 'apply' command
skipDepsValidation: true
timeout: 7200
delete:
# Flags specific to the 'delete' command
dryRun: true
Supported Commands
The following commands support flags configuration:
global- Flags that apply to all commandsapply- Cluster deployment and updatesdelete- Cluster deletioncreate- PKI creation (furyctl create pkionly, see below)get- Information retrievaldiff- Configuration comparisonvalidate- Configuration validationdownload- Dependencies downloadconnect- VPN connectionsrenew- Certificate renewaldump- Template rendering
Dynamic Values
You can use dynamic value substitution in flags, just like in the main configuration:
flags:
global:
# Use environment variables
workdir: "{env://PWD}/workspace"
outdir: "{env://HOME}/.furyctl/output"
log: "{env://HOME}/.furyctl/logs/furyctl.log"
apply:
# Reference files relative to config location
distroLocation: "{file://./custom-distribution}"
distroPatches: "{file://./patches}"
# Use environment variables for paths
binPath: "{env://HOME}/.local/bin"
Examples
Basic Configuration
apiVersion: kfd.sighup.io/v1alpha2
kind: OnPremises
metadata:
name: basic-cluster
spec:
distributionVersion: v1.31.0
# ... rest of your cluster configuration
flags:
# Global flags apply to all commands
global:
debug: true
gitProtocol: "https"
workdir: "/tmp/furyctl-workspace"
# Apply command specific flags
apply:
skipDepsValidation: true
dryRun: false
timeout: 7200
vpnAutoConnect: false
skipVpnConfirmation: false
force: ["upgrades"]
# Delete command specific flags
delete:
dryRun: true
skipDepsValidation: false
# Create command specific flags (furyctl create pki only)
create:
path: "/path/to/pki"
Dynamic Values
apiVersion: kfd.sighup.io/v1alpha2
kind: EKS
metadata:
name: dynamic-cluster
spec:
distributionVersion: v1.31.0
# ... rest of your cluster configuration
flags:
global:
# Use environment variables
workdir: "{env://PWD}/furyctl-workspace"
outdir: "{env://HOME}/.furyctl/output"
log: "{env://HOME}/.furyctl/logs/furyctl.log"
apply:
# Reference files relative to config location
distroLocation: "{file://./custom-distribution}"
distroPatches: "{file://./patches}"
# Use environment variables for paths
binPath: "{env://HOME}/.local/bin"
# Combine static and dynamic values
upgradePathLocation: "{env://PWD}/upgrade-paths/v1.31.0"
delete:
# Use environment variable for dry-run control
dryRun: "{env://FURYCTL_DRY_RUN}" # Set to "true" or "false"
Team Standardization
apiVersion: kfd.sighup.io/v1alpha2
kind: EKS
metadata:
name: production-cluster
spec:
distributionVersion: v1.31.0
# ... rest of your cluster configuration
flags:
global:
# Standardize debug output for the team
debug: false
# Standardize git protocol for corporate environments
gitProtocol: "ssh"
# Use consistent workspace location
workdir: "/workspace/furyctl"
apply:
# Safety defaults for production environments
dryRun: false
# Skip dependency validation for faster deployments in CI/CD
skipDepsValidation: false
skipDepsDownload: false
# Increase timeout for large clusters
timeout: 10800 # 3 hours
podRunningCheckTimeout: 600 # 10 minutes
# VPN settings for corporate network
vpnAutoConnect: true
skipVpnConfirmation: true
# Force certain behaviors for consistency
force: ["pods-running-check", "upgrades"]
delete:
# Safety first - always dry run by default
dryRun: true
# Do not force: furyctl asks for a confirmation
force: false
Upgrade Scenario
apiVersion: kfd.sighup.io/v1alpha2
kind: OnPremises
metadata:
name: upgrade-cluster
spec:
distributionVersion: v1.31.0
# ... rest of your cluster configuration
flags:
global:
# Enable detailed logging during upgrades
debug: true
log: "{env://PWD}/upgrade-logs/upgrade-{env://USER}.log"
apply:
# Upgrade-specific settings
upgrade: true
upgradePathLocation: "{file://./upgrade-paths}"
# Skip certain validations during upgrades
skipDepsValidation: true
skipNodesUpgrade: false
# Extended timeouts for upgrade operations
timeout: 14400 # 4 hours
podRunningCheckTimeout: 900 # 15 minutes
# Force upgrade-related operations
force: ["upgrades", "migrations"]
# Run specific phases for controlled upgrades
phase: "distribution"
# Post-upgrade validation phases
postApplyPhases: ["validation", "smoke-tests"]
# Safety settings
dryRun: false
# Other commands like validate, download, connect, renew, dump
# also support flags - see their specific documentation or use --help
Usage
To use flags configuration:
- Add a
flagssection to yourfuryctl.yamlfile - Configure the flags you want to set by default
- Run furyctl commands normally - the flags will be automatically applied
# The flags from your configuration will be automatically used
furyctl apply
# You can still override flags when needed
furyctl apply --timeout 3600 --dry-run
Best Practices
- Start simple - Begin with basic flags and add more as needed
- Use dynamic values - Leverage environment variables for user-specific paths
- Safety first - Consider setting
dryRun: trueby default for destructive operations - Team consistency - Use flags configuration to standardize behavior across your team
- Document choices - Add comments explaining why certain flags are set
Validation
The flags configuration includes built-in validation that will stop execution with FATAL errors for:
- Unsupported flags for specific commands - Commands will exit immediately with detailed error messages
- Invalid flag values (e.g., negative timeouts, invalid protocols)
- Conflicting flag combinations (e.g.,
upgradewithupgradeNode) - Configuration file access issues (permissions, malformed YAML)
⚠️ Breaking Change: Invalid flags now cause FATAL errors and stop execution immediately. This ensures configuration problems are caught early rather than potentially causing issues later in the process.
Note: If no furyctl.yaml file is present, commands that don't require configuration (like furyctl create pki) will work normally without any errors.
Supported Flags
Note: All flag names in the furyctl.yaml file use camelCase format (e.g., noTty, skipDepsValidation). These are automatically converted to kebab-case internally for CLI compatibility (e.g., --no-tty, --skip-deps-validation).
Global Flags
debug(bool) - Enable debug outputdisableAnalytics(bool) - Deprecated, has no effectnoTty(bool) - Disable TTYworkdir(string) - Working directoryoutdir(string) - Output directorylog(string) - Log file pathgitProtocol(string) - Git protocol to use ("https" or "ssh")
Apply Command Flags
phase(string) - Limit execution to specific phasestartFrom(string) - Start execution from specific phasedistroLocation(string) - Distribution locationdistroPatches(string) - Distribution patches locationbinPath(string) - Binary pathskipNodesUpgrade(bool) - Skip nodes upgradeskipDepsDownload(bool) - Skip dependencies downloadskipDepsValidation(bool) - Skip dependencies validationdryRun(bool) - Dry run modevpnAutoConnect(bool) - Auto connect VPNskipVpnConfirmation(bool) - Skip VPN confirmationforce(array) - Force optionspostApplyPhases(array) - Post apply phasestimeout(int) - Timeout in secondspodRunningCheckTimeout(int) - Pod running check timeoutupgrade(bool) - Enable upgrade modeupgradePathLocation(string) - Upgrade path locationupgradeNode(string) - Specific node to upgradeairgapBundle(string) - Air-gapped bundle pathforceExtract(bool) - Force bundle re-extraction
Delete Command Flags
phase(string) - Limit execution to specific phasedistroLocation(string) - Distribution locationdistroPatches(string) - Distribution patches locationbinPath(string) - Binary pathdryRun(bool) - Dry run modeskipVpnConfirmation(bool) - Skip VPN confirmationvpnAutoConnect(bool) - Auto connect VPNskipDepsDownload(bool) - Skip dependencies downloadskipDepsValidation(bool) - Skip dependencies validationairgapBundle(string) - Air-gapped bundle pathforceExtract(bool) - Force bundle re-extractionforce(bool) - Delete without a confirmation. Note the different type:applytakes an array here
Create Command Flags
Only furyctl create pki reads these flags. furyctl create config creates the configuration file,
thus it cannot read flags from one: it stops when the file is already present.
path(string) - Path where to save PKI filesetcd(bool) - Create PKI only for etcdcontrolplane(bool) - Create PKI only for Kubernetes control plane
Get and Diff Command Flags
Get Command:
binPath(string) - Binary pathdistroLocation(string) - Distribution locationskipDepsDownload(bool) - Skip dependencies downloadskipDepsValidation(bool) - Skip dependencies validationairgapBundle(string) - Air-gapped bundle pathforceExtract(bool) - Force bundle re-extractionformat(string) - Output format ofget cluster-info. Values are text, json and yamlfrom(string) - Version to show the upgrade paths of, instead of the version in the configuration filekind(string) - Kind of cluster to show the supported versions or the upgrade paths of
Diff Command:
phase(string) - Limit execution to specific phasedistroLocation(string) - Distribution locationdistroPatches(string) - Distribution patches locationbinPath(string) - Binary pathupgradePathLocation(string) - Upgrade path locationairgapBundle(string) - Air-gapped bundle pathforceExtract(bool) - Force bundle re-extraction
Validate Command:
distroLocation(string) - Distribution locationdistroPatches(string) - Distribution patches locationbinPath(string) - Binary path
Download Command:
binPath(string) - Binary pathdistroLocation(string) - Distribution locationdistroPatches(string) - Distribution patches locationbundleOutput(string) - Bundle tarball output path
Connect Command:
profile(string) - OpenVPN profile name
Renew Command:
binPath(string) - Binary pathdistroLocation(string) - Distribution locationskipDepsDownload(bool) - Skip dependencies downloadskipDepsValidation(bool) - Skip dependencies validationairgapBundle(string) - Air-gapped bundle pathforceExtract(bool) - Force bundle re-extraction
Dump Command:
distroLocation(string) - Distribution locationdistroPatches(string) - Distribution patches locationdryRun(bool) - Dry runnoOverwrite(bool) - Do not overwrite existing filesskipValidation(bool) - Skip validation