kn-plugin-admin

README

# kn-admin

**[This component is ALPHA](https://github.com/knative/community/tree/main/mechanics/MATURITY-LEVELS.md)**

The `kn admin` is a plugin of Knative client and it is designed to help administrators and operators better manage a Knative platform installation with kn CLI.
This plugin’s main objective is to make administration and operation workflows easier, for instance by making it easy to accomplish
tasks such as feature flags enablement or disablement with one command, instead of many manual steps like modifying ConfigMaps or yaml files.

## Getting Started

### Installation
You can download latest binaries from the https://github.com/knative-sandbox/kn-plugin-admin/releases[Releases] page.

Here are two ways to run `kn admin`:

1. You can run it standalone, just put it on your system path, and make sure it is executable.
2. You can install it as a plugin of `kn` client to run:

- Following the https://github.com/knative/client/blob/master/docs/README.md[document] to install `kn client` if you don't have it.
- Copy `kn admin` binary to `~/.config/kn/plugins/` folder and make sure its filename is `kn-admin`.
- Run `kn plugin list` to assure the `kn-admin` plugin is installed successfully.

After the plugin is installed, you can use `kn admin` to run its related subcommands. 

### Usage

----
A plugin of kn client to manage Knative for administrators.

For example:
kn admin domain set - to set Knative route domain
kn admin private-registry enable - to enable deployment from the private registry
kn admin autoscaling update - to manage autoscaling config

Usage:
  kn admin [command]

Available Commands:
  autoscaling Manage autoscaling config
  domain      Manage route domain
  help        Help about any command
  registry    Manage registry
  version     Prints the plugin version

Flags:
      --config string   config file (default is $HOME/.config/kn/plugins/admin.yaml)
  -h, --help            help for kn admin
  -t, --toggle          Help message for toggle

Use "kn admin [command] --help" for more information about a command.
----

#### `kn admin cdc`
----
Manage custom domain claim

Usage:
  kn admin cdc [command]

Available Commands:
  create      create cluster domain claim
  delete      delete cluster domain claim
  list        List cluster domain claims

Flags:
  -h, --help   help for cdc

Global Flags:
      --config string   config file (default is $HOME/.config/kn/plugins/admin.yaml)

Use "kn admin cdc [command] --help" for more information about a command.
----

#### `kn admin domain`

----
Set default route domain or route domain for Service with selectors. For example:

kn admin domain set - to set Knative route domain

Usage:
  kn admin domain [flags]
  kn admin domain [command]

Available Commands:
  set         set route domain
  unset       unset route domain

Flags:
  -h, --help   help for domain

Global Flags:
      --config string   config file (default is $HOME/.config/kn/plugins/admin.yaml)

Use "admin domain [command] --help" for more information about a command.

----

#### `kn admin registry`

----
Manage registry used by Knative service deployment

Usage:
  kn admin registry [command]

Available Commands:
  add         Add registry with credentials
  help        Help about any command
  list        List registry settings
  remove      Remove registry settings

Flags:
  -h, --help   help for registry

Global Flags:
      --config string   config file (default is $HOME/.config/kn/plugins/admin.yaml)

Use "kn admin registry [command] --help" for more information about a command.
----

#### `kn admin autoscaling`

----
Manage autoscaling provided by Knative Pod Autoscaler (KPA). For example:

kn admin autoscaling update - to manage autoscaling config

Usage:
  kn admin autoscaling [command]

Available Commands:
  list        List autoscaling config
  update      update autoscaling config

Flags:
  -h, --help   help for autoscaling

Global Flags:
      --config string   config file (default is $HOME/.config/kn/plugins/admin.yaml)

Use "kn admin autoscaling [command] --help" for more information about a command.

----

#### `kn admin profiling`

----
Enable Knative Serving components profiling and download profiling data

Usage:
  kn admin profiling [flags]

Aliases:
  profiling, prof

Examples:

  # To enable Knative Serving profiling
  kn admin profiling --enable

  # To download heap profiling data of autoscaler
  kn admin profiling --target autoscaler --heap

  # To download 2 minutes execution trace data of networking-istio
  kn admin profiling --target networking-istio --trace 2m

  # To download go routing block and memory allocations data of activator and save them to /tmp
  kn admin profiling --target activator --block --mem-allocs --save-to /tmp

  # To download all available profiling data for specified pod activator-5979f56548
  kn admin profiling --target activator-5979f56548 --all


Flags:
      --all              Download all available profiling data
      --block            Download go routine blocking data
      --cpu string       Download cpu profiling data, you can specify a profiling data duration with 's' for second(s), 'm' for minute(s) and 'h' for hour(s), e.g: '1m' for one minute (default "5s")
      --disable          Disable Knative Serving profiling
      --enable           Enable Knative Serving profiling
      --goroutine        Download stack traces of all current goroutines data
      --heap             Download heap profiling data
  -h, --help             help for profiling
      --mem-allocs       Download memory allocations data
      --mutex            Download holders of contended mutexes data
  -s, --save-to string   The path to save the downloaded profiling data, if not speicifed, the data will be saved in current working folder
  -t, --target string    The profiling target. It can be a Knative Serving component name or a specific pod name, e.g: 'activator' or 'activator-586d468c99-w59cm'
      --thread-create    Download stack traces that led to the creation of new OS threads data
      --trace string     Download execution trace data, you can specify a trace data duration with 's' for second(s), 'm' for minute(s) and 'h' for hour(s), e.g: '1m' for one minute (default "5s")

Global Flags:
      --config string   config file (default is $HOME/.config/kn/plugins/admin.yaml)

----
### Examples

#### As a Knative administrator, I want to update Knative route domain with my custom domain.


.Update the default route domain if --selector no specified
====
----
$ kn admin domain set --custom-domain mydomain.com
Set Knative route domain mydomain.com
----
====

.Update a custom domain with --selector and Service with a label app=v1 will use test.com
====
----
$ kn admin domain set --custom-domain test.com --selector app=v1
Set Knative route domain test.com with selector [app=v1]
----
====

.Unset a route domain
====
----
$ kn-admin domain unset --custom-domain mydomain.com
Unset Knative route domain mydomain.com
----
====

#### As a Knative administrator, I want to enable deploying from private registry.

.Enable a private registry with given credentials for Service creation.
=====
-----
$ kn admin registry add \
  --secret=[SECRET_NAME] \
  --server=[REGISTRY_SERVER_URL] \
  --email=[REGISTRY_EMAIL] \
  --username=[REGISTRY_USER] \
  --password=[REGISTRY_PASSWORD] \
  --namespace=[NAMESPACE] \
  --serviceaccount=[SERVICE_ACCOUNT]
-----
=====

.List all private registries with given namespace and service account.
=====
-----
$ kn admin registry list \
  --namespace=[NAMESPACE] \
  --serviceaccount=[SERVICE_ACCOUNT]
-----
=====

.Remove a private registry by server and username.
=====
-----
$ kn admin registry remove \
  --username=[REGISTRY_USER] \
  --server=[REGISTRY_SERVER_URL] \
  --namespace=[NAMESPACE] \
  --serviceaccount=[SERVICE_ACCOUNT]
-----
=====

#### As a Knative administrator, I want to update global configs for autoscaling.

.Enable scale-to-zero and update stable-window for autoscaling.
=====
-----
$ kn admin autoscaling update --scale-to-zero --stable-window 2m
Updated Knative autoscaling config
-----
=====

#### As a Knative administrator, I want to list autoscaling configs which apply to overall Knative platform.

.List autoscaling configs.
=====
-----
$ kn admin autoscaling list
NAME                                   VALUE
activator-capacity                     100.0
container-concurrency-target-default   100.0
enable-scale-to-zero                   false
max-scale-down-rate                    3.0
max-scale-up-rate                      1000.0
panic-threshold-percentage             100.0
panic-window-percentage                10.0
pod-autoscaler-class                   kpa.autoscaling.knative.dev
requests-per-second-target-default     200.0
scale-to-zero-grace-period             30s
scale-to-zero-pod-retention-period     0s
stable-window                          1m
target-burst-capacity                  200.0
-----
=====

#### As a Knative administrator, I want to enable Knative Serving profiling and download profile data.

.Enable Knative Serving profiling.
=====
-----
$ kn admin profiling --enable
Knative Serving profiling is enabled
-----
=====

.Download 5 seconds cpu profiling data of activator component and save data to /tmp folder
=====
-----
$ kn admin profiling --target activator --cpu 5s --save-to /tmp
Starting to download profiling data for pod activator-586d468c99-w59cm...
Saving 5 second(s) cpu profiling data to /tmp/activator-586d468c99-w59cm_cpu_5s_20200725165758
Forwarding from 127.0.0.1:18008 -> 8008
Forwarding from [::1]:18008 -> 8008
Handling connection for 18008
-----
=====
After you get the profiling data file, you need to use https://blog.golang.org/pprof[pprof] to open it.