Browse Source

Update README

Put a fuller description of the state of the project in the README, and
copy in the FAQ from the initial project kickoff email[1].

[1] http://lists.openstack.org/pipermail/openstack-dev/2018-June/131183.html

Change-Id: I9e7e59756fc73377abb0a75b9aad15712e7b8a31
changes/30/579230/1
Zane Bitter 10 months ago
parent
commit
b589194d5c
1 changed files with 210 additions and 5 deletions
  1. 210
    5
      README.rst

+ 210
- 5
README.rst View File

@@ -5,15 +5,220 @@ openstack-service-broker
5 5
 Builds Ansible Playbook Bundles for use in Automation Broker to expose
6 6
 OpenStack resources in the Kubernetes Service Catalog.
7 7
 
8
-Please fill here a long description which must be at least 3 lines wrapped on
9
-80 cols, so that distribution package maintainers can use it in their packages.
10
-Note that this is a hard requirement.
8
+The project is in the very early stages of development. We will first build a
9
+prototype that demonstrates the concept of managing OpenStack resources through
10
+the Kubernetes Service Catalog, using the http://automationbroker.io/ project
11
+to implement the Open Service Broker API, which in turn uses Ansible playbooks
12
+to drive the underlying services.
11 13
 
12 14
 * Free software: Apache license
13
-* Documentation: https://docs.openstack.org/openstack-service-broker/latest
14 15
 * Source: https://git.openstack.org/cgit/openstack/openstack-service-broker
15 16
 * Bugs: https://storyboard.openstack.org/#!/project/1038
16 17
 
17 18
 --------
18 19
 
19
-* TODO
20
+Join Us
21
+=======
22
+
23
+* On the `openstack-dev`_ mailing list (use ``[service-broker]`` in the subject
24
+  line)
25
+* In ``#openstack-service-broker`` on `FreeNode`_.
26
+* Working on the `prototype worklist`_.
27
+
28
+.. _openstack-dev: http://lists.openstack.org/pipermail/openstack-dev/
29
+.. _FreeNode: https://freenode.net/
30
+.. _prototype worklist: https://storyboard.openstack.org/#!/worklist/391
31
+
32
+FAQ
33
+===
34
+
35
+What is the Open Service Broker API?
36
+------------------------------------
37
+
38
+The `Open Service Broker API`_ is a standard way to expose external resources
39
+to applications running in a PaaS. It was originally developed in the context
40
+of CloudFoundry, but the same standard was adopted by Kubernetes (and hence
41
+OpenShift) in the form of the `Service Catalog extension`_. (The Service
42
+Catalog in Kubernetes is the component that calls out to a service broker.) So
43
+a single implementation can cover the most popular open-source PaaS offerings.
44
+
45
+In many cases, the services take the form of simply a pre-packaged application
46
+that also runs inside the PaaS. But they don't have to be - services can be
47
+anything. Provisioning via the service broker ensures that the services
48
+requested are tied in to the PaaS's orchestration of the application's
49
+lifecycle.
50
+
51
+(This is certainly not the be-all and end-all of integration between OpenStack
52
+and containers - we also need ways to tie PaaS-based applications into the
53
+OpenStack's orchestration of a larger group of resources. Some applications may
54
+even use both. But it's an important part of the story.)
55
+
56
+What sorts of services would OpenStack expose?
57
+----------------------------------------------
58
+
59
+Some example use cases might be:
60
+
61
+* The application needs a reliable message queue. Rather than spinning up
62
+  multiple storage-backed containers with anti-affinity policies and dealing
63
+  with the overhead of managing e.g. RabbitMQ, the application requests a Zaqar
64
+  queue from an OpenStack cloud. The overhead of running the queueing service
65
+  is amortised across all of the applications in the cloud. The queue gets
66
+  cleaned up correctly when the application is removed, since it is tied into
67
+  the application definition.
68
+* The application needs a database. Rather than spinning one up in a
69
+  storage-backed container and dealing with the overhead of managing it, the
70
+  application requests a Trove DB from an OpenStack cloud.
71
+* The application includes a service that needs to run on bare metal for
72
+  performance reasons (e.g. could also be a database). The application requests
73
+  a bare-metal server from Nova w/ Ironic for the purpose. (The same applies to
74
+  requesting a VM, but there are alternatives like KubeVirt - which also
75
+  operates through the Service Catalog - available for getting a VM in
76
+  Kubernetes. There are no non-proprietary alternatives for getting a
77
+  bare-metal server.)
78
+
79
+`AWS`_, `Azure`_, and `GCP`_ all have service brokers available that support
80
+these and many more services that they provide. I don't know of any reason in
81
+principle not to expose every type of resource that OpenStack provides via a
82
+service broker.
83
+
84
+How is this different from cloud-provider-openstack?
85
+----------------------------------------------------
86
+
87
+The `Cloud Controller`_ interface in Kubernetes allows Kubernetes itself to
88
+access features of the cloud to provide its service. For example, if k8s needs
89
+persistent storage for a container then it can request that from Cinder through
90
+`cloud-provider-openstack`_. It can also request a load balancer from Octavia
91
+instead of having to start a container running HAProxy to load balance between
92
+multiple instances of an application container (thus enabling use of hardware
93
+load balancers via the cloud's abstraction for them).
94
+
95
+In contrast, the Service Catalog interface allows the *application* running on
96
+Kubernetes to access features of the cloud.
97
+
98
+What does a service broker look like?
99
+-------------------------------------
100
+
101
+A service broker provides an HTTP API with 5 actions:
102
+
103
+* List the services provided by the broker
104
+* Create an instance of a resource
105
+* Bind the resource into an instance of the application
106
+* Unbind the resource from an instance of the application
107
+* Delete the resource
108
+
109
+The binding step is used for things like providing a set of DB credentials to a
110
+container. You can rotate credentials when replacing a container by revoking
111
+the existing credentials on unbind and creating a new set on bind, without
112
+replacing the entire resource.
113
+
114
+Is there an easier way?
115
+-----------------------
116
+
117
+Yes! Folks from OpenShift came up with a project called the `Automation
118
+Broker`_. To add support for a service to Automation Broker you just create a
119
+container with an Ansible playbook to handle each of the actions
120
+(create/bind/unbind/delete). This eliminates the need to write another
121
+implementation of the service broker API, and allows us to simply `write
122
+Ansible playbooks instead`_.
123
+
124
+(Aside: Heat uses a comparable method to allow users to manage an external
125
+resource using Mistral workflows: the OS::Mistral::ExternalResource resource
126
+type.)
127
+
128
+Support for accessing `AWS`_ resources through a service broker is also
129
+implemented using these Ansible Playbook Bundles.
130
+
131
+Does this mean maintaining another client interface?
132
+----------------------------------------------------
133
+
134
+Maybe not. We already have per-project Python libraries, (deprecated)
135
+per-project CLIs, openstackclient CLIs, openstack-sdk, shade, Heat resource
136
+plugins, and Horizon dashboards. (Mistral actions are generated automatically
137
+from the clients.) Some consolidation is already planned, but it would be great
138
+not to require projects to maintain yet another interface.
139
+
140
+One option is to implement a tool that generates a set of playbooks for each of
141
+the resources already exposed (via shade) in the OpenStack Ansible modules.
142
+Then in theory we'd only need to implement the common parts once, and then
143
+every service with support in shade would get this for free. Ideally the same
144
+broker could be used against any OpenStack cloud (so e.g. k8s might be running
145
+in your private cloud, but you may want its service catalog to allow you to
146
+connect to resources in one or more public clouds) - using shade is an
147
+advantage there because it is designed to abstract the differences between
148
+clouds.
149
+
150
+Another option might be to write or generate Heat templates for each resource
151
+type we want to expose. Then we'd only need to implement a common way of
152
+creating a Heat stack, and just have a different template for each resource
153
+type. This is the approach taken by the AWS playbook bundles (except with
154
+CloudFormation, obviously). An advantage is that this allows Heat to do any
155
+checking and type conversion required on the input parameters. Heat templates
156
+can also be made to be fairly cloud-independent, mainly because they make it
157
+easier to be explicit about things like ports and subnets than on the command
158
+line, where it's more tempting to allow things to happen in a magical but
159
+cloud-specific way.
160
+
161
+I'd prefer to go with the pure-Ansible autogenerated way so we can have support
162
+for everything, but looking at the `GCP`_/`Azure`_/`AWS`_ brokers they have 10,
163
+11 and 17 services respectively, so arguably we could get a comparable number
164
+of features exposed without investing crazy amounts of time if we had to write
165
+templates explicitly.
166
+
167
+How would authentication work?
168
+------------------------------
169
+
170
+There are two main deployment topologies we need to consider: Kubernetes
171
+deployed by an OpenStack tenant (Magnum-style, though not necessarily using
172
+Magnum) and accessing resources in that tenant's project in the local cloud, or
173
+accessing resources in some remote OpenStack cloud.
174
+
175
+We also need to take into account that in the second case, the Kubernetes
176
+cluster may 'belong' to a single cloud tenant (as in the first case) or may be
177
+shared by applications that each need to authenticate to different OpenStack
178
+tenants. (Kubernetes has traditionally assumed the former, but I expect it to
179
+move in the direction of allowing the latter, and it's already fairly common
180
+for OpenShift deployments.)
181
+
182
+The way e.g. the `AWS`_ broker works is that you can either use the credentials
183
+provisioned to the VM that k8s is installed on (a 'Role' in AWS parlance - note
184
+that this is completely different to a Keystone Role), or supply credentials to
185
+authenticate to AWS remotely.
186
+
187
+OpenStack doesn't yet support per-instance credentials, although we're working
188
+on it. (One thing to keep in mind is that ideally we'll want a way to provide
189
+different permissions to the service broker and cloud-provider-openstack.) An
190
+option in the meantime might be to provide a way to set up credentials as part
191
+of the k8s installation. We'd also need to have a way to specify credentials
192
+manually. Unlike for proprietary clouds, the credentials also need to include
193
+the Keystone auth_url. We should try to reuse openstacksdk's
194
+`clouds.yaml/secure.yaml format`_ if possible.
195
+
196
+The OpenShift Ansible Broker works by starting up an Ansible container on k8s
197
+to run a playbook from the bundle, so presumably credentials can be passed as
198
+regular k8s secrets.
199
+
200
+In all cases we'll want to encourage users to authenticate using Keystone
201
+`Application Credentials`_.
202
+
203
+How would network integration work?
204
+-----------------------------------
205
+
206
+`Kuryr`_ allows us to connect application containers in Kubernetes to Neutron
207
+networks in OpenStack. It would be desirable if, when the user requests a VM or
208
+bare-metal server through the service broker, it were possible to choose
209
+between attaching to the same network as Kubernetes pods, or to a different
210
+network.
211
+
212
+
213
+.. _Open Service Broker API: https://www.openservicebrokerapi.org/
214
+.. _Service Catalog extension: https://kubernetes.io/docs/concepts/service-catalog/
215
+.. _AWS: https://github.com/awslabs/aws-servicebroker#aws-service-broker
216
+.. _Azure: https://github.com/Azure/open-service-broker-azure#open-service-broker-for-azure
217
+.. _GCP: https://github.com/GoogleCloudPlatform/gcp-service-broker#cloud-foundry-service-broker-for-google-cloud-platform
218
+.. _Cloud Controller: https://github.com/kubernetes/community/blob/master/keps/0002-controller-manager.md#remove-cloud-provider-code-from-kubernetes-core
219
+.. _cloud-provider-openstack: https://github.com/kubernetes/cloud-provider-openstack#openstack-cloud-controller-manager
220
+.. _Automation Broker: http://automationbroker.io/
221
+.. _write Ansible playbooks instead: https://docs.openshift.org/latest/apb_devel/index.html
222
+.. _clouds.yaml/secure.yaml format: https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html#config-files
223
+.. _Application Credentials: https://docs.openstack.org/keystone/latest/user/application_credentials.html
224
+.. _Kuryr: https://docs.openstack.org/kuryr/latest/devref/goals_and_use_cases.html

Loading…
Cancel
Save