Skip to content
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 · 13 comments
Closed

Service type=ExternalName is not documented enough #5822

ahmetb opened this issue Oct 9, 2017 · 13 comments
Assignees

Comments

@ahmetb
Copy link
Member

@ahmetb 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
Copy link
Member Author

@ahmetb ahmetb commented Oct 9, 2017

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

@mooperd
Copy link

@mooperd 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
Copy link
Contributor

@tonglil 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
Copy link
Member

@bowei bowei commented Dec 6, 2017

@tonglil -- lgtm

@ryanmcginnis
Copy link
Contributor

@ryanmcginnis ryanmcginnis commented Mar 22, 2018

Ping. Is this still being worked on?

@ahmetb
Copy link
Member Author

@ahmetb ahmetb commented Mar 22, 2018

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

@RouR
Copy link

@RouR 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
Copy link

@pablodav 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
Copy link

@pablodav 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
Copy link
Contributor

@lucperkins lucperkins commented Jun 21, 2018

/assign

@lucperkins
Copy link
Contributor

@lucperkins 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
Copy link

@nightswimmings nightswimmings commented Nov 6, 2018

Do ExternalName services support port binding?

@pyramation
Copy link

@pyramation pyramation commented Jun 4, 2020

@nightswimmings I'm also curious. From what I can tell, if you add port or ports the behavior is as follows (it does nothing):

apiVersion: v1
kind: Service
metadata:
  name: postgres-service
  namespace: mynamespace
spec:
  type: ExternalName
  externalName: my-prod-db.abcd.us-east-1.rds.amazonaws.com
  ports:
    - name: pg
      protocol: TCP
      port: 5432
      targetPort: 5432

Then I test inside of a box in the same namespace, I test the connection, and the only way I get anything is by using :5432 with the hostname:

curl -v postgres-service.mynamespace.svc.cluster.local:5432
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet