From 600e785168f09e77922c8cfaf822d4ce05a237de Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Fri, 10 Jul 2015 16:21:05 -0700 Subject: [PATCH] add user guide docs for kubectl exec, proxy, and port-forward --- ...connecting-to-applications-port-forward.md | 41 ++++++++++++++++ .../connecting-to-applications-proxy.md | 23 +++++++++ docs/user-guide/getting-into-containers.md | 49 +++++++++++++++++++ 3 files changed, 113 insertions(+) create mode 100644 docs/user-guide/connecting-to-applications-port-forward.md create mode 100644 docs/user-guide/connecting-to-applications-proxy.md create mode 100644 docs/user-guide/getting-into-containers.md diff --git a/docs/user-guide/connecting-to-applications-port-forward.md b/docs/user-guide/connecting-to-applications-port-forward.md new file mode 100644 index 00000000000..0fa65dee2b2 --- /dev/null +++ b/docs/user-guide/connecting-to-applications-port-forward.md @@ -0,0 +1,41 @@ +#Connecting to applications: kubectl port-forward +kubectl port-forward forwards connections to a local port to a port on a pod. Its man page is available [here](../../docs/kubectl_port-forward.md). Compared to [kubectl proxy](../../docs/accessing-the-cluster.md#using-kubectl-proxy), `kubectl port-forward` is more generic as it can forward TCP traffic while `kubectl proxy` can only forward HTTP traffic. This guide demonstrates how to use `kubectl port-forward` to connect to a Redis database, which may be useful for database debugging. + + +## Creating a Redis master +``` +$kubectl create examples/redis/redis-master.yaml +pods/redis-master +``` +wait until the Redis master pod is Running and Ready, +``` +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +redis-master 2/2 Running 0 41s +``` + + +## Connecting to the Redis master[a] +The Redis master is listening on port 6397, to verify this, +``` +$ kubectl get pods redis-master -t='{{(index (index .spec.containers 0).ports 0).containerPort}}{{"\n"}}' +6379 +``` + + +then we forward the port 6379 on the local workstation to the port 6379 of pod redis-master, +``` +$ kubectl port-forward -p redis-master 6379:6379 +I0710 14:43:38.274550 3655 portforward.go:225] Forwarding from 127.0.0.1:6379 -> 6379 +I0710 14:43:38.274797 3655 portforward.go:225] Forwarding from [::1]:6379 -> 6379 +``` +To verify the connection is successful, we run a redis-cli on the local workstation, +``` +$ redis-cli +127.0.0.1:6379> ping +PONG +``` +Now one can debug the database from the local workstation. + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/connecting-to-applications-2.md?pixel)]() diff --git a/docs/user-guide/connecting-to-applications-proxy.md b/docs/user-guide/connecting-to-applications-proxy.md new file mode 100644 index 00000000000..d473ed18e83 --- /dev/null +++ b/docs/user-guide/connecting-to-applications-proxy.md @@ -0,0 +1,23 @@ +#Connecting to applications: kubectl proxy and apiserver proxy +You have seen the [basics](../../docs/accessing-the-cluster.md) about `kubectl proxy` and `apiserver proxy`. This guide shows how to use them together to access a service([kube-ui](../../docs/ui.md)) running on the Kubernetes cluster from your workstation. + + +##Getting the apiserver proxy URL of kube-ui +kube-ui is deployed as a cluster add-on. To find its apiserver proxy URL, +``` +$ kubectl cluster-info | grep "KubeUI" +KubeUI is running at https://173.255.119.104/api/v1/proxy/namespaces/kube-system/services/kube-ui +``` +if this command does not find the URL, try the steps [here](../../docs/ui.md#accessing-the-ui). + + +##Connecting to the kube-ui service from your local workstation +The above proxy URL is an access to the kube-ui service provided by the apiserver. To access it, you still need to authenticate to the apiserver. `kubectl proxy` can handle the authentication. +``` +$ kubectl proxy --port=8001 +Starting to serve on localhost:8001 +``` +Now you can access the kube-ui service on your local workstation at http://localhost:8001/api/v1/proxy/namespaces/kube-system/services/kube-ui + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/connecting-to-applications-1.md?pixel)]() diff --git a/docs/user-guide/getting-into-containers.md b/docs/user-guide/getting-into-containers.md new file mode 100644 index 00000000000..f215d003ddf --- /dev/null +++ b/docs/user-guide/getting-into-containers.md @@ -0,0 +1,49 @@ +#Getting into containers: kubectl exec +Developers can use `kubectl exec` to run commands in a container. This guide demonstrates two use cases. + +##Using kubectl exec to check the environment variables of a container +Kubernetes exposes [services](../../docs/services.md#environment-variables) through environment variables. It is convenient to check these environment variables using `kubectl exec`. + + +We first create a pod and a service, +``` +$ kubectl create -f examples/guestbook/redis-master-controller.yaml +$ kubectl create -f examples/guestbook/redis-master-service.yaml +``` +wait until the pod is Running and Ready, +``` +$ kubectl get pod +NAME READY REASON RESTARTS AGE +redis-master-ft9ex 1/1 Running 0 12s +``` +then we can check the environment variables of the pod, +``` +$ kubectl exec redis-master-ft9ex env +... +REDIS_MASTER_SERVICE_PORT=6379 +REDIS_MASTER_SERVICE_HOST=10.0.0.219 +... +``` +We can use these environment variables in applications to find the service. + + +## Using kubectl exec to check the mounted volumes +It is convenient to use `kubectl exec` to check if the volumes are mounted as expected. +We first create a Pod with a volume mounted at /data/redis, +``` +kubectl create -f examples/walkthrough/pod2.yaml +``` +wait until the pod is Running and Ready, +``` +$ kubectl get pods +NAME READY REASON RESTARTS AGE +storage 1/1 Running 0 1m +``` +we then use `kubectl exec` to verify that the volume is mounted at /data/redis, +``` +$ kubectl exec storage ls /data +redis +``` + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/getting-into-containers.md?pixel)]()