Service type=ExternalName is not documented enough

[ahmetb]

We currently document service types in this doc: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types Among these, only 2 types, NodePort and LoadBalancer have their own sections.

Currently all documentation about ExternalName type is listed below. Even this is still not helping me enough to understand what purpose this feature serves, how it can be used (it says proxying is not provided). I think we need a dedicated section to explain this type.

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.
...

Virtual IPs and service proxies

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. In Kubernetes v1.0 the proxy was purely in userspace. In Kubernetes v1.1 an iptables proxy was added, but was not the default operating mode. Since Kubernetes v1.2, the iptables proxy is the default.
...

Publishing services - service types

...

• 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.

I'm assuming it's a relatively new feature, that's why the comprehensive documentation is lacking.

/cc @kubernetes/sig-network-misc

[ahmetb]

I've found a better explanation at https://akomljen.com/kubernetes-tips-part-1/

[mooperd]

+1

[tonglil]

The whole Services page is a bit of a mess to read and comprehend right now, especially for new users. There is information about system-level choices like kube-proxy to user-level things like DNS, service types, and selectors.

I propose that the content on the current Services page gets reorganized and broken down into these subsections:

• Services, Load Balancing, and Networking > Services
  1. Services main page, including:
     • Defining a service
     • Selectors
     • Multiport
     • Choosing your own IP address
  2. Headless services
  3. Publishing services aka service types, including:
     • ClusterIP
     • NodePort
     • LoadBalancer
       • Internal LB
       • SSL
     • ExternalName
     • External IPs
  4. Discovering services
  5. kube-proxy behavior
  6. Shortcomings + future work
  7. Implementation gore/details

If this sounds good, I can take a stab at it.

[bowei]

@tonglil -- lgtm

[ryanmcginnis]

Ping. Is this still being worked on?

[ahmetb]

Nobody seems to have self-assigned. I'm not sure about the status.

[RouR]

Can I set IP instead of dns name?
Somethig like this

kind: Service
apiVersion: v1
metadata:
  name: external-grafana
  namespace: kube-system
spec:
  type: ExternalName
  externalName: 207.244.95.62
  ports:
  - port: 3000

[pablodav]

For new users (like me) I think could be common to confuse the purpose of service and ingress.
Until I got into clear picture of ingress and its scope I though I'm could resolve the exposition of my services to my users with "services".
When I read ExternalName it confuses more both, because I can use nginx-ingress and ExternalName with very similar objective.

Until now I don't know if ExternalName could replace the need of nginx-ingress in my on-premises deployment, and wha'ts the scope of ExternalName on-premises.

It is not clear in the documentation what is the best choice to start on-premises (There is better documented choices per cloud provider), probably some wider perspective could be added for on-premises.

For example, until projects like https://metallb.universe.tf/ and nginx-ingress are better documented / mature, is the best option to use the weak NodePort and setup a fixed config reverse-proxy pointing to my node's IPs outside my cluster?

[pablodav]

Some documentation with more details and clear explanation like this:

https://medium.com/@kyralak/accessing-kubernetes-services-without-ingress-nodeport-or-loadbalancer-de6061b42d72

could be very useful for newbies.
It helped me a lot.

[lucperkins]

/assign

[lucperkins]

@tonglil That's a great suggestion for content structure. For now, I'm going to address the specific issue regarding ExternalName service definitions. At some point, though, I'd love to restructure that doc, as you are right that it could use some user-friendliness-directed re-org. I'll be in touch if I do so.