Carvel Logo

Management Commands Reference

Package

Package commands provides options to interact with package repositories, available packages and package installs.

Available packages

The package available group of commands can be used to get or list packages available in a namespace or all namespaces.

Listing available packages

The package available list command can be used to get a list of packages available in one or all namespaces.

$ kctrl package available list

A package can also be passed to get different available versions of the package.

$ kctrl package available list -p pkg.test.carvel.dev

Supported flags:

  • -A, --all-namespaces string, List available packages in all namespaces
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • -p, --package, string, List all available versions of package
  • --summary, boolean, Show summarized list of packages (default true)
  • --wide, boolean, Show additional info

Getting details of available packages

The package available get command can be used to get details of available packages or specific versions of a package.

$ kctrl package available get -p pkg.test.carvel.dev
# or...
$ kctrl package available get -p pkg.test.carvel.dev/1.0.0

The values-schema flag can be used to get the available values schema for a specific version of the package.

$ kctrl package available get -p pkg.test.carvel.dev/1.0.0 --values-schema

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • -p, --package, string, List all available versions of package
  • --values-schema, string, Values schema of the package (optional)

Installed Packages

The package installed group of commands can be used to view, create and update installed packages.

Installing a package

The package installed create command can be used to create a new installation. The package install command is a sugared alternative for the same.

$ kctrl package installed create --package-install cert-man --package cert-manager.community.tanzu.vmware.com --version 1.5.4
# or...
$ kctrl package install --package-install cert-man --package cert-manager.community.tanzu.vmware.com --version 1.5.4

A values file can also be passed while running this command.

$ kctrl package install --package-install cert-man --package cert-manager.community.tanzu.vmware.com --version 1.5.4 --values-file values.yml

Supported flags:

  • -p, --package string, name of available package consumed by the installation
  • --version string, version of package that the package install should consume
  • --service-account-name string, Name of an existing service account used to install underlying package contents, optional
  • --namespace string, Specified namespace for package installation
  • --dangerous-allow-use-of-shared-namespace boolean, Allow installation of packages in shared namespaces (default, kube-public)
  • --wait boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout duration, Maximum amount of time to wait in wait phase (default 30m0s)
  • --values boolean, Add or keep values supplied to package install, optional (default true)
  • --values-file string, The path to the configuration values file, optional
  • --ytt-overlay-file string, Path to ytt overlay file (can also be a directory)
  • --ytt-overlays boolean, Add or keep ytt overlays (default true)

Updating an installed package

The package installed update command can be used to update an existing installation to a newer version or with a new values file. To update to a newer version:

$ kctrl package installed update --package-install cert-man --version 1.6.1

To update to a newer values file:

$ kctrl package installed update --package-install cert-man --values-file updated-values.yml

Supported flags:

  • --version string, version of package that the package install should consume
  • --installboolean, Install package if the installed package does not exist (default false)
  • --namespace string, Specified namespace to find package installation to be updated in
  • --wait boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout duration, Maximum amount of time to wait in wait phase (default 30m0s)
  • --values boolean, Add or keep values supplied to package install, optional (default true)
  • --values-file string, The path to the configuration values file, optional
  • --ytt-overlay-file string, Path to ytt overlay file (can also be a directory)
  • --ytt-overlays boolean, Add or keep ytt overlays (default true)

Listing package installs

The package installed list command can be used to list all installed packages.

$ kctrl package installed list

Supported flags:

  • -n, --namespace string, Specify namespace where kctrl should look for package installs
  • -A, --all-namespaces boolean, List installed packages in all namespaces

Getting details for installed package

The package installed get command can be used to fetch information for an installed package.

$ kctrl package installed get --package-install cert-man

This can also be used to view the values being used with the package install.

$ kctrl package installed get --package-install cert-man --values

Or to download the values file consumed by the installation.

$ kctrl package installed get --package-install cert-man --values-file-output output-values.yml

Pausing reconciliation for a package install

The kctrl package installed pause command can be used to pause reconciliation for a package installation.

$ kctrl package installed pause -i cert-man

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)

Triggering reconciliation for package installation

The kctrl package installed kick command can be used to trigger reconciliation for an installed package.

$ kctrl package installed kick -i cert-man
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • --wait boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout duration, Maximum amount of time to wait in wait phase (default 5m0s)

Observing status of app created by package installation

The kctrl package installed status command can be used to observe the status of the app created by the package installation with information from the last reconciliation. The command tails and streams app status updates till the app reconciles or fails if the command is run while the installation is reconciling.

$ kctrl package installed status -i cert-man

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)

Deleting package installatiions

The package installed delete command can be used to delete package installations and resources created along with it by kctrl.

$ kctrl package installed delete -i cert-man

Created resources other than the PackageInstall resource might include Secrets, Service Accounts, Cluster Roles and Cluster Role Bindings which are cleaned up if they were created while installing the package using the CLI.

Shared flags

  • -i, --package-install string, assigned name for a package installation

Created resources

If a service account name is not specified using a flag while creating a package installation, kctrl creates a service account, cluster role and cluster role binding to be used by the package install.

