Merge pull request #3982 from Shopify/plugin-docs
Add kubectl plugin docs
This commit is contained in:
commit
29f7d9a77a
2 changed files with 357 additions and 98 deletions
357
docs/kubectl-plugin.md
Normal file
357
docs/kubectl-plugin.md
Normal file
|
@ -0,0 +1,357 @@
|
||||||
|
<!--
|
||||||
|
-----------------NOTICE------------------------
|
||||||
|
This file is referenced in code as
|
||||||
|
https://github.com/kubernetes/ingress-nginx/blob/master/docs/kubectl-plugin.md
|
||||||
|
Do not move it without providing redirects.
|
||||||
|
-----------------------------------------------
|
||||||
|
-->
|
||||||
|
|
||||||
|
# The ingress-nginx kubectl plugin
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Install [krew](https://github.com/GoogleContainerTools/krew), then run
|
||||||
|
```console
|
||||||
|
$ kubectl krew install ingress-nginx
|
||||||
|
```
|
||||||
|
to install the plugin. Then run
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx --help
|
||||||
|
```
|
||||||
|
to make sure the plugin is properly installed and to get a list of commands:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx --help
|
||||||
|
A kubectl plugin for inspecting your ingress-nginx deployments
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
ingress-nginx [command]
|
||||||
|
|
||||||
|
Available Commands:
|
||||||
|
backends Inspect the dynamic backend information of an ingress-nginx instance
|
||||||
|
certs Output the certificate data stored in an ingress-nginx pod
|
||||||
|
conf Inspect the generated nginx.conf
|
||||||
|
exec Execute a command inside an ingress-nginx pod
|
||||||
|
general Inspect the other dynamic ingress-nginx information
|
||||||
|
help Help about any command
|
||||||
|
info Show information about the ingress-nginx service
|
||||||
|
ingresses Provide a short summary of all of the ingress definitions
|
||||||
|
lint Inspect kubernetes resources for possible issues
|
||||||
|
logs Get the kubernetes logs for an ingress-nginx pod
|
||||||
|
ssh ssh into a running ingress-nginx pod
|
||||||
|
|
||||||
|
Flags:
|
||||||
|
--as string Username to impersonate for the operation
|
||||||
|
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
|
||||||
|
--cache-dir string Default HTTP cache directory (default "/Users/alexkursell/.kube/http-cache")
|
||||||
|
--certificate-authority string Path to a cert file for the certificate authority
|
||||||
|
--client-certificate string Path to a client certificate file for TLS
|
||||||
|
--client-key string Path to a client key file for TLS
|
||||||
|
--cluster string The name of the kubeconfig cluster to use
|
||||||
|
--context string The name of the kubeconfig context to use
|
||||||
|
-h, --help help for ingress-nginx
|
||||||
|
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
|
||||||
|
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
|
||||||
|
-n, --namespace string If present, the namespace scope for this CLI request
|
||||||
|
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
|
||||||
|
-s, --server string The address and port of the Kubernetes API server
|
||||||
|
--token string Bearer token for authentication to the API server
|
||||||
|
--user string The name of the kubeconfig user to use
|
||||||
|
|
||||||
|
Use "ingress-nginx [command] --help" for more information about a command.
|
||||||
|
```
|
||||||
|
|
||||||
|
If a new `ingress-nginx` version has just been released, the plugin may not yet have been updated inside the repository. In that case, you can install the latest version of the plugin by running:
|
||||||
|
|
||||||
|
```console
|
||||||
|
(
|
||||||
|
set -x; cd "$(mktemp -d)" &&
|
||||||
|
curl -fsSLO "https://github.com/kubernetes/ingress-nginx/releases/download/nginx-0.24.0/{ingress-nginx.yaml,kubectl-ingress_nginx-$(uname | tr '[:upper:]' '[:lower:]')-amd64.tar.gz}" &&
|
||||||
|
kubectl krew install \
|
||||||
|
--manifest=ingress-nginx.yaml --archive=kubectl-ingress_nginx-$(uname | tr '[:upper:]' '[:lower:]')-amd64.tar.gz
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Replacing `0.24.0` with the recently released version.
|
||||||
|
|
||||||
|
## Common Flags
|
||||||
|
|
||||||
|
- Every subcommand supports the basic `kubectl` configuration flags like `--namespace`, `--context`, `--client-key` and so on.
|
||||||
|
- Subcommands that act on a particular `ingress-nginx` pod (`backends`, `certs`, `conf`, `exec`, `general`, `logs`, `ssh`), support the `--deployment <deployment>` and `--pod <pod>` flags to select either a pod from a deployment with the given name, or a pod with the given name. The `--deployment` flag defaults to `nginx-ingress-controller`.
|
||||||
|
- Subcommands that inspect resources (`ingresses`, `lint`) support the `--all-namespaces` flag, which causes them to inspect resources in every namespace.
|
||||||
|
|
||||||
|
## Subcommands
|
||||||
|
|
||||||
|
Note that `backends`, `general`, `certs`, and `conf` require `ingress-nginx` version `0.23.0` or higher.
|
||||||
|
|
||||||
|
### backends
|
||||||
|
|
||||||
|
Run `kubectl ingress-nginx backends` to get a JSON array of the backends that an ingress-nginx controller currently knows about:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx backends -n ingress-nginx
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "default-apple-service-5678",
|
||||||
|
"service": {
|
||||||
|
"metadata": {
|
||||||
|
"creationTimestamp": null
|
||||||
|
},
|
||||||
|
"spec": {
|
||||||
|
"ports": [
|
||||||
|
{
|
||||||
|
"protocol": "TCP",
|
||||||
|
"port": 5678,
|
||||||
|
"targetPort": 5678
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"selector": {
|
||||||
|
"app": "apple"
|
||||||
|
},
|
||||||
|
"clusterIP": "10.97.230.121",
|
||||||
|
"type": "ClusterIP",
|
||||||
|
"sessionAffinity": "None"
|
||||||
|
},
|
||||||
|
"status": {
|
||||||
|
"loadBalancer": {}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"port": 0,
|
||||||
|
"secureCACert": {
|
||||||
|
"secret": "",
|
||||||
|
"caFilename": "",
|
||||||
|
"pemSha": ""
|
||||||
|
},
|
||||||
|
"sslPassthrough": false,
|
||||||
|
"endpoints": [
|
||||||
|
{
|
||||||
|
"address": "10.1.3.86",
|
||||||
|
"port": "5678"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"sessionAffinityConfig": {
|
||||||
|
"name": "",
|
||||||
|
"cookieSessionAffinity": {
|
||||||
|
"name": ""
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"upstreamHashByConfig": {
|
||||||
|
"upstream-hash-by-subset-size": 3
|
||||||
|
},
|
||||||
|
"noServer": false,
|
||||||
|
"trafficShapingPolicy": {
|
||||||
|
"weight": 0,
|
||||||
|
"header": "",
|
||||||
|
"headerValue": "",
|
||||||
|
"cookie": ""
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "default-echo-service-8080",
|
||||||
|
...
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "upstream-default-backend",
|
||||||
|
...
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Add the `--list` option to show only the backend names. Add the `--backend <backend>` option to show only the backend with the given name.
|
||||||
|
|
||||||
|
### certs
|
||||||
|
|
||||||
|
Use `kubectl ingress-nginx certs --host <hostname>` to dump the SSL cert/key information for a given host. Requires that `--enable-dynamic-certificates` is `true` (this is the default as of version `0.24.0`). WARNING: This command will dump sensitive private key information. Don't blindly share the output, and certainly don't log it anywhere.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx certs --host testaddr.local -n ingress-nginx
|
||||||
|
-----BEGIN CERTIFICATE-----
|
||||||
|
...
|
||||||
|
-----END CERTIFICATE-----
|
||||||
|
-----BEGIN CERTIFICATE-----
|
||||||
|
...
|
||||||
|
-----END CERTIFICATE-----
|
||||||
|
|
||||||
|
-----BEGIN RSA PRIVATE KEY-----
|
||||||
|
<REDACTED! DO NOT SHARE THIS!>
|
||||||
|
-----END RSA PRIVATE KEY-----
|
||||||
|
```
|
||||||
|
|
||||||
|
### conf
|
||||||
|
|
||||||
|
Use `kubectl ingress-nginx conf` to dump the generated `nginx.conf` file. Add the `--host <hostname>` option to view only the server block for that host:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx conf -n ingress-nginx --host testaddr.local
|
||||||
|
|
||||||
|
server {
|
||||||
|
server_name testaddr.local ;
|
||||||
|
|
||||||
|
listen 80;
|
||||||
|
|
||||||
|
set $proxy_upstream_name "-";
|
||||||
|
set $pass_access_scheme $scheme;
|
||||||
|
set $pass_server_port $server_port;
|
||||||
|
set $best_http_host $http_host;
|
||||||
|
set $pass_port $pass_server_port;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
|
||||||
|
set $namespace "";
|
||||||
|
set $ingress_name "";
|
||||||
|
set $service_name "";
|
||||||
|
set $service_port "0";
|
||||||
|
set $location_path "/";
|
||||||
|
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### exec
|
||||||
|
|
||||||
|
`kubectl ingress-nginx exec` is exactly the same as `kubectl exec`, with the same command flags. It will automatically choose an `ingress-nginx` pod to run the command in.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx exec -i -n ingress-nginx -- ls /etc/nginx
|
||||||
|
fastcgi.conf
|
||||||
|
fastcgi.conf.default
|
||||||
|
fastcgi_params
|
||||||
|
fastcgi_params.default
|
||||||
|
geoip
|
||||||
|
koi-utf
|
||||||
|
koi-win
|
||||||
|
lua
|
||||||
|
mime.types
|
||||||
|
mime.types.default
|
||||||
|
modsecurity
|
||||||
|
modules
|
||||||
|
nginx.conf
|
||||||
|
nginx.conf.default
|
||||||
|
opentracing.json
|
||||||
|
owasp-modsecurity-crs
|
||||||
|
scgi_params
|
||||||
|
scgi_params.default
|
||||||
|
template
|
||||||
|
uwsgi_params
|
||||||
|
uwsgi_params.default
|
||||||
|
win-utf
|
||||||
|
```
|
||||||
|
|
||||||
|
### general
|
||||||
|
|
||||||
|
`kubectl ingress-nginx general` dumps miscellaneous controller state as a JSON object. Currently it just shows the number of controller pods known to a particular controller pod.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx general
|
||||||
|
{
|
||||||
|
"controllerPodsCount": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### info
|
||||||
|
|
||||||
|
Shows the internal and external IP/CNAMES for an `ingress-nginx` service.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx info -n ingress-nginx
|
||||||
|
Service cluster IP address: 10.187.253.31
|
||||||
|
LoadBalancer IP|CNAME: 35.123.123.123
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the `--service <service>` flag if your `ingress-nginx` `LoadBalancer` service is not named `ingress-nginx`.
|
||||||
|
|
||||||
|
### ingresses
|
||||||
|
|
||||||
|
`kubectl ingress-nginx ingresses`, alternately `kubectl ingress-nginx ing`, shows a more detailed view of the ingress definitions in a namespace. Compare:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl get ingresses --all-namespaces
|
||||||
|
NAMESPACE NAME HOSTS ADDRESS PORTS AGE
|
||||||
|
default example-ingress1 testaddr.local,testaddr2.local localhost 80 5d
|
||||||
|
default test-ingress-2 * localhost 80 5d
|
||||||
|
```
|
||||||
|
|
||||||
|
vs
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx ingresses --all-namespaces
|
||||||
|
NAMESPACE INGRESS NAME HOST+PATH ADDRESSES TLS SERVICE SERVICE PORT ENDPOINTS
|
||||||
|
default example-ingress1 testaddr.local/etameta localhost NO pear-service 5678 5
|
||||||
|
default example-ingress1 testaddr2.local/otherpath localhost NO apple-service 5678 1
|
||||||
|
default example-ingress1 testaddr2.local/otherotherpath localhost NO pear-service 5678 5
|
||||||
|
default test-ingress-2 * localhost NO echo-service 8080 2
|
||||||
|
```
|
||||||
|
|
||||||
|
### lint
|
||||||
|
|
||||||
|
`kubectl ingress-nginx lint` can check a namespace or entire cluster for potential configuration issues. This command is especially useful when upgrading between `ingress-nginx` versions.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx lint --all-namespaces --verbose
|
||||||
|
Checking ingresses...
|
||||||
|
✗ anamespace/this-nginx
|
||||||
|
- Contains the removed session-cookie-hash annotation.
|
||||||
|
Lint added for version 0.24.0
|
||||||
|
https://github.com/kubernetes/ingress-nginx/issues/3743
|
||||||
|
✗ othernamespace/ingress-definition-blah
|
||||||
|
- The rewrite-target annotation value does not reference a capture group
|
||||||
|
Lint added for version 0.22.0
|
||||||
|
https://github.com/kubernetes/ingress-nginx/issues/3174
|
||||||
|
|
||||||
|
Checking deployments...
|
||||||
|
✗ namespace2/nginx-ingress-controller
|
||||||
|
- Uses removed config flag --sort-backends
|
||||||
|
Lint added for version 0.22.0
|
||||||
|
https://github.com/kubernetes/ingress-nginx/issues/3655
|
||||||
|
- Uses removed config flag --enable-dynamic-certificates
|
||||||
|
Lint added for version 0.24.0
|
||||||
|
https://github.com/kubernetes/ingress-nginx/issues/3808
|
||||||
|
```
|
||||||
|
|
||||||
|
to show the lints added **only** for a particular `ingress-nginx` release, use the `--from-version` and `--to-version` flags:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx lint --all-namespaces --verbose --from-version 0.24.0 --to-version 0.24.0
|
||||||
|
Checking ingresses...
|
||||||
|
✗ anamespace/this-nginx
|
||||||
|
- Contains the removed session-cookie-hash annotation.
|
||||||
|
Lint added for version 0.24.0
|
||||||
|
https://github.com/kubernetes/ingress-nginx/issues/3743
|
||||||
|
|
||||||
|
Checking deployments...
|
||||||
|
✗ namespace2/nginx-ingress-controller
|
||||||
|
- Uses removed config flag --enable-dynamic-certificates
|
||||||
|
Lint added for version 0.24.0
|
||||||
|
https://github.com/kubernetes/ingress-nginx/issues/3808
|
||||||
|
```
|
||||||
|
|
||||||
|
### logs
|
||||||
|
|
||||||
|
`kubectl ingress-nginx logs` is almost the same as `kubectl logs`, with fewer flags. It will automatically choose an `ingress-nginx` pod to read logs from.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx logs -n ingress-nginx
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
NGINX Ingress controller
|
||||||
|
Release: dev
|
||||||
|
Build: git-48dc3a867
|
||||||
|
Repository: git@github.com:kubernetes/ingress-nginx.git
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
W0405 16:53:46.061589 7 flags.go:214] SSL certificate chain completion is disabled (--enable-ssl-chain-completion=false)
|
||||||
|
nginx version: nginx/1.15.9
|
||||||
|
W0405 16:53:46.070093 7 client_config.go:549] Neither --kubeconfig nor --master was specified. Using the inClusterConfig. This might not work.
|
||||||
|
I0405 16:53:46.070499 7 main.go:205] Creating API client for https://10.96.0.1:443
|
||||||
|
I0405 16:53:46.077784 7 main.go:249] Running in Kubernetes cluster version v1.10 (v1.10.11) - git (clean) commit 637c7e288581ee40ab4ca210618a89a555b6e7e9 - platform linux/amd64
|
||||||
|
I0405 16:53:46.183359 7 nginx.go:265] Starting NGINX Ingress controller
|
||||||
|
I0405 16:53:46.193913 7 event.go:209] Event(v1.ObjectReference{Kind:"ConfigMap", Namespace:"ingress-nginx", Name:"udp-services", UID:"82258915-563e-11e9-9c52-025000000001", APIVersion:"v1", ResourceVersion:"494", FieldPath:""}): type: 'Normal' reason: 'CREATE' ConfigMap ingress-nginx/udp-services
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### ssh
|
||||||
|
|
||||||
|
`kubectl ingress-nginx ssh` is exactly the same as `kubectl ingress-nginx exec -it -- /bin/bash`. Use it when you want to quickly be dropped into a shell inside a running `ingress-nginx` container.
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ kubectl ingress-nginx ssh -n ingress-nginx
|
||||||
|
www-data@nginx-ingress-controller-7cbf77c976-wx5pn:/etc/nginx$
|
||||||
|
```
|
|
@ -93,104 +93,6 @@ kube-system kube-dns ClusterIP 10.96.0.10 <none>
|
||||||
kube-system kubernetes-dashboard NodePort 10.103.128.17 <none> 80:30000/TCP 30m
|
kube-system kubernetes-dashboard NodePort 10.103.128.17 <none> 80:30000/TCP 30m
|
||||||
```
|
```
|
||||||
|
|
||||||
Use the `ingress-nginx` kubectl plugin
|
|
||||||
|
|
||||||
Install [krew](https://github.com/GoogleContainerTools/krew), then run
|
|
||||||
```console
|
|
||||||
$ (
|
|
||||||
set -x; cd "$(mktemp -d)" &&
|
|
||||||
curl -fsSLO "https://github.com/kubernetes/ingress-nginx/releases/download/nginx-0.24.0/{ingress-nginx.yaml,kubectl-ingress_nginx-$(uname | tr '[:upper:]' '[:lower:]')-amd64.tar.gz}" &&
|
|
||||||
kubectl krew install \
|
|
||||||
--manifest=ingress-nginx.yaml --archive=kubectl-ingress_nginx-$(uname | tr '[:upper:]' '[:lower:]')-amd64.tar.gz
|
|
||||||
)
|
|
||||||
```
|
|
||||||
to install the plugin. Then run
|
|
||||||
```console
|
|
||||||
$ kubectl ingress-nginx --help
|
|
||||||
```
|
|
||||||
to make sure the plugin is properly installed and to get a list of commands. The plugin includes all of the commands present in the `/dbg` tool, plus a more detailed version of `kubectl get ingresses` available by runnning `kubectl ingress-nginx ingresses`.
|
|
||||||
|
|
||||||
Use the `/dbg` Tool to Check Dynamic Configuration
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ kubectl exec -n <namespace-of-ingress-controller> nginx-ingress-controller-67956bf89d-fv58j /dbg
|
|
||||||
dbg is a tool for quickly inspecting the state of the nginx instance
|
|
||||||
|
|
||||||
Usage:
|
|
||||||
dbg [command]
|
|
||||||
|
|
||||||
Available Commands:
|
|
||||||
backends Inspect the dynamically-loaded backends information
|
|
||||||
conf Dump the contents of /etc/nginx/nginx.conf
|
|
||||||
general Output the general dynamic lua state
|
|
||||||
help Help about any command
|
|
||||||
|
|
||||||
Flags:
|
|
||||||
-h, --help help for dbg
|
|
||||||
|
|
||||||
Use "dbg [command] --help" for more information about a command.
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ kubectl exec -n <namespace-of-ingress-controller> nginx-ingress-controller-67956bf89d-fv58j /dbg backends
|
|
||||||
Inspect the dynamically-loaded backends information.
|
|
||||||
|
|
||||||
Usage:
|
|
||||||
dbg backends [command]
|
|
||||||
|
|
||||||
Available Commands:
|
|
||||||
all Output the all dynamic backend information as a JSON array
|
|
||||||
get Output the backend information only for the backend that has this name
|
|
||||||
list Output a newline-separated list of the backend names
|
|
||||||
|
|
||||||
Flags:
|
|
||||||
-h, --help help for backends
|
|
||||||
|
|
||||||
Use "dbg backends [command] --help" for more information about a command.
|
|
||||||
```
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ kubectl exec -n <namespace-of-ingress-controller> nginx-ingress-controller-67956bf89d-fv58j /dbg backends list
|
|
||||||
coffee-svc-80
|
|
||||||
tea-svc-80
|
|
||||||
upstream-default-backend
|
|
||||||
```
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ kubectl exec -n <namespace-of-ingress-controller> nginx-ingress-controller-67956bf89d-fv58j /dbg backends get coffee-svc-80
|
|
||||||
{
|
|
||||||
"endpoints": [
|
|
||||||
{
|
|
||||||
"address": "10.1.1.112",
|
|
||||||
"port": "8080"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"address": "10.1.1.119",
|
|
||||||
"port": "8080"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"address": "10.1.1.121",
|
|
||||||
"port": "8080"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"load-balance": "ewma",
|
|
||||||
"name": "coffee-svc-80",
|
|
||||||
"noServer": false,
|
|
||||||
"port": 0,
|
|
||||||
"secureCACert": {
|
|
||||||
"caFilename": "",
|
|
||||||
"pemSha": "",
|
|
||||||
"secret": ""
|
|
||||||
},
|
|
||||||
"service": {
|
|
||||||
"metadata": {
|
|
||||||
"creationTimestamp": null
|
|
||||||
},
|
|
||||||
"spec": {
|
|
||||||
....
|
|
||||||
```
|
|
||||||
|
|
||||||
## Debug Logging
|
## Debug Logging
|
||||||
|
|
||||||
Using the flag `--v=XX` it is possible to increase the level of logging. This is performed by editing
|
Using the flag `--v=XX` it is possible to increase the level of logging. This is performed by editing
|
||||||
|
|
Loading…
Reference in a new issue