From 5391d054e4ca8ed8d8049effacf8c5ad4ed08c0e Mon Sep 17 00:00:00 2001 From: lucperkins Date: Wed, 20 Jun 2018 22:12:01 -0700 Subject: [PATCH 1/4] Re-organize doc --- .../concepts/services-networking/service.md | 107 ++++++++++++------ 1 file changed, 71 insertions(+), 36 deletions(-) diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index dfaa1a0a68..e0aa7740db 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -135,32 +135,15 @@ The traffic will be routed to endpoints defined by the user (`1.2.3.4:9376` in this example). An ExternalName service is a special case of service that does not have -selectors. It does not define any ports or Endpoints. Rather, it serves as a -way to return an alias to an external service residing outside the cluster. - -```yaml -kind: Service -apiVersion: v1 -metadata: - name: my-service - namespace: prod -spec: - type: ExternalName - externalName: my.database.example.com -``` - -When looking up the host `my-service.prod.svc.CLUSTER`, the cluster DNS service -will return a `CNAME` record with the value `my.database.example.com`. Accessing -such a service works in the same way as others, with the only difference that -the redirection happens at the DNS level and no proxying or forwarding occurs. -Should you later decide to move your database into your cluster, you can start -its pods, add appropriate selectors or endpoints and change the service `type`. +selectors and uses DNS names instead. For more information, see the +[ExternalName](#externalname) section later in this document. ## Virtual IPs and service proxies -Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is +Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is responsible for implementing a form of virtual IP for `Services` of type other -than `ExternalName`. +than [`ExternalName`](#externalname). + In Kubernetes v1.0, `Services` are a "layer 4" (TCP/UDP over IP) construct, the proxy was purely in userspace. In Kubernetes v1.1, the `Ingress` API was added (beta) to represent "layer 7"(HTTP) services, iptables proxy was added too, @@ -348,7 +331,8 @@ can do a DNS SRV query for `"_http._tcp.my-service.my-ns"` to discover the port number for `"http"`. The Kubernetes DNS server is the only way to access services of type -`ExternalName`. More information is available in the [DNS Pods and Services](/docs/concepts/services-networking/dns-pod-service/). +`ExternalName`. More information is available in the [DNS Pods and +Services](/docs/concepts/services-networking/dns-pod-service/). ## Headless services @@ -378,7 +362,7 @@ For headless services that do not define selectors, the endpoints controller doe not create `Endpoints` records. However, the DNS system looks for and configures either: - * CNAME records for `ExternalName`-type services. + * CNAME records for [`ExternalName`](#externalname)-type services. * A records for any `Endpoints` that share a name with the service, for all other types. @@ -396,19 +380,20 @@ The default is `ClusterIP`. * `ClusterIP`: Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster. This is the default `ServiceType`. - * `NodePort`: Exposes the service on each Node's IP at a static port (the `NodePort`). - A `ClusterIP` service, to which the `NodePort` service will route, is automatically - created. You'll be able to contact the `NodePort` service, from outside the cluster, + * [`NodePort`](#nodeport): Exposes the service on each Node's IP at a static port + (the `NodePort`). A `ClusterIP` service, to which the `NodePort` service will + route, is automatically created. You'll be able to contact the `NodePort` service, + from outside the cluster, by requesting `:`. - * `LoadBalancer`: Exposes the service externally using a cloud provider's load balancer. - `NodePort` and `ClusterIP` services, to which the external load balancer will route, - are automatically created. - * `ExternalName`: Maps the service to the contents of the `externalName` field - (e.g. `foo.bar.example.com`), by returning a `CNAME` record with its value. - No proxying of any kind is set up. This requires version 1.7 or higher of - `kube-dns`. + * [`LoadBalancer`](#loadbalancer): Exposes the service externally using a cloud + provider's load balancer. `NodePort` and `ClusterIP` services, to which the external + load balancer will route, are automatically created. + * [`ExternalName`](#externalname): Maps the service to the contents of the + `externalName` field (e.g. `foo.bar.example.com`), by returning a `CNAME` record + with its value. No proxying of any kind is set up. This requires version 1.7 or + higher of `kube-dns`. -### Type NodePort +### Type NodePort {#nodeport} If you set the `type` field to `NodePort`, the Kubernetes master will allocate a port from a range specified by `--service-node-port-range` flag (default: 30000-32767), and each @@ -429,7 +414,7 @@ even to just expose one or more nodes' IPs directly. Note that this Service will be visible as both `:spec.ports[*].nodePort` and `.spec.clusterIP:spec.ports[*].port`. (If the `--nodeport-addresses` flag in kube-proxy is set, would be filtered NodeIP(s).) -### Type LoadBalancer +### Type LoadBalancer {#loadbalancer} On cloud providers which support external load balancers, setting the `type` field to `LoadBalancer` will provision a load balancer for your `Service`. @@ -756,6 +741,56 @@ spec: **Note:** NLB only works with certain instance classes, see the [AWS documentation](http://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets) for supported instance types. +### Type ExternalName {#externalname} + +{{< note >}} +ExternalName Services are available only with `kube-dns` version 1.7 and later. +{{< /note >}} + +Services of type ExternalName map a service to a DNS name (specified using +the `spec.externalName` parameter) rather than to a typical selector like +`my-service` or `cassandra`. This Service definition, for example, would map +the `my-service` Service in the `prod` namespace to `my.database.example.com`: + +```yaml +kind: Service +apiVersion: v1 +metadata: + name: my-service + namespace: prod +spec: + type: ExternalName + externalName: my.database.example.com +``` + +When looking up the host `my-service.prod.svc.CLUSTER`, the cluster DNS service +will return a `CNAME` record with the value `my.database.example.com`. Accessing +`my-service` works in the same way as other Services but with the crucial +difference that redirection happens at the DNS level rather than via proxying or +forwarding. Should you later decide to move your database into your cluster, you +can start its pods, add appropriate selectors or endpoints and change the service `type`. + +#### Using ExternalName Services across namespaces + +In addition to enabling Kubernetes pods to + +```yaml +kind: Service +apiVersion: v1 +metadata: + name: my-service + namespace: namespace-a +spec: + type: ExternalName + externalName: my-service.namespace-b.svc.cluster.local + ports: + - port: 80 +``` + +{{< note >}} +This section is indebted to the [Kubernetes Tips - Part +1](https://akomljen.com/kubernetes-tips-part-1/) blog post from [Alen Komljen](https://akomljen.com/). +{{< /note >}} ### External IPs From 8910ac886fe395a40adb6a9b151fd4f05f2af0ad Mon Sep 17 00:00:00 2001 From: lucperkins Date: Mon, 9 Jul 2018 12:29:22 -0700 Subject: [PATCH 2/4] Remove section on multiple namespaces --- .../concepts/services-networking/service.md | 20 ++----------------- 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index e0aa7740db..b77c5fdd92 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -768,24 +768,8 @@ will return a `CNAME` record with the value `my.database.example.com`. Accessing `my-service` works in the same way as other Services but with the crucial difference that redirection happens at the DNS level rather than via proxying or forwarding. Should you later decide to move your database into your cluster, you -can start its pods, add appropriate selectors or endpoints and change the service `type`. - -#### Using ExternalName Services across namespaces - -In addition to enabling Kubernetes pods to - -```yaml -kind: Service -apiVersion: v1 -metadata: - name: my-service - namespace: namespace-a -spec: - type: ExternalName - externalName: my-service.namespace-b.svc.cluster.local - ports: - - port: 80 -``` +can start its pods, add appropriate selectors or endpoints, and change the +service's `type`. {{< note >}} This section is indebted to the [Kubernetes Tips - Part From f5b5d2baed809d3edaeae4c33d17e42b1be399b4 Mon Sep 17 00:00:00 2001 From: lucperkins Date: Mon, 9 Jul 2018 13:17:50 -0700 Subject: [PATCH 3/4] Add note on kubectl api-resources command --- .../overview/working-with-objects/namespaces.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/content/en/docs/concepts/overview/working-with-objects/namespaces.md b/content/en/docs/concepts/overview/working-with-objects/namespaces.md index c0de016bbb..cb74056327 100644 --- a/content/en/docs/concepts/overview/working-with-objects/namespaces.md +++ b/content/en/docs/concepts/overview/working-with-objects/namespaces.md @@ -98,4 +98,14 @@ in some namespaces. However namespace resources are not themselves in a namespa And low-level resources, such as [nodes](/docs/admin/node) and persistentVolumes, are not in any namespace. +To see which Kubernetes resources are and aren't in a namespace: + +```shell +# In a namespace +$ kubectl api-resources --namespaced=true + +# Not in a namespace +$ kubectl api-resources --namespaced=false +``` + {{% /capture %}} \ No newline at end of file From b93e8b9941eac5eecc062ec96be312e462977d46 Mon Sep 17 00:00:00 2001 From: lucperkins Date: Tue, 10 Jul 2018 10:16:34 -0700 Subject: [PATCH 4/4] Undo changes accidentally imported from another branch --- .../concepts/services-networking/service.md | 91 ++++++++----------- 1 file changed, 36 insertions(+), 55 deletions(-) diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index b77c5fdd92..dfaa1a0a68 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -135,15 +135,32 @@ The traffic will be routed to endpoints defined by the user (`1.2.3.4:9376` in this example). An ExternalName service is a special case of service that does not have -selectors and uses DNS names instead. For more information, see the -[ExternalName](#externalname) section later in this document. +selectors. It does not define any ports or Endpoints. Rather, it serves as a +way to return an alias to an external service residing outside the cluster. + +```yaml +kind: Service +apiVersion: v1 +metadata: + name: my-service + namespace: prod +spec: + type: ExternalName + externalName: my.database.example.com +``` + +When looking up the host `my-service.prod.svc.CLUSTER`, the cluster DNS service +will return a `CNAME` record with the value `my.database.example.com`. Accessing +such a service works in the same way as others, with the only difference that +the redirection happens at the DNS level and no proxying or forwarding occurs. +Should you later decide to move your database into your cluster, you can start +its pods, add appropriate selectors or endpoints and change the service `type`. ## Virtual IPs and service proxies -Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is +Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is responsible for implementing a form of virtual IP for `Services` of type other -than [`ExternalName`](#externalname). - +than `ExternalName`. In Kubernetes v1.0, `Services` are a "layer 4" (TCP/UDP over IP) construct, the proxy was purely in userspace. In Kubernetes v1.1, the `Ingress` API was added (beta) to represent "layer 7"(HTTP) services, iptables proxy was added too, @@ -331,8 +348,7 @@ can do a DNS SRV query for `"_http._tcp.my-service.my-ns"` to discover the port number for `"http"`. The Kubernetes DNS server is the only way to access services of type -`ExternalName`. More information is available in the [DNS Pods and -Services](/docs/concepts/services-networking/dns-pod-service/). +`ExternalName`. More information is available in the [DNS Pods and Services](/docs/concepts/services-networking/dns-pod-service/). ## Headless services @@ -362,7 +378,7 @@ For headless services that do not define selectors, the endpoints controller doe not create `Endpoints` records. However, the DNS system looks for and configures either: - * CNAME records for [`ExternalName`](#externalname)-type services. + * CNAME records for `ExternalName`-type services. * A records for any `Endpoints` that share a name with the service, for all other types. @@ -380,20 +396,19 @@ The default is `ClusterIP`. * `ClusterIP`: Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster. This is the default `ServiceType`. - * [`NodePort`](#nodeport): Exposes the service on each Node's IP at a static port - (the `NodePort`). A `ClusterIP` service, to which the `NodePort` service will - route, is automatically created. You'll be able to contact the `NodePort` service, - from outside the cluster, + * `NodePort`: Exposes the service on each Node's IP at a static port (the `NodePort`). + A `ClusterIP` service, to which the `NodePort` service will route, is automatically + created. You'll be able to contact the `NodePort` service, from outside the cluster, by requesting `:`. - * [`LoadBalancer`](#loadbalancer): Exposes the service externally using a cloud - provider's load balancer. `NodePort` and `ClusterIP` services, to which the external - load balancer will route, are automatically created. - * [`ExternalName`](#externalname): Maps the service to the contents of the - `externalName` field (e.g. `foo.bar.example.com`), by returning a `CNAME` record - with its value. No proxying of any kind is set up. This requires version 1.7 or - higher of `kube-dns`. + * `LoadBalancer`: Exposes the service externally using a cloud provider's load balancer. + `NodePort` and `ClusterIP` services, to which the external load balancer will route, + are automatically created. + * `ExternalName`: Maps the service to the contents of the `externalName` field + (e.g. `foo.bar.example.com`), by returning a `CNAME` record with its value. + No proxying of any kind is set up. This requires version 1.7 or higher of + `kube-dns`. -### Type NodePort {#nodeport} +### Type NodePort If you set the `type` field to `NodePort`, the Kubernetes master will allocate a port from a range specified by `--service-node-port-range` flag (default: 30000-32767), and each @@ -414,7 +429,7 @@ even to just expose one or more nodes' IPs directly. Note that this Service will be visible as both `:spec.ports[*].nodePort` and `.spec.clusterIP:spec.ports[*].port`. (If the `--nodeport-addresses` flag in kube-proxy is set, would be filtered NodeIP(s).) -### Type LoadBalancer {#loadbalancer} +### Type LoadBalancer On cloud providers which support external load balancers, setting the `type` field to `LoadBalancer` will provision a load balancer for your `Service`. @@ -741,40 +756,6 @@ spec: **Note:** NLB only works with certain instance classes, see the [AWS documentation](http://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets) for supported instance types. -### Type ExternalName {#externalname} - -{{< note >}} -ExternalName Services are available only with `kube-dns` version 1.7 and later. -{{< /note >}} - -Services of type ExternalName map a service to a DNS name (specified using -the `spec.externalName` parameter) rather than to a typical selector like -`my-service` or `cassandra`. This Service definition, for example, would map -the `my-service` Service in the `prod` namespace to `my.database.example.com`: - -```yaml -kind: Service -apiVersion: v1 -metadata: - name: my-service - namespace: prod -spec: - type: ExternalName - externalName: my.database.example.com -``` - -When looking up the host `my-service.prod.svc.CLUSTER`, the cluster DNS service -will return a `CNAME` record with the value `my.database.example.com`. Accessing -`my-service` works in the same way as other Services but with the crucial -difference that redirection happens at the DNS level rather than via proxying or -forwarding. Should you later decide to move your database into your cluster, you -can start its pods, add appropriate selectors or endpoints, and change the -service's `type`. - -{{< note >}} -This section is indebted to the [Kubernetes Tips - Part -1](https://akomljen.com/kubernetes-tips-part-1/) blog post from [Alen Komljen](https://akomljen.com/). -{{< /note >}} ### External IPs