If values are specified using a values file, kctrl creates a secret using the values that can be consumed by the package installation. (See Installing a Package for information on how PackageInstall CRs consume secrets)

These resources are tracked by using the packaging.carvel.dev/package-... annotations and similar annotations are added to the resources themselves to assert ownership of the resources, so that they can be safely deleted while deleting the package installation. (See Security Model for information on how PackageInstall CRs use service accounts)

Package Repositories

The package repository group of commands can be used to view, create and delete packages repositories.

Adding package repositories

The package repository add command can be used to add a package repository to a namespace.

$ kctrl package repository add -r test-repo --url index.docker.io/k8slt/kc-e2e-test-repo:latest

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • --dangerous-allow-use-of-shared-namespace boolean, Allow addition of package repositories in shared namespaces (default, kube-public)
  • -r, --repository, string, Set package repository name (required)
  • --url, string, OCI registry url for package repository bundle (required)
  • --wait, boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval, duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout, duration, Maximum amount of time to wait in wait phase (default 5m0s)

Updating existing package repositories

The package repository update command can be used to update an existing repository.

$ kctrl package repository update -r test-repo --url index.docker.io/k8slt/kc-e2e-test-repo-2:latest

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • -r, --repository, string, Set package repository name (required)
  • --url, string, OCI registry url for package repository bundle (required)
  • --wait, boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval, duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout, duration, Maximum amount of time to wait in wait phase (default 5m0s)

Listing package repositories

The package repository list command can be used to list existing repositories.

$ kctrl package repository list

Supported flags:

  • -A, --all-namespaces string, List available packages in all namespaces
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)

Getting details for package repositories

The package repository get command can be used to get details of an existing package repository.

$ kctrl package repository get -r test-repo

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • -r, --repository string, Set package repository name (required)

Deleting package repositories

The package repository delete command can be used to delete a package repository.

$ kctrl package repository delete -r test-repo

Supported flags:

  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • -r, --repository string, Set package repository name (required)
  • --wait, boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval, duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout, duration, Maximum amount of time to wait in wait phase (default 5m0s)

App

The app commands let users observe and interact with Apps conveniently.

Listing apps

The kctrl app list command can be used to list apps.

$ kctrl app list

Supported flags:

  • -A, --all-namespaces boolean, List apps in all namespaces
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)

Geting details for an app

The kctrl app get command can be used to get details for an app.

$ kctrl app get -a simple-app

Supported flags:

  • -a, --app string, Set app name (required)
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)

Observe status of an app

The kctrl app status command allows users to observe the status of the app with information from the last reconciliation. The command tails and streams app status updates till the app reconciles or fails if the command is run while the app is reconciling.

$ kctrl app status -a simple-app

Supported flags:

  • -a, --app string, Set app name (required)
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • --ignore-not-exists boolean, Keep following app if it does not exist

Pause reconciliation of an app

The kctrl app pause command allows pausing of periodic recopnciliation of an app.

$ kctrl app pause -a simple-app

Supported flags:

  • -a, --app string, Set app name (required)
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)

Trigger reconciliation of an app

The kctrl app kick command can be used to trigger reconciliation of a command and tail the app status till it reconciles if desired. It can also be used to restart periodic reconciliation for a paused app.

$ kctrl app kick -a simple-app

Supported flags:

  • -a, --app string, Set app name (required)
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • --wait boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout duration, Maximum amount of time to wait in wait phase (default 5m0s)

Delete an app

The kctrl app delete command can be used to delete an app.

$ kctrl app delete -a simple-app

Supported flags:

  • -a, --app string, Set app name (required)
  • -n, --namespace string, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig)
  • --noop boolean, Ignore resources created by the app and delete the custom resource itself
  • --wait boolean, Wait for reconciliation to complete (default true)
  • --wait-check-interval duration, Amount of time to sleep between checks while waiting (default 1s)
  • --wait-timeout duration, Maximum amount of time to wait in wait phase (default 5m0s)

Global Flags

  • --color boolean, Set color output (default true)
  • --column string, Filter to show only given columns
  • --debug boolean, Include debug output
  • -h, --help boolean, help for kctrl
  • --json boolean, Output as JSON
  • --kube-api-burst, int, Set Kubernetes API client burst limit (default 1000)
  • --kube-api-qps float32, Set Kubernetes API client QPS limit (default 1000)
  • --kubeconfig string, Path to the kubeconfig file ($KCTRL_KUBECONFIG),
  • --kubeconfig-contextstring, Kubeconfig context override ($KCTRL_KUBECONFIG_CONTEXT)
  • --kubeconfig-yaml string, Kubeconfig contents as YAML ($KCTRL_KUBECONFIG_YAML)
  • --tty boolean, Force TTY-like output (default true)
  • -v, --version boolean, version for kctrl
  • -y, --yes, boolean, Assumes yes for any prompt

Environment variables

Environment Variables:

  • FORCE_COLOR: set to 1 to force colors to the printed. Useful to preserve colors when piping output such as in kctrl app list --tty --all-namespaces |& less -R
(Help improve our docs: edit this page on GitHub)