New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Service type=ExternalName is not documented enough #5822

Closed
ahmetb opened this Issue Oct 9, 2017 · 12 comments

Comments

Projects
None yet
10 participants
@ahmetb
Member

ahmetb commented Oct 9, 2017

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

This comment has been minimized.

Member

ahmetb commented Oct 9, 2017

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

@mooperd

This comment has been minimized.

mooperd commented Oct 26, 2017

+1

@steveperry-53 steveperry-53 added this to KubeCon Docs Sprint in Doc Writing and Editing Nov 1, 2017

@Bradamant3 Bradamant3 added this to Miscellaneous small issues in Doc Sprints Nov 21, 2017

@tonglil

This comment has been minimized.

Contributor

tonglil commented Dec 6, 2017

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

This comment has been minimized.

Member

bowei commented Dec 6, 2017

@tonglil -- lgtm

@ryanmcginnis

This comment has been minimized.

Contributor

ryanmcginnis commented Mar 22, 2018

Ping. Is this still being worked on?

@ahmetb

This comment has been minimized.

Member

ahmetb commented Mar 22, 2018

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

@RouR

This comment has been minimized.

RouR commented May 19, 2018

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

This comment has been minimized.

pablodav commented Jun 11, 2018

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

This comment has been minimized.

pablodav commented Jun 19, 2018

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

This comment has been minimized.

Collaborator

lucperkins commented Jun 21, 2018

/assign

@lucperkins

This comment has been minimized.

Collaborator

lucperkins commented Jun 21, 2018

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

@nightswimmings

This comment has been minimized.

nightswimmings commented Nov 6, 2018

Do ExternalName services support port binding?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment