+ + + + +### API Resources + +Service Catalog installs the `servicecatalog.k8s.io` API and provides the following Kubernetes resources: + +* `ClusterServiceBroker`: An in-cluster representation of a Service Broker, encapsulating its server connection details. +These are created and managed by Cluster Operators who wish to use that broker server to make new types of Managed Services available within their cluster. +* `ClusterServiceClass`: A Managed Service offered by a particular Service Broker. +When a new `ClusterServiceBroker` resource is added to the cluster, the Service Catalog controller connects to the Service Broker to obtain a list of available Managed Services. It then creates a new `ClusterServiceClass` resource corresponding to each Managed Service. +* `ClusterServicePlan`: A specific offering of a Managed Service. For example, a Managed Service may have different plans available, such as a free tier or paid tier, or it may have different configuration options, such as using SSD storage or having more resources. Similar to `ClusterServiceClass`, when a new `ClusterServiceBroker` is added to the cluster, the Service Catalog creates a new `ClusterServicePlan` resource corresponding to each Service Plan available for each Managed Service. +* `ServiceInstance`: A provisioned instance of a `ClusterServiceClass`. +These are created by Cluster Operators to make a specific instance of a Managed Service available for use by one or more in-cluster applications. +When a new `ServiceInstance` resource is created, the Service Catalog controller will connect to the appropriate Service Broker and instruct it to provision the service instance. +* `ServiceBinding`: Access credentials to a `ServiceInstance`. +These are created by Cluster Operators who want their applications to make use of a Service `ServiceInstance`. +Upon creation, the Service Catalog controller will create a Kubernetes `Secret` containing connection details and credentials for the Service Instance, which can be mounted into Pods. + +### Authentication + +Service Catalog supports these methods of authentication: + +* Basic (username/password) +* [OAuth 2.0 Bearer Token](https://tools.ietf.org/html/rfc6750) + +## Usage + +A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can use the Service Catalog API Resources to provision Managed Services and make them available within a Kubernetes cluster. The steps involved are: + +1. Listing the Managed Services and Service Plans available from a Service Broker. +1. Provisioning a new instance of the Managed Service. +1. Binding to the Managed Service, which returns the connection credentials. +1. Mapping the connection credentials into the application. + +### Listing Managed Services and Service Plans + +First, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must create a `ClusterServiceBroker` resource within the `servicecatalog.k8s.io` group. This resource contains the URL and connection details necessary to access a Service Broker endpoint. + +This is an example of a `ClusterServiceBroker` resource: + +```yaml +apiVersion: servicecatalog.k8s.io/v1beta1 +kind: ClusterServiceBroker +metadata: + name: cloud-broker +spec: + # Points to the endpoint of a Service Broker. (This example is not a working URL.) + url: https://servicebroker.somecloudprovider.com/v1alpha1/projects/service-catalog/brokers/default + ##### + # Additional values can be added here, which may be used to communicate + # with the Service Broker, such as bearer token info or a caBundle for TLS. + ##### +``` + +The following is a sequence diagram illustrating the steps involved in listing Managed Services and Plans available from a Service Broker: + +{:height="80%" width="80%"} + +1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a *List Services* call to the external Service Broker. +1. The Service Broker returns a list of available Managed Services and Service Plans, which are cached locally in `ClusterServiceClass` and `ClusterServicePlan` resources. +1. A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can then get the list of available Managed Services using the following command: + + kubectl get clusterserviceclasses -o=custom-columns=SERVICE\ NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName + + It should output a list of service names with a format similar to: + + SERVICE NAME EXTERNAL NAME + 4f6e6cf6-ffdd-425f-a2c7-3c9258ad2468 cloud-provider-service + ... ... + + They can also view the Service Plans available using the following command: + + kubectl get clusterserviceplans -o=custom-columns=PLAN\ NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName + + It should output a list of plan names with a format similar to: + + PLAN NAME EXTERNAL NAME + 86064792-7ea2-467b-af93-ac9694d96d52 service-plan-name + ... ... + + +### Provisioning a new instance + +A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can initiate the provisioning of a new instance by creating a `ServiceInstance` resource. + +This is an example of a `ServiceInstance` resource: + +```yaml +apiVersion: servicecatalog.k8s.io/v1beta1 +kind: ServiceInstance +metadata: + name: cloud-queue-instance + namespace: cloud-apps +spec: + # References one of the previously returned services + clusterServiceClassExternalName: cloud-provider-service + clusterServicePlanExternalName: service-plan-name + ##### + # Additional parameters can be added here, + # which may be used by the Service Broker. + ##### +``` + +The following sequence diagram illustrates the steps involved in provisioning a new instance of a Managed Service: + +{:height="80%" width="80%"} + +1. When the `ServiceInstance` resource is created, Service Catalog initiates a *Provision Instance* call to the external Service Broker. +1. The Service Broker creates a new instance of the Managed Service and returns an HTTP response. +1. A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can then check the status of the instance to see if it is ready. + +### Binding to a Managed Service + +After a new instance has been provisioned, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must bind to the Managed Service to get the connection credentials and service account details necessary for the application to use the service. This is done by creating a `ServiceBinding` resource. + +The following is an example of a `ServiceBinding` resource: + +```yaml +apiVersion: servicecatalog.k8s.io/v1beta1 +kind: ServiceBinding +metadata: + name: cloud-queue-binding + namespace: cloud-apps +spec: + instanceRef: + name: cloud-queue-instance + ##### + # Additional information can be added here, such as a secretName or + # service account parameters, which may be used by the Service Broker. + ##### +``` + +The following sequence diagram illustrates the steps involved in binding to a Managed Service instance: + +{:height="80%" width="80%"} + +1. After the `ServiceBinding` is created, Service Catalog makes a *Bind Instance* call to the external Service Broker. +1. The Service Broker enables the application permissions/roles for the appropriate service account. +1. The Service Broker returns the information necessary to connect and access the Managed Service instance. This is provider and service-specific so the information returned may differ between Service Providers and their Managed Services. + +### Mapping the connection credentials + +After binding, the final step involves mapping the connection credentials and service-specific information into the application. +These pieces of information are stored in secrets that the application in the cluster can access and use to connect directly with the Managed Service. + +
+ + + +#### Pod Configuration File + +One method to perform this mapping is to use a declarative Pod configuration. + +The following example describes how to map service account credentials into the application. A key called `sa-key` is stored in a volume named `provider-cloud-key`, and the application mounts this volume at `/var/secrets/provider/key.json`. The environment variable `GOOGLE_APPLICATION_CREDENTIALS` is mapped from the value of the mounted file. + +```yaml +... + spec: + volumes: + - name: provider-cloud-key + secret: + secretName: sa-key + containers: +... + volumeMounts: + - name: provider-cloud-key + mountPath: /var/secrets/provider + env: + - name: PROVIDER_APPLICATION_CREDENTIALS + value: "/var/secrets/provider/key.json" +``` + +The following example describes how to map secret values into application environment variables. In this example, the messaging queue topic name is mapped from a secret named `provider-queue-credentials` with a key named `topic` to the environment variable `TOPIC`. + + +```yaml +... + env: + - name: "TOPIC" + valueFrom: + secretKeyRef: + name: provider-queue-credentials + key: topic +``` + +{% endcapture %} + + +{% capture whatsnext %} +* If you are familiar with {% glossary_tooltip text="Helm Charts" term_id="helm-chart" %}, [install Service Catalog using Helm](/docs/tasks/service-catalog/install-service-catalog-using-helm/) into your Kubernetes cluster. Alternatively, you can [install Service Catalog using the SC tool](/docs/tasks/service-catalog/install-service-catalog-using-sc/). +* View [sample service brokers](https://github.com/openservicebrokerapi/servicebroker/blob/master/gettingStarted.md#sample-service-brokers). +* Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project. + +{% endcapture %} + + +{% include templates/concept.md %} diff --git a/docs/concepts/services-networking/service.md b/docs/concepts/services-networking/service.md index 8aae3f98a0..089fab27cf 100644 --- a/docs/concepts/services-networking/service.md +++ b/docs/concepts/services-networking/service.md @@ -117,7 +117,7 @@ subsets: - port: 9376 ``` -NOTE: Endpoint IPs may not be loopback (127.0.0.0/8), link-local +**NOTE:** Endpoint IPs may not be loopback (127.0.0.0/8), link-local (169.254.0.0/16), or link-local multicast (224.0.0.0/24). Accessing a `Service` without a selector works the same as if it had a selector. @@ -151,13 +151,11 @@ its pods, add appropriate selectors or endpoints and change the service `type`. 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. - -As of Kubernetes v1.0, `Services` are a "layer 4" (TCP/UDP over IP) construct. -In Kubernetes v1.1 the `Ingress` API was added (beta) to represent "layer 7" -(HTTP) services. +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, +and become the default operating mode since Kubernetes v1.2. In Kubernetes v1.9-alpha, +ipvs proxy was added. ### Proxy-mode: userspace @@ -169,37 +167,20 @@ will be proxied to one of the `Service`'s backend `Pods` (as reported in `SessionAffinity` of the `Service`. Lastly, it installs iptables rules which capture traffic to the `Service`'s `clusterIP` (which is virtual) and `Port` and redirects that traffic to the proxy port which proxies the backend `Pod`. - -The net result is that any traffic bound for the `Service`'s IP:Port is proxied -to an appropriate backend without the clients knowing anything about Kubernetes -or `Services` or `Pods`. - -By default, the choice of backend is round robin. Client-IP based session affinity -can be selected by setting `service.spec.sessionAffinity` to `"ClientIP"` (the -default is `"None"`), and you can set the max session sticky time by setting the field -`service.spec.sessionAffinityConfig.clientIP.timeoutSeconds` if you have already set -`service.spec.sessionAffinity` to `"ClientIP"` (the default is "10800"). +By default, the choice of backend is round robin.  ### Proxy-mode: iptables In this mode, kube-proxy watches the Kubernetes master for the addition and -removal of `Service` and `Endpoints` objects. For each `Service` it installs +removal of `Service` and `Endpoints` objects. For each `Service`, it installs iptables rules which capture traffic to the `Service`'s `clusterIP` (which is virtual) and `Port` and redirects that traffic to one of the `Service`'s -backend sets. For each `Endpoints` object it installs iptables rules which -select a backend `Pod`. +backend sets. For each `Endpoints` object, it installs iptables rules which +select a backend `Pod`.By default, the choice of backend is random. -By default, the choice of backend is random. Client-IP based session affinity -can be selected by setting `service.spec.sessionAffinity` to `"ClientIP"` (the -default is `"None"`), and you can set the max session sticky time by setting the field -`service.spec.sessionAffinityConfig.clientIP.timeoutSeconds` if you have already set -`service.spec.sessionAffinity` to `"ClientIP"` (the default is "10800"). - -As with the userspace proxy, the net result is that any traffic bound for the -`Service`'s IP:Port is proxied to an appropriate backend without the clients -knowing anything about Kubernetes or `Services` or `Pods`. This should be +Obviously, iptables need not switch back between userspace and kernelspace, it should be faster and more reliable than the userspace proxy. However, unlike the userspace proxier, the iptables proxier cannot automatically retry another `Pod` if the one it initially selects does not respond, so it depends on @@ -231,12 +212,21 @@ options for load balancing algorithm, such as: - nq: never queue **Note:** ipvs mode assumed IPVS kernel modules are installed on the node -before running kube-proxy. When kube-proxy starts, if proxy mode is ipvs, +before running kube-proxy. When kube-proxy starts with ipvs proxy mode, kube-proxy would validate if IPVS modules are installed on the node, if it's not installed kube-proxy will fall back to iptables proxy mode.  +In any of proxy model, any traffic bound for the Service’s IP:Port is +proxied to an appropriate backend without the clients knowing anything +about Kubernetes or Services or Pods. Client-IP based session affinity +can be selected by setting service.spec.sessionAffinity to "ClientIP" +(the default is "None"), and you can set the max session sticky time by +setting the field service.spec.sessionAffinityConfig.clientIP.timeoutSeconds +if you have already set service.spec.sessionAffinity to "ClientIP" +(the default is “10800”). + ## Multi-Port Services Many `Services` need to expose more than one port. For this case, Kubernetes @@ -708,6 +698,10 @@ work, and the client IP is not altered. This same basic flow executes when traffic comes in through a node-port or through a load-balancer, though in those cases the client IP does get altered. +#### Ipvs + +Iptables operations slow down dramatically in large scale cluster e.g 10,000 Services. IPVS is designed for load balancing and based on in-kernel hash tables. So we can achieve performance consistency in large number of services from IPVS-based kube-proxy. Meanwhile, IPVS-based kube-proxy has more sophisticated load balancing algorithms (least conns, locality, weighted, persistence). + ## API Object Service is a top-level resource in the Kubernetes REST API. More details about the diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index 4dccc7bc75..aebe9c5cf6 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -54,7 +54,7 @@ dynamic provisioning for themselves. To enable dynamic storage provisioning based on storage class, the cluster administrator needs to enable the `DefaultStorageClass` [admission controller](/docs/admin/admission-controllers/#defaultstorageclass) on the API server. This can be done, for example, by ensuring that `DefaultStorageClass` is -among the comma-delimited, ordered list of values for the `--admission-control` flag of +among the comma-delimited, ordered list of values for the `--admission-control` flag of the API server component. For more information on API server command line flags, please check [kube-apiserver](/docs/admin/kube-apiserver/) documentation. @@ -417,8 +417,6 @@ spec: `PersistentVolumes` binds are exclusive, and since `PersistentVolumeClaims` are namespaced objects, mounting claims with "Many" modes (`ROX`, `RWX`) is only possible within one namespace. -`` - ## Writing Portable Configuration If you're writing configuration templates or examples that run on a wide range of clusters @@ -455,4 +453,3 @@ and need persistent storage, we recommend that you use the following pattern: default. At some point, the alpha annotation will cease to have meaning, but the unset `storageClass` field on the PVC will have the desired effect. - diff --git a/docs/concepts/storage/volumes.md b/docs/concepts/storage/volumes.md index 4ea6df948a..2d2ad25678 100644 --- a/docs/concepts/storage/volumes.md +++ b/docs/concepts/storage/volumes.md @@ -65,33 +65,118 @@ mount each volume. Kubernetes supports several types of Volumes: - * `emptyDir` - * `hostPath` - * `gcePersistentDisk` * `awsElasticBlockStore` - * `nfs` - * `iscsi` - * `fc (fibre channel)` - * `flocker` - * `glusterfs` - * `rbd` - * `cephfs` - * `gitRepo` - * `secret` - * `persistentVolumeClaim` - * `downwardAPI` - * `projected` - * `azureFileVolume` * `azureDisk` - * `vsphereVolume` - * `Quobyte` - * `PortworxVolume` - * `ScaleIO` - * `StorageOS` + * `azureFile` + * `cephfs` + * `downwardAPI` + * `emptyDir` + * `fc` (fibre channel) + * `flocker` + * `gcePersistentDisk` + * `gitRepo` + * `glusterfs` + * `hostPath` + * `iscsi` * `local` + * `nfs` + * `persistentVolumeClaim` + * `projected` + * `portworxVolume` + * `quobyte` + * `rbd` + * `scaleIO` + * `secret` + * `storageos` + * `vsphereVolume` We welcome additional contributions. +### awsElasticBlockStore + +An `awsElasticBlockStore` volume mounts an Amazon Web Services (AWS) [EBS +Volume](http://aws.amazon.com/ebs/) into your pod. Unlike +`emptyDir`, which is erased when a Pod is removed, the contents of an EBS +volume are preserved and the volume is merely unmounted. This means that an +EBS volume can be pre-populated with data, and that data can be "handed off" +between pods. + +**Important:** You must create an EBS volume using `aws ec2 create-volume` or the AWS API before you can use it. +{: .caution} + +There are some restrictions when using an awsElasticBlockStore volume: + +* the nodes on which pods are running must be AWS EC2 instances +* those instances need to be in the same region and availability-zone as the EBS volume +* EBS only supports a single EC2 instance mounting a volume + +#### Creating an EBS volume + +Before you can use an EBS volume with a pod, you need to create it. + +```shell +aws ec2 create-volume --availability-zone=eu-west-1a --size=10 --volume-type=gp2 +``` + +Make sure the zone matches the zone you brought up your cluster in. (And also check that the size and EBS volume +type are suitable for your use!) + +#### AWS EBS Example configuration + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-ebs +spec: + containers: + - image: gcr.io/google_containers/test-webserver + name: test-container + volumeMounts: + - mountPath: /test-ebs + name: test-volume + volumes: + - name: test-volume + # This AWS EBS volume must already exist. + awsElasticBlockStore: + volumeID:
- Attend KubeCon in Austin, TX on December 6-8, 2017 + Attend KubeCon in Austin, TX on December 6-8, 2017