github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-08-04 01:40:07 +00:00
Code Issues Projects Releases Wiki Activity

Hopefully make NodePort docs clearer

Browse Source
This commit is contained in:
Tim Hockin 2015-06-19 15:08:36 -07:00
parent 3afda5d566
commit ff91fef26b
3 changed files with 45 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
api/swagger-spec/v1.json
View File

@ -13399,8 +13399,7 @@
"v1.ServiceSpec": { "v1.ServiceSpec": {
"id": "v1.ServiceSpec", "id": "v1.ServiceSpec",
"required": [ "required": [
"ports", "ports"
"clusterIP"
], ],
"properties": { "properties": {
"ports": { "ports": {
@ -13415,7 +13414,8 @@
"description": "label keys and values that must match in order to receive traffic for this service; if empty, all pods are selected, if not specified, endpoints must be manually specified" "description": "label keys and values that must match in order to receive traffic for this service; if empty, all pods are selected, if not specified, endpoints must be manually specified"
}, },
"clusterIP": { "clusterIP": {
"type": "string" "type": "string",
"description": "IP address of the service; usually assigned by the system; if specified, it will be allocated to the service if unused or else creation of the service will fail; cannot be updated; 'None' can be specified for a headless service when proxying is not required"
}, },
"type": { "type": {
"type": "string", "type": "string",
@ -13461,7 +13461,7 @@
"nodePort": { "nodePort": {
"type": "integer", "type": "integer",
"format": "int32", "format": "int32",
"description": "the port on each node on which this service is exposed" "description": "the port on each node on which this service is exposed when type=NodePort or LoadBalancer; usually assigned by the system; if specified, it will be allocated to the service if unused or else creation of the service will fail"
} }
} }
}, },

73
docs/services.md
View File

@ -17,8 +17,8 @@ Enter `Services`.
A Kubernetes `Service` is an abstraction which defines a logical set of `Pods` A Kubernetes `Service` is an abstraction which defines a logical set of `Pods`
and a policy by which to access them - sometimes called a micro-service. The and a policy by which to access them - sometimes called a micro-service. The
set of `Pods` targeted by a `Service` is (usually) determined by a [`Label set of `Pods` targeted by a `Service` is (usually) determined by a [`Label
Selector`](labels.md#label-selectors) (see below for why you might want a `Service` without a Selector`](labels.md#label-selectors) (see below for why you might want a
selector). `Service` without a selector).
As an example, consider an image-processing backend which is running with 3 As an example, consider an image-processing backend which is running with 3
replicas. Those replicas are fungible - frontends do not care which backend replicas. Those replicas are fungible - frontends do not care which backend
@ -64,17 +64,17 @@ This specification will create a new `Service` object named "my-service" which
targets TCP port 9376 on any `Pod` with the "app=MyApp" label. This `Service` targets TCP port 9376 on any `Pod` with the "app=MyApp" label. This `Service`
will also be assigned an IP address (sometimes called the "cluster IP"), which will also be assigned an IP address (sometimes called the "cluster IP"), which
is used by the service proxies (see below). The `Service`'s selector will be is used by the service proxies (see below). The `Service`'s selector will be
evaluated continuously and the results will be posted in an `Endpoints` object evaluated continuously and the results will be POSTed to an `Endpoints` object
also named "my-service". also named "my-service".
Note that a `Service` can map an incoming port to any `targetPort`. By default Note that a `Service` can map an incoming port to any `targetPort`. By default
the `targetPort` is the same as the `port` field. Perhaps more interesting is the `targetPort` will be set to the same value as the `port` field. Perhaps
that `targetPort` can be a string, referring to the name of a port in the more interesting is that `targetPort` can be a string, referring to the name of
backend `Pods`. The actual port number assigned to that name can be different a port in the backend `Pods`. The actual port number assigned to that name can
in each backend `Pod`. This offers a lot of flexibility for deploying and be different in each backend `Pod`. This offers a lot of flexibility for
evolving your `Services`. For example, you can change the port number that deploying and evolving your `Services`. For example, you can change the port
pods expose in the next version of your backend software, without breaking number that pods expose in the next version of your backend software, without
clients. breaking clients.
Kubernetes `Services` support `TCP` and `UDP` for protocols. The default Kubernetes `Services` support `TCP` and `UDP` for protocols. The default
is `TCP`. is `TCP`.
@ -143,13 +143,12 @@ this example).
Every node in a Kubernetes cluster runs a `kube-proxy`. This application Every node in a Kubernetes cluster runs a `kube-proxy`. This application
watches the Kubernetes master for the addition and removal of `Service` watches the Kubernetes master for the addition and removal of `Service`
and `Endpoints` objects. For each `Service` it opens a port (random) on the and `Endpoints` objects. For each `Service` it opens a port (randomly chosen)
local node. Any connections made to that port will be proxied to one of the on the local node. Any connections made to that port will be proxied to one of
corresponding backend `Pods`. Which backend to use is decided based on the the corresponding backend `Pods`. Which backend to use is decided based on the
`SessionAffinity` of the `Service`. Lastly, it installs iptables rules which `SessionAffinity` of the `Service`. Lastly, it installs iptables rules which
capture traffic to the `Service`'s `Port` on the `Service`'s cluster IP (which capture traffic to the `Service`'s cluster IP (which is virtual) and `Port` and
is entirely virtual) and redirects that traffic to the previously described redirects that traffic to the previously described port.
port.
The net result is that any traffic bound for the `Service` is proxied to an The net result is that any traffic bound for the `Service` is proxied to an
appropriate backend without the clients knowing anything about Kubernetes or appropriate backend without the clients knowing anything about Kubernetes or
@ -202,14 +201,14 @@ disambiguated. For example:
## Choosing your own IP address ## Choosing your own IP address
A user can specify their own cluster IP address as part of a `Service` creation You can specify your own cluster IP address as part of a `Service` creation
request. To do this, set the `spec.clusterIP` field. For example, if they request. To do this, set the `spec.clusterIP` field. For example, if you
already have an existing DNS entry that they wish to replace, or legacy systems already have an existing DNS entry that you wish to replace, or legacy systems
that are configured for a specific IP address and difficult to re-configure. that are configured for a specific IP address and difficult to re-configure.
The IP address that a user chooses must be a valid IP address and within the The IP address that a user chooses must be a valid IP address and within the
service_cluster_ip_range CIDR range that is specified by flag to the API server. service_cluster_ip_range CIDR range that is specified by flag to the API
If the IP address value is invalid, the apiserver returns a 422 HTTP status code server. If the IP address value is invalid, the apiserver returns a 422 HTTP
to indicate that the value is invalid. status code to indicate that the value is invalid.
### Why not use round-robin DNS? ### Why not use round-robin DNS?
@ -273,16 +272,18 @@ a name lookup for "my-service". `Pods` which exist in other `Namespaces` must
qualify the name as "my-service.my-ns". The result of these name lookups is the qualify the name as "my-service.my-ns". The result of these name lookups is the
cluster IP. cluster IP.
We will soon add DNS support for multi-port `Services` in the form of SRV Kubernetes also supports DNS SRV (service) records for named ports. If the
records. "my-service.my-ns" `Service` has a port named "http" with protocol `TCP`, you
can do a DNS SRV query for "_http._tcp.my-service.my-ns" to discover the port
number for "http".
## Headless services ## Headless services
Sometimes you don't need or want load-balancing and a single service IP. In Sometimes you don't need or want load-balancing and a single service IP. In
this case, you can create "headless" services by specifying `"None"` for the this case, you can create "headless" services by specifying `"None"` for the
cluster IP (`spec.clusterIP`). cluster IP (`spec.clusterIP`).
For such `Services`, a cluster IP is not allocated and service-specific
environment variables for `Pods` are not created. DNS is configured to return For such `Services`, a cluster IP is not allocated. DNS is configured to return
multiple A records (addresses) for the `Service` name, which point directly to multiple A records (addresses) for the `Service` name, which point directly to
the `Pods` backing the `Service`. Additionally, the kube proxy does not handle the `Pods` backing the `Service`. Additionally, the kube proxy does not handle
these services and there is no load balancing or proxying done by the platform these services and there is no load balancing or proxying done by the platform
@ -301,12 +302,13 @@ Service onto an external (outside of your cluster, maybe public internet) IP
address. Kubernetes supports two ways of doing this: `NodePort`s and address. Kubernetes supports two ways of doing this: `NodePort`s and
`LoadBalancer`s. `LoadBalancer`s.
Every `Service` has a `Type` field which defines how the `Service` can be Every `Service` has a `type` field which defines how the `Service` can be
accessed. Valid values for this field are: accessed. Valid values for this field are:
* `ClusterIP`: use a cluster-internal IP only - this is the default * `ClusterIP`: use a cluster-internal IP only - this is the default and is
discussed above
* `NodePort`: use a cluster IP, but also expose the service on a port on each * `NodePort`: use a cluster IP, but also expose the service on a port on each
node of the cluster (the same port on each) node of the cluster (the same port on each node)
* `LoadBalancer`: use a ClusterIP and a NodePort, but also ask the cloud * `LoadBalancer`: use a ClusterIP and a NodePort, but also ask the cloud
provider for a load balancer which forwards to the `Service` provider for a load balancer which forwards to the `Service`
@ -316,11 +318,14 @@ as of Kubernetes 1.0.
### Type = NodePort ### Type = NodePort
If you set the `type` field to `"NodePort"`, the Kubernetes master will If you set the `type` field to `"NodePort"`, the Kubernetes master will
allocate you a port (from a flag-configured range, default: 30,000 - 32,767) allocate a port from a flag-configured range (default: 30000-32767), and each
on each node for each port exposed by your `Service`. That port will be node will proxy that port (the same port number on every node) into your `Service`.
reported in your `Service`'s `spec.ports[*].nodePort` field. If you specify That port will be reported in your `Service`'s `spec.ports[*].nodePort` field.
a value in that field, the system will allocate you that port or else will
fail the API transaction. If you want a specific port number, you can specify a value in the `nodePort`
field, and the system will allocate you that port or else the API transaction
will fail. The value you specify must be in the configured range for node
ports.
This gives developers the freedom to set up their own load balancers, to This gives developers the freedom to set up their own load balancers, to
configure cloud environments that are not fully supported by Kubernetes, or configure cloud environments that are not fully supported by Kubernetes, or

4
pkg/api/v1/types.go
View File

@ -1071,7 +1071,7 @@ type ServiceSpec struct {
// not be changed by updates. // not be changed by updates.
// Valid values are None, empty string (""), or a valid IP address // Valid values are None, empty string (""), or a valid IP address
// None can be specified for headless services when proxying is not required // None can be specified for headless services when proxying is not required
ClusterIP string `json:"clusterIP,omitempty description: IP address of the service; usually assigned by the system; if specified, it will be allocated to the service if unused, and creation of the service will fail otherwise; cannot be updated; 'None' can be specified for a headless service when proxying is not required"` ClusterIP string `json:"clusterIP,omitempty" description:"IP address of the service; usually assigned by the system; if specified, it will be allocated to the service if unused or else creation of the service will fail; cannot be updated; 'None' can be specified for a headless service when proxying is not required"`
// Type determines how the service will be exposed. Valid options: ClusterIP, NodePort, LoadBalancer // Type determines how the service will be exposed. Valid options: ClusterIP, NodePort, LoadBalancer
Type ServiceType `json:"type,omitempty" description:"type of this service; must be ClusterIP, NodePort, or LoadBalancer; defaults to ClusterIP"` Type ServiceType `json:"type,omitempty" description:"type of this service; must be ClusterIP, NodePort, or LoadBalancer; defaults to ClusterIP"`
@ -1106,7 +1106,7 @@ type ServicePort struct {
// The port on each node on which this service is exposed. // The port on each node on which this service is exposed.
// Default is to auto-allocate a port if the ServiceType of this Service requires one. // Default is to auto-allocate a port if the ServiceType of this Service requires one.
NodePort int `json:"nodePort" description:"the port on each node on which this service is exposed"` NodePort int `json:"nodePort" description:"the port on each node on which this service is exposed when type=NodePort or LoadBalancer; usually assigned by the system; if specified, it will be allocated to the service if unused or else creation of the service will fail"`
} }
// Service is a named abstraction of software service (for example, mysql) consisting of local port // Service is a named abstraction of software service (for example, mysql) consisting of local port