├── .gitignore ├── LICENSE ├── NOTICE ├── README.md ├── access-control.html.md.erb ├── app-log-streaming.html.md.erb ├── binding-credentials.html.md.erb ├── compatibility.html.md.erb ├── dashboard-sso.html.md.erb ├── enable-sharing.html.md.erb ├── examples.html.md.erb ├── images ├── async-service-broker-flow.png ├── managed-services.graffle ├── managed-services.png ├── route-services-fully-brokered.png ├── route-services-static-brokered.png ├── route-services-user-provided.png ├── sync-service-broker-flow.png ├── v1services.png ├── v2services-new.png └── web-ui-manage-service.png ├── index.html.md.erb ├── managing-service-brokers.html.md.erb ├── overview.html.md.erb ├── route-services.html.md.erb └── supporting-multiple-cf-instances.html.md.erb /.gitignore: -------------------------------------------------------------------------------- 1 | output 2 | final_app 3 | .bundle 4 | Gemfile.lock 5 | final_app/* 6 | cached_shas.yml 7 | **/.sass-cache/* 8 | bin 9 | vendor 10 | [#]*[#] 11 | .DS_Store 12 | .ruby-version 13 | .vscode/ -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2015-Present CloudFoundry.org Foundation, Inc. All Rights Reserved. 2 | 3 | Copyright (c) 2012-2015 Pivotal Software, Inc. All Rights Reserved. 4 | 5 | Licensed under the Apache License, Version 2.0 (the "License"); 6 | you may not use this file except in compliance with the License. 7 | You may obtain a copy of the License at 8 | 9 | http://www.apache.org/licenses/LICENSE-2.0 10 | 11 | Unless required by applicable law or agreed to in writing, software 12 | distributed under the License is distributed on an "AS IS" BASIS, 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | See the License for the specific language governing permissions and 15 | limitations under the License. 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Extending Cloud Foundry 2 | 3 | This guide explains how to extend a Cloud Foundry instance with user-supplied services. 4 | 5 | This repo is one of several doc repositories that go into a complete documentation set. 6 | 7 | The contents here are structured as a topic repository intended to be 8 | compiled into a larger document with 9 | [Bookbinder](https://github.com/pivotal-cf/bookbinder). 10 | 11 | See the [docs-book-cloudfoundry](http://github.com/cloudfoundry/docs-book-cloudfoundry) 12 | repo for the complete list of open source documentation repositories, as well as 13 | information about the publishing process. 14 | -------------------------------------------------------------------------------- /access-control.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Managing access to Service Plans 3 | owner: Core Services 4 | --- 5 | 6 | 7 | 8 | All new service plans from standard brokers are private by default. When you add a new broker, or when you add a new 9 | plan to an existing broker's catalog, service plans do not immediately become available. This is an admin control which service plans are available to you, and manage limited service availability. 10 | 11 | Space scoped brokers are registered to a specific space, and all users within that space can access the broker's service plans. With space-scoped brokers, service visibility is not managed separately. 12 | 13 | ## Prerequisites 14 | - CLI v6.4.0 15 | - Cloud Controller API v2.9.0 (cf-release v179) 16 | - Admin user access; the following commands can be run only by an admin user 17 | 18 | ## Service Plan access 19 | 20 | The `service-access` CLI command allows an admin to see the current access control setting for every service plan in the marketplace, across all service brokers. 21 | 22 | 
 23 | $ cf service-access
 24 | getting service access as admin...
 25 | broker: elasticsearch-broker
 26 |    service        plan     access    orgs
 27 |    elasticsearch  standard limited
 28 | 
 29 | broker: p-mysql
 30 |    service   plan        access   orgs
 31 |    p-mysql   100mb-dev   all
 32 |
33 | 34 | The `access` column shows values `all`, `limited`, or `none`, defined as follows: 35 | 36 | * `all` - The service plan is available to all users, or _public_. 37 | * `none` - No one can use the service plan; it is _private_. 38 | * `limited` - The plan is available only to users within the orgs listed. 39 | 40 | The `-b`, `-e`, and `-o` flags let you filter by broker, service, and org. 41 | 42 | 
 43 | $ cf help service-access
 44 | NAME:
 45 |    service-access - List service access settings
 46 | 
 47 | USAGE:
 48 |    cf service-access [-b BROKER] [-e SERVICE] [-o ORG]
 49 | 
 50 | OPTIONS:
 51 |    -b     access for plans of a particular broker
 52 |    -e     access for plans of a particular service offering
 53 |    -o     plans accessible by a particular org
 54 |
55 | 56 | ## Enabling access to Service Plans 57 | 58 | Admins use the `cf enable-service-access` command to give users access to service plans. The command grants access at the org level or across all orgs. 59 | 60 | When an org has access to a plan, its users see the plan in the services marketplace (`cf marketplace`) and its Space Developer users can provision instances of the plan in their spaces. 61 | 62 | #### Enabling access to a subset of users 63 | 64 | The `-p` and `-o` flags to `cf enable-service-access` let the admin limit user access to specific service plans or orgs as follows: 65 | 66 | - `-p PLAN` grants all users access to one service plan (access:`all`) 67 | - `-o ORG` grants users in a specified org access to all plans (access: `limited`) 68 | - `-p PLAN -o ORG` grants users in one org access to one plan (access: `limited`) 69 | 70 | For example, the following command grants the org dev-user-org access to the p-mysql service. 71 | 72 | 
 73 | $ cf enable-service-access p-mysql -o dev-user-org
 74 | Enabling access to all plans of service p-mysql for the org dev-user-org as admin...
 75 | OK
 76 | 
 77 | $ cf service-access
 78 | getting service access as admin...
 79 | broker: p-mysql
 80 |    service   plan        access   orgs
 81 |    p-mysql                        dev-user-org
 82 |
83 | 84 | Run `cf help enable-service-access` to review these options from the command line. 85 | 86 | 87 | Running `cf enable-service-access SERVICE-NAME` without any flags lets all users access every plan carried by the service. For example, the following command grants all-user access to all `p-mysql` service plans: 88 | 89 | 
 90 | $ cf enable-service-access p-mysql
 91 | Enabling access to all plans of service p-mysql for all orgs as admin...
 92 | OK
 93 | 
 94 | $ cf service-access
 95 | getting service access as admin...
 96 | broker: p-mysql
 97 |    service   plan        access   orgs
 98 |    p-mysql   100mb-dev   all
 99 |
100 | 101 |

When multiple brokers provide two or more services with the same name, you must specify the broker by including the -b BROKER flag in the cf enable-service-access command.

102 | 103 | 104 | ## Deactivating access to Service Plans 105 | 106 | Admins use the `cf disable-service-access` command to deactivate user access to service plans. The command denies access at the org level or across all orgs. 107 | 108 | #### Deactivating access to all plans for all users 109 | 110 | When you run `cf disable-service-access SERVICE-NAME` without any flags, it deactivates all user access to all plans carried by the service. For example, the following command denies any user access to all `p-mysql` service plans: 111 | 112 | 
113 | $ cf disable-service-access p-mysql
114 | Disabling access to all plans of service p-mysql for all orgs as admin...
115 | OK
116 | 
117 | $ cf service-access
118 | getting service access as admin...
119 | broker: p-mysql
120 |    service    plan        access   orgs
121 |    p-mysql    100mb-dev   none
122 |
123 | 124 | #### Deactivating access for specific orgs or plans 125 | 126 | The `-p` and `-o` flags to `cf disable-service-access` allow the admin to deny access to specific service plans or orgs as follows: 127 | 128 | - `-p PLAN` Deactivates user access to one service plan. 129 | - `-o ORG` Deactivates access to all plans for users in a specified org. 130 | - `-p PLAN -o ORG` Prevents users in one org from accessing one plan. 131 | 132 | Run `cf help disable-service-access` to review these options from the command line. 133 | 134 |

When multiple brokers provide two or more services with the same name, you must specify the broker by including the -b BROKER flag in the cf disable-service-access command.

135 | 136 | ### Limitations 137 | 138 | - You cannot deactivate access to a service plan for an org if the plan is currently available to all orgs. You must deactivate access for all orgs and activate access for a particular org. 139 | -------------------------------------------------------------------------------- /app-log-streaming.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: App Log streaming 3 | owner: Core Services 4 | --- 5 | 6 | 7 | 8 | When you bind an application to an instance of an applicable service, Cloud Foundry streams logs for the 9 | bound application to the service instance. 10 | 11 | - Logs for all apps bound to a log-consuming service instance are streamed to that instance. 12 | - Logs for an app bound to multiple log-consuming service instances are streamed to all instances. 13 | 14 | To activate this capability, a service broker must implement the following: 15 | 16 | 1. In the [catalog](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#catalog-management) endpoint, the broker must include `requires: syslog_drain`. This minor security measure validates that a service returning a `syslog_drain_url` in response to the [bind](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#binding) operation has also declared that it expects log streaming. 17 | If the broker does not include `requires: syslog_drain`, and the bind request returns a value for `syslog_drain_url`, 18 | <%= vars.app_runtime_abbr %> returns an error for the bind operation. 19 | 20 | 2. In response to a [bind](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#binding) request, the broker returns a value for `syslog_drain_url`. The syslog URL has a scheme of syslog, syslog-tls, or https and can include a port number. For example: 21 | 22 | `"syslog_drain_url": "syslog://logs.example.com:1234"` 23 | 24 | ## How does it work? 25 | 26 | 1. Service broker returns a value for `syslog_drain_url` in response to bind. 27 | 1. Loggregator periodically polls an internal Cloud Controller endpoint for updates. 28 | 1. Upon discovering a new `syslog_drain_url`, Loggregator identifies the associated app. 29 | 1. Loggregator streams app logs for that app to the locations specified by the service instances' `syslog_drain_url`s. 30 | 31 | You can manually configure app logs to be streamed to a location of your choice 32 | using user-provided service instances. 33 | 34 | For details, see 35 | <% if vars.guide_name == 'Tile Developer' %> 36 | [Streaming app logs to log management services](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/<%= vars.current_major_tas_version %>/tas-for-vms/services-log-management.html). 37 | <% else %> 38 | [Streaming app logs to log management services](../devguide/services/log-management.html). 39 | <% end %> 40 | -------------------------------------------------------------------------------- /binding-credentials.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Binding credentials 3 | owner: Core Services 4 | --- 5 | 6 | A bindable service returns credentials that an application can consume in response to the `cf bind` API call. 7 | Cloud Foundry writes these credentials to the 8 | <% if vars.guide_name == 'Tile Developer' %> 9 | [`VCAP_SERVICES`](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/<%= vars.current_major_version %>/tas-for-vms/deploy-apps-environment-variable.html) environment variable. 10 | <% else %> 11 | [`VCAP_SERVICES`](../devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable. 12 | <% end %> 13 | In some cases, buildpacks can write a subset of these credentials to other 14 | environment variables that frameworks might need. 15 | 16 | Choose from the following list of credential fields, if possible, although you can provide additional fields as 17 | needed. 18 | Refer to the 19 | <% if vars.guide_name == 'Tile Developer' %> 20 | [Using Bound Services](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/<%= vars.current_major_version %>/tas-for-vms/services-managing-services.html) 21 | <% else %> 22 | [Using Bound Services](../devguide/services/managing-services.html#use) 23 | <% end %> 24 | section of the _Managing Service Instances with the CLI_ topic for information about how these 25 | credentials are consumed. 26 | 27 | If you provide a service that supports a connection string, provide the uri key for 28 | buildpacks and application libraries to use. 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 |
CredentialsDescription
uriConnection string of the form DB-TYPE://USERNAME:PASSWORD@HOSTNAME:PORT/NAME, 41 | where DB-TYPE is a type of database such as mysql, postgres, mongodb, or amqp.
hostnameFQDN of the server host
portPort of the server host
nameName of the service instance
vhostName of the messaging server virtual host - a replacement for a name specific to AMQP providers
usernameServer user
passwordServer password
69 | 70 | The following is an example output of `ENV['VCAP_SERVICES']`. 71 | 72 | Depending on the types of databases you are using, each database might return different 73 | credentials. 74 | 75 | ``` 76 | VCAP_SERVICES= 77 | { 78 | cleardb: [ 79 | { 80 | name: "cleardb-1", 81 | label: "cleardb", 82 | plan: "spark", 83 | credentials: { 84 | name: "ad_c6f4446532610ab", 85 | hostname: "us-cdbr-east-03.cleardb.com", 86 | port: "3306", 87 | username: "b5d435f40dd2b2", 88 | password: "ebfc00ac", 89 | uri: "mysql://b5d435f40dd2b2:ebfc00ac@us-cdbr-east-03.cleardb.com:3306/ad_c6f4446532610ab", 90 | jdbcUrl: "jdbc:mysql://b5d435f40dd2b2:ebfc00ac@us-cdbr-east-03.cleardb.com:3306/ad_c6f4446532610ab" 91 | } 92 | } 93 | ], 94 | cloudamqp: [ 95 | { 96 | name: "cloudamqp-6", 97 | label: "cloudamqp", 98 | plan: "lemur", 99 | credentials: { 100 | uri: "amqp://ksvyjmiv:IwN6dCdZmeQD4O0ZPKpu1YOaLx1he8wo@lemur.cloudamqp.com/ksvyjmiv" 101 | } 102 | } 103 | { 104 | name: "cloudamqp-9dbc6", 105 | label: "cloudamqp", 106 | plan: "lemur", 107 | credentials: { 108 | uri: "amqp://vhuklnxa:9lNFxpTuJsAdTts98vQIdKHW3MojyMyV@lemur.cloudamqp.com/vhuklnxa" 109 | } 110 | } 111 | ], 112 | rediscloud: [ 113 | { 114 | name: "rediscloud-1", 115 | label: "rediscloud", 116 | plan: "20mb", 117 | credentials: { 118 | port: "6379", 119 | host: "pub-redis-6379.us-east-1-2.3.ec2.redislabs.com", 120 | password: "1M5zd3QfWi9nUyya" 121 | } 122 | }, 123 | ], 124 | } 125 | ``` 126 | -------------------------------------------------------------------------------- /compatibility.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cloud Foundry API and CLI compatibility 3 | owner: Services Enablement 4 | --- 5 | 6 | 7 | 8 | This topic tells you about what versions of the Cloud Foundry API and CLI support each version of the 9 | Service Broker API. 10 | 11 | 12 | ## v2.11 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 |
cf-releasev250
Cloud Controller APIv2.66
cf CLIv6.14.0
30 | 31 | ## v2.10 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 |
cf-releasev240
Cloud Controller APIv2.61
cf CLIv6.14.0
49 | 50 | ## v2.9 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 |
cf-releasev238
Cloud Controller APIv2.57.0
cf CLIv6.14.0
68 | 69 | 70 | ## v2.8 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 |
cf-releasev226
Cloud Controller APIv2.44.0
cf CLIv6.14.0
88 | 89 | 90 | ## v2.7 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 |
cf-releasev220
Cloud Controller APIv2.37.0
cf CLIv6.12.1
108 | 109 | 110 | ## v2.6 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 |
cf-releasev213
Cloud Controller APIv2.33.0
cf CLIv6.12.1
128 | 129 | 130 | ## v2.5 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 |
cf-releasev209
Cloud Controller APIv2.27.0
cf CLIv6.12.1
148 | 149 | 150 | ## v2.4 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 |
cf-releasev192
Cloud Controller APIv2.17.0
cf CLIv6.7.0
168 | 169 | 170 | ## v2.3 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 |
cf-releasev169
180 | 181 | 182 | ## v2.2 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 |
cf-releasev164
192 | 193 | 194 | ## v2.1 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 |
cf-releasev152
204 | 205 | 206 | ## v2.0 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 |
cf-releasev148
216 | -------------------------------------------------------------------------------- /dashboard-sso.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Dashboard Single Sign-on 3 | owner: Core Services 4 | --- 5 | 6 | Single sign-on (SSO) allows <%= vars.app_runtime_first %> you to authenticate with third party service 7 | dashboards 8 | using your <%= vars.app_runtime_abbr %> credentials. 9 | Service dashboards are web interfaces which allow you to interact with some or all of the features the 10 | service offers. 11 | SSO provides a streamlined experience that limits repeated logins and multiple accounts across managed services. 12 | Your credentials are never directly transmitted to the service because the OAuth protocol handles authentication. 13 | 14 | Dashboard SSO was introduced in [cf-release v169](https://github.com/cloudfoundry/cf-release/tree/v169) so 15 | this or a newer version is required to support the feature. 16 | 17 | ## Enabling SSO 18 | 19 | To activate the SSO feature, Cloud Controller requires a UAA client with sufficient permissions to 20 | create and delete clients for the service brokers that request them. 21 | 22 | You can configure the client by including the following snippet in the `cf-release` manifest: 23 | 24 | ``` 25 | properties: 26 | uaa: 27 | clients: 28 | cc-service-dashboards: 29 | secret: cc-broker-secret 30 | scope: openid,cloud_controller_service_permissions.read 31 | authorities: clients.read,clients.write,clients.admin 32 | authorized-grant-types: authorization_code,client_credentials 33 | ``` 34 | 35 | When this client is not present in the `cf-release manifest`, Cloud Controller cannot manage UAA clients 36 | and you receive a warning when creating or updating service brokers that advertise the `dashboard_client` 37 | properties. 38 | 39 | ## Service Broker responsibilities 40 | 41 | ### Registering the dashboard client 42 | 43 | 1. A service broker must include the `dashboard_client` line in the JSON response from 44 | its [catalog endpoint](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#catalog-management) for each service that implements this feature. A valid response appears. 45 | 46 | ``` 47 | { 48 | "services": [ 49 | { 50 | "id": "44b26033-1f54-4087-b7bc-da9652c2a539", 51 | ... 52 | "dashboard_client": { 53 | "id": "p-mysql-client", 54 | "secret": "p-mysql-secret", 55 | "redirect_uri": "http://p-mysql.example.com" 56 | } 57 | } 58 | ] 59 | } 60 | ``` 61 | 62 | The dashboard_client line is a hash containing three lines: 63 | 68 | 69 | 1. When a service broker advertises the `dashboard_client` property for any of its services is [added or updated](managing-service-brokers.html), Cloud Controller creates or update UAA clients as necessary. This client is used by the service dashboard to authenticate users. 70 | 71 | ### Dashboard URL 72 | 73 | A service broker must return a URL for `dashboard_url` in response to a [provision request](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#provisioning). Cloud Controller clients expose this URL to users. `dashboard_url` can be found in the response from Cloud Controller to create a service instance, enumerate service instances, space summary, and other endpoints. 74 | 75 | You can go to the service dashboard at the URL provided by `dashboard_url`, initiating the OAuth login flow. 76 | 77 | ## Service dashboard responsibilities 78 | 79 | ### OAuth flow 80 | 81 | When you go to the URL from `dashboard_url`, the service dashboard initiates the OAuth login flow. A summary of the flow can be found in [section 1.2 of the OAuth RFC](http://tools.ietf.org/html/rfc6749#section-1.2). OAuth expects the presence of an [Authorization Endpoint](http://tools.ietf.org/html/rfc6749#section-3.1) and a [Token Endpoint](http://tools.ietf.org/html/rfc6749#section-3.2). In <%= vars.app_runtime_abbr %>, these endpoints are provided by the UAA. Clients can discover the location of UAA from Cloud Controller's info endpoint; in the `token_endpoint` field of the response. 82 | 83 | ``` 84 | $ curl api.example.com/info 85 | {"name":"vcap","build":"2222","support":"http://support.example.com","version 86 | ":2,"description":"Cloud Foundry sponsored by Example Company","authorization_endpoint": 87 | "https://login.example.com","token_endpoint":"https://uaa.example.com", 88 | "allow_debug":true} 89 | ``` 90 | 91 | To activate service dashboards to support SSO for service instances created from different <%= vars.app_runtime_abbr %> instances, the `/v2/info` URL is sent to service brokers in the X-Api-Info-Location header of every API call. 92 | 93 | A service dashboard can discover this URL from the broker, which activates the dashboard 94 | to contact the appropriate UAA for a particular service instance. Although the Cloud Foundry API (CAPI) V2 is now deprecated, the Cloud Controller still communicates its `/v2/info URL` through this header. `/v2/info` is the sole CAPI V2 endpoint that continues to be served even where a Cloud Controller has been configured, through the CAPI BOSH release, to deactivate the V2 API. 95 | 96 | A service dashboard must implement the OAuth Authorization Code Grant type. See: 97 | 98 | * [UAA documentation](https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#authorization-code-grant) 99 | * [RFC documentation](http://tools.ietf.org/html/rfc6749#section-4.1) 100 | 101 | Here are the steps: 102 | 103 | 1. When you visit the service dashboard at the value of `dashboard_url`, the dashboard redirects you to a browser for the Authorization Endpoint and includes `client_id`, a `redirect_uri` (callback URL with domain matching the value of `dashboard_client.redirect_uri`), and a list of requested scopes. 104 | 105 | Scopes are permissions that are included in the token for a dashboard client that are received from UAA. Cloud Controller uses scopes to enforce access. A client must request the minimum scopes it requires. The minimum scopes required for this workflow are: 106 | `cloud_controller_service_permissions.read` and `openid`. 107 | 108 | For an explanation of the scopes available to dashboard clients, see [On Scopes](#on-scopes). 109 | 110 | 2. You are authenticated by UAA and redirected to the Login Server, where you approve or deny the scopes requested by the service dashboard. You are presented with a description for permissions that represent each scope. After authentication, your browser is redirected back to the Authorization endpoint on UAA with an authentication cookie for the UAA. 111 | 112 | 3. Assuming you grant access, UAA redirects your browser back to the value of `redirect_uri` that the dashboard provided in the request for the Authorization Endpoint. The `Location` header in the response includes an authorization code: 113 | 114 | ```console 115 | HTTP/1.1 302 Found 116 | Location: https://p-mysql.example.com/manage/auth?code=F45jH 117 | ``` 118 | 119 | 4. The dashboard UI then requests an access token from the Token Endpoint by including the authorization code that you received in the previous step. When you make the request, the dashboard must authenticate with UAA by passing the client `id` and `secret` lines in a basic auth header. UAA verifies that the client ID matches the client that issued the code. The dashboard also includes the `redirect_uri` used to obtain the authorization code for verification. 120 | 121 | 5. UAA authenticates the dashboard client, validates the authorization code, and makes sure that the redirect URI that was received matches the URI used to redirect the client. If valid, UAA responds back with an access token and a refresh token. 122 | 123 | ### Checking user permissions 124 | 125 | UAA is responsible for your authentication and provides the service with an access token with the requested permissions. However, after you have been logged in, it is the responsibility of the service dashboard to verify that you make the request to manage an instance and have access to that service instance. 126 | 127 | The service uses a GET to the `/v3/service_instances/:guid/permissions` endpoint on the Cloud Controller. The request must include a token for an authenticated user and the service instance GUID. The token is the same one obtained from the UAA in response to a request to the Token Endpoint described earlier. 128 | 129 | #### Request example 130 | 131 | ```json 132 | curl -H 'Content-Type: application/json' \ 133 | -H 'Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoid' \ 134 | http://api.cloudfoundry.com/v3/service_instances/44b26033-1f54-4087-b7bc-da9652c2a539/permissions 135 | 136 | ``` 137 | 138 | #### Response 139 | 140 | ``` 141 | { 142 | "manage": true, 143 | "read": true 144 | } 145 | ``` 146 | 147 | The response includes the following strings which indicate the various permissions for a given service instance: 148 | 149 | - `manage`: if `true`, you have sufficient permissions to make changes and update the service instance. `false` indicates insufficient permissions. 150 | - `read`: if `true`, you have permission to access read-only diagnostic and monitoring information for a given service instance. For example, permission to view a read-only dashboard. `false` indicates insufficient permissions. 151 | 152 | Since administrators might change the permissions of users at any time, the service checks this endpoint whenever a user uses the SSO flow to access the service UI. 153 | 154 | ### Scopes 155 | 156 | With scopes, you can specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond what you already have. 157 | 158 | #### Minimum scopes 159 | 160 | The following scopes are necessary to implement the integration. Dashboards might not need more permissions than to have the scopes activated. 161 | 162 | | Scope | Permissions | 163 | | ------------------------------------------------ | ------------- | 164 | | `openid` | Allows access to basic data; for example, email addresses | 165 | | `cloud_controller_service_permissions.read` | Allows access to the Cloud Controller endpoint that specifies whether you can manage a given service instance | 166 | 167 | #### Additional scopes 168 | 169 | Dashboards with extended capabilities might need to request the following additional scopes. 170 | 171 | | Scope | Permissions | 172 | | ------------------------------------------------ | ------------- | 173 | | `cloud_controller.read` | Allows read access to all resources you are authorized to read | 174 | | `cloud_controller.write` | Allows write access to all resources you are authorized to update / create / delete | 175 | 176 | ## Reference implementation 177 | 178 | The [MySQL Service Broker](https://github.com/cloudfoundry/cf-mysql-broker) is an example of a broker that implements a SSO dashboard. 179 | 180 | The login flow is implemented using the [OmniAuth library](https://github.com/intridea/omniauth) and a custom [UAA OmniAuth Strategy](https://github.com/cloudfoundry/omniauth-uaa-oauth2). 181 | 182 | See the [OmniAuth wiki page](https://github.com/intridea/omniauth/wiki/Strategy-Contribution-Guide) for instructions on how to create your own strategy. 183 | 184 | The UAA OmniAuth strategy is used to get an authorization code. 185 | 186 | For more information on authorization codes, see [this section](https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#authorization-code-grant) of the UAA documentation. 187 | 188 | You are redirected back to the service (as specified by the `callback_path` option or the default `auth/cloudfoundry/callback` path) with the authorization code. Before the application action is dispatched, the OmniAuth strategy uses the authorization code to [get a token](https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#client-obtains-token-post-oauth-token) and uses the token to request information from UAA to fill the `omniauth.auth` environment variable. When OmniAuth returns control to the application, the `omniauth.auth` environment variable hash is filled with the token and user information obtained from UAA. 189 | 190 | For more information, see [Auth Controller](https://github.com/cloudfoundry/cf-mysql-broker/blob/master/app/controllers/manage/auth_controller.rb). 191 | 192 | ## Restrictions 193 | 194 | * UAA clients are scoped to services. There must be a `dashboard_client` entry for each service that uses SSO integration. 195 | * Each `dashboard_client id` must be unique across the <%= vars.app_runtime_abbr %> deployment. 196 | 197 | ## Resources 198 | 199 | * [OAuth](http://oauth.net/2/) 200 | * [Example broker with SSO implementation (MySQL)](https://github.com/cloudfoundry/cf-mysql-broker) 201 | * [Cloud Controller API docs](https://v3-apidocs.cloudfoundry.org/version/3.147.0/#introduction) 202 | * [User Account and Authentication (UAA) Service APIs](https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst) 203 | -------------------------------------------------------------------------------- /enable-sharing.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Service Instance sharing 3 | owner: Core Services 4 | --- 5 | 6 | You can allow instances of your services to be shared across spaces and orgs within Cloud Foundry. 7 | This allows apps running in different spaces and orgs to use the same service instance. 8 | 9 | If you have Space Developer permissions in the space where the service instance was created, you are responsible 10 | for sharing, unsharing, updating, and deleting the service instance. 11 | 12 | For more information about the developer and administrator tasks related to service instance sharing, see 13 | <% if vars.guide_name == 'Tile Developer' %> 14 | [Sharing Service Instances](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/<%= vars.current_major_tas_version %>/tas-for-vms/services-sharing-instances.html). 15 | <% else %> 16 | [Sharing Service Instances](../devguide/services/sharing-instances.html). 17 | <% end %> 18 | 19 | ## Enabling service instance sharing 20 | 21 | Service brokers must explicitly activate service instance sharing by setting a flag in their service-level 22 | metadata object. 23 | This allows service instances of any service plan to be shared across orgs and spaces. 24 | The `"shareable"` flag must be set to `true` in the service-level metadata to activate service 25 | instance sharing. If the flag is set to `false` or is absent, sharing is deactivated. 26 | 27 | An example catalog: 28 | 29 | ``` 30 | { 31 | "services":[{ 32 | "id":"766fa866-a950-4b12-adff-c11fa4cf8fdc", 33 | "name": "example-service", 34 | "metadata": { 35 | "shareable": true 36 | } 37 | }] 38 | } 39 | ``` 40 | 41 | ## Binding permissions based on instance sharing 42 | 43 | When a service instance is created in one space and shared into another, you can bind your apps to the 44 | service instance from both spaces. 45 | 46 | You might want to have the service broker return credentials with different permissions depending on 47 | which space an app is bound from. 48 | For example, a messaging service can permit writes from the originating space and only reads 49 | from any spaces that the service is shared into. 50 | 51 | To determine whether the space of the app is the same as the originating space of the service instance, 52 | the service broker can compare the `context.space_guid` and `bind_resource.space_guid` fields in the binding request. 53 | The `context.space_guid` field represents the space where the service instance was created, 54 | and `bind_resource.space_guid` represents the space of the app involved in the binding. 55 | 56 | ## Security considerations 57 | 58 | You must consider the following before enabling service instance sharing: 59 | 60 | <% if vars.guide_name == 'Tile Developer' %> 61 | * [Service keys](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/<%= vars.current_major_tas_version %>/tas-for-vms/services-service-keys.html) 62 | <% else %> 63 | * [Service keys](../devguide/services/service-keys.html) 64 | <% end %> 65 | can only be generated if you have access to the space where the service instance was created. 66 | This verifies that only developers with access to this space have visibility 67 | into where and how many times the service instance is used. It is not possible 68 | to distinguish between service keys created when targeting the originating space 69 | and those created when targeting the space where the instance has been shared to. 70 | Also, unsharing an instance from a space does not delete any service keys. 71 | 72 | * Consider the impact of giving out excessive permissions for service bindings, 73 | especially bindings that originate from spaces that the service instance has 74 | been shared into. For example, a messaging service can permit writes from the 75 | originating space and only reads from any shared spaces. 76 | For more information, 77 | see [Binding Permissions Based on Instance Sharing](#binding-permissions). 78 | 79 | * You can generate unique credentials for each binding. This ensures that 80 | developers can unshare a service instance at any time. Unsharing an instance 81 | deletes any service bindings and revokes access for those credentials. 82 | Unsharing an instance prevents unauthorized 83 | future access from developers and apps that saved the credentials that they were 84 | previously provided using the service binding. 85 | 86 | * Consider the impact of a service instance dashboard being accessed by users 87 | of shared service instances. If authenticating through SSO, 88 | see [Dashboard Single Sign-On](./dashboard-sso.html). 89 | -------------------------------------------------------------------------------- /examples.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Service Broker examples 3 | owner: Core Services 4 | --- 5 | 6 | 7 | The following example service broker applications have been developed in Cloud Foundry. This is a 8 | good starting point 9 | if you are developing your own service broker. 10 | 11 | ## Ruby 12 | 13 | * [GitHub Repository service](https://github.com/cloudfoundry-samples/github-service-broker-ruby) - this is designed to be an easy-to-read example of a service broker, with complete documentation, and comes with a demo app that uses the service. The broker can be deployed as an application to any Cloud Foundry instance or hosted elsewhere. The service broker uses GitHub as the service back end. 14 | * [MySQL database service](https://github.com/cloudfoundry/cf-mysql-release) - this broker and its accompanying MySQL server are designed to be deployed together as a [BOSH](https://github.com/cloudfoundry/bosh) release. BOSH is used to deploy or upgrade the release, monitors the health of running components, and restarts or recreates unhealthy VMs. The broker code alone can be found [here](https://github.com/cloudfoundry/cf-mysql-broker). 15 | 16 | ## Java 17 | 18 | * [Spring Cloud - Cloud Foundry Service Broker](https://github.com/spring-cloud/spring-cloud-cloudfoundry-service-broker) - This implements the REST contract for service brokers and the artifacts are published to the Spring Maven repository. This greatly simplifies development: include a single dependency in Gradle, implement interfaces, and configure. A sample implementation has been provided for [MongoDB](https://github.com/spring-cloud-samples/cloudfoundry-service-broker). 19 | * [MySQL Java Broker](https://github.com/cloudfoundry-community/cf-mysql-java-broker) - a Java port of the Ruby-based [MySQL broker](https://github.com/cloudfoundry/cf-mysql-broker). 20 | 21 | ## Go 22 | 23 | * [Asynchronous Service Broker for AWS EC2](https://github.com/cloudfoundry-samples/go_service_broker) - This broker implements support for [Asynchronous Service Operations](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#asynchronous-operations), and calls AWS APIs to provision EC2 VMs. 24 | -------------------------------------------------------------------------------- /images/async-service-broker-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/async-service-broker-flow.png -------------------------------------------------------------------------------- /images/managed-services.graffle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/managed-services.graffle -------------------------------------------------------------------------------- /images/managed-services.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/managed-services.png -------------------------------------------------------------------------------- /images/route-services-fully-brokered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/route-services-fully-brokered.png -------------------------------------------------------------------------------- /images/route-services-static-brokered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/route-services-static-brokered.png -------------------------------------------------------------------------------- /images/route-services-user-provided.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/route-services-user-provided.png -------------------------------------------------------------------------------- /images/sync-service-broker-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/sync-service-broker-flow.png -------------------------------------------------------------------------------- /images/v1services.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/v1services.png -------------------------------------------------------------------------------- /images/v2services-new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/v2services-new.png -------------------------------------------------------------------------------- /images/web-ui-manage-service.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloudfoundry/docs-services/67a31ca4faa008b224827c44ea654421d6d9ae1f/images/web-ui-manage-service.png -------------------------------------------------------------------------------- /index.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Creating managed services in Cloud Foundry 3 | description: Any type of add on that can be provisioned alongside your app. For example, a database or an account on a third party SaaS provider. 4 | owner: Core Services 5 | --- 6 | 7 | 8 | Managed Services are defined as having been integrated 9 | with <%= vars.app_runtime_first %> through APIs, and allow you to provision reserved resources and credentials on demand. For documentation targeted at end users, such as how to provision services and integrate them with apps, see [Services](overview.html). This section is intended for developers and operators interested in creating Managed Services for <%= vars.app_runtime_first %>. 10 | 11 | To develop Managed Services for <%= vars.app_runtime_abbr %>, you need a <%= vars.app_runtime_abbr %> instance to allow testing your service broker as you are developing it. You must have admin access to your <%= vars.app_runtime_abbr %> instance to manage service brokers and the services marketplace catalog. For local development, <%= vars.recommended_by %> recommends using the [BOSH guide](https://bosh.io/docs/quick-start/) to deploy your own local instance of <%= vars.app_runtime_abbr %> using VirtualBox. 12 | 13 | <%= vars.tiledev_link %> 14 | 15 | ## Table of Contents 16 | 17 | * [Services](overview.html) 18 | 19 | * **Service Broker API** 20 | 21 | * [Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker/blob/v2.15/spec.md) 22 | 23 | * [Platform Profiles](https://github.com/openservicebrokerapi/servicebroker/blob/v2.15/profile.md) 24 | 25 | * [Catalog Metadata](https://github.com/openservicebrokerapi/servicebroker/blob/v2.15/profile.md#service-metadata) 26 | 27 | * [Volume Services](https://github.com/openservicebrokerapi/servicebroker/blob/v2.15/spec.md#volume-mounts-object) 28 | 29 | * [Release Notes](https://github.com/openservicebrokerapi/servicebroker/blob/v2.15/release-notes.md) 30 | 31 | * [Managing Service Brokers](managing-service-brokers.html) 32 | 33 | * [Managing access to Service Plans](access-control.html) 34 | 35 | * [Dashboard Single Sign-On](dashboard-sso.html) 36 | 37 | * [Service Broker examples](examples.html) 38 | 39 | * [Binding credentials in Cloud Foundry](binding-credentials.html) 40 | 41 | * [Service Instance sharing in Cloud Foundry](enable-sharing.html) 42 | 43 | * [App Log streaming in Cloud Foundry](app-log-streaming.html) 44 | 45 | * [Offering Route Services in Cloud Foundry](route-services.html) 46 | 47 | * [Supporting multiple <%= vars.app_runtime_abbr %> Instances](supporting-multiple-cf-instances.html) 48 | -------------------------------------------------------------------------------- /managing-service-brokers.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Managing Service Brokers 3 | owner: Core Services 4 | --- 5 | 6 | This page assumes you are using cf CLI v6.16 or later. 7 | 8 | In order to run many of the commands, you must be authenticated with <%= vars.app_runtime_full %> as an admin user or 9 | as a space developer. 10 | 11 | ## Quick start 12 | 13 | Given a service broker that has implemented the [Service Broker API](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md), two steps are required to 14 | make its services available to end users in all orgs or a limited number of orgs by service plan. 15 | 16 | 1. [Registering a broker](#register-broker) 17 | 1. [Making plans public](#make-plans-public) 18 | 19 | ## Registering a broker 20 | 21 | Registering a broker causes Cloud Controller to fetch and validate the catalog 22 | from your broker, and save the catalog to the Cloud Controller database. 23 | The basic auth username and password which are provided when adding a broker are 24 | encrypted in Cloud Controller database, and used by the Cloud Controller to 25 | authenticate with the broker when making all API calls. 26 | Your service broker can validate the username and password sent in every 27 | request; otherwise, anyone could curl your broker to delete service instances. When the broker is registered with an URL having the scheme `https`, Cloud Controller makes all calls to the broker over HTTPS. 28 | 29 | As of cf-release 229, CC API 2.47.0, <%= vars.platform_name %> supports two types of brokers: _standard brokers_ and _space-scoped brokers_. A list of their differences follows: 30 | 31 | **Standard Brokers** 32 | 33 | * Publish service plans to specific orgs or all orgs in the deployment. Can also keep plans unavailable, or _private_. 34 | * Created by admins, with the command `cf create-service-broker` 35 | 
 36 |   $ cf create-service-broker mybrokername someuser somethingsecure https://mybroker.example.com
 37 |
38 | * Managed by admins 39 | * Service plans are created private. Before anyone can use them, an admin must explicitly [make them available](#make-plans-public) within an org or across all orgs. 40 | 41 | **Space-scoped brokers** 42 | 43 | * Publish service plans only to users within the space they are created. Plans are unavailable outside of this space. 44 | * Created by space developers using the command `cf create-service-broker` with the `--space-scoped` flag 45 | 
 46 |   $ cf create-service-broker mybrokername someuser somethingsecure https://mybroker.example.com --space-scoped
 47 |
48 | 49 | If a space developer runs cf create-service-broker without the --space-scoped flag, they receive an error. 50 | 51 | * Managed by space developers 52 | * Newly created plans are published to all users in their space. 53 | 54 | ### Making plans public 55 | 56 | After an admin creates a new service plan from a standard broker, no one can use it until the admin explicitly makes it available to users within a specific org or all orgs in the deployment. 57 | 58 | See the [Access Control](./access-control.html#enable-access) topic for how to make standard broker service plans available to users. 59 | 60 | ### Multiple brokers, services and plans 61 | 62 | Many service brokers can be added to a <%= vars.platform_name %> instance, each offering 63 | many services and plans. 64 | Keep the following constraints in mind: 65 | 66 | - It is not possible to have multiple brokers with the same name. 67 | - Prior to Cloud Foundry API (CAPI) v1.71, the service ID and plan IDs of each service advertised by the broker must be unique across <%= vars.platform_name %>. 68 | - With CAPI v1.71 or later, the service ID and plan IDs of each service advertised by the broker must be unique only within the broker and can overlap ids defined in other brokers. 69 | - GUIDs are recommended for the service ID and plan IDs of each service. 70 | 71 |

72 | If your deployment uses CAPI v1.71 or later, you can add multiple brokers with the same URL. In this case, the brokers must have different names. CAPI v1.70 and 73 | earlier do not support this feature.

74 | 75 | See [Possible errors](#possible-errors) for error messages and what do to 76 | when you see them. 77 | 78 | ## Listing service brokers 79 | 80 | 
 81 | $ cf service-brokers
 82 | Getting service brokers as admin...
 83 | OK
 84 | 
 85 | Name            URL
 86 | my-service-broker https://mybroker.example.com
 87 |
88 | 89 | ## Updating a broker 90 | 91 | Updating a broker is how to ingest changes a broker author has made into Cloud 92 | Foundry. 93 | Similar to adding a broker, update causes Cloud Controller to fetch the catalog 94 | from a broker, validate it, and update the Cloud Controller database with any 95 | changes found in the catalog. 96 | 97 | Update also provides a means to change the basic auth credentials cloud 98 | controller uses to authenticate with a broker, as well as the base URL of the 99 | broker's API endpoints. 100 | 101 | 
102 | $ cf update-service-broker mybrokername someuser somethingsecure https://mybroker.example.com
103 |
104 | 105 | ## Renaming a broker 106 | 107 | A service broker can be renamed with the `rename-service-broker` 108 | command. 109 | This name is used only by the <%= vars.platform_name %> operator to identify brokers, and 110 | has no relation to configuration of the broker itself. 111 | 112 | 
113 | $ cf rename-service-broker mybrokername mynewbrokername
114 |
115 | 116 | ## Removing a broker 117 | 118 | When you remove a service broker, all services and plans in the broker's catalog are removed from the <%= vars.platform_name %> Marketplace. 119 | 120 | 
121 | $ cf delete-service-broker mybrokername
122 |
123 | 124 | When you attempt to remove a service broker it can fail if there are service instances for any service plan in its catalog. When you are planning to shut down or 125 | delete a broker, make sure to remove all service instances first. Failure to do so 126 | leaves orphaned service instances in the <%= vars.platform_name %> database. If a 127 | service broker has been shut down without first deleting service instances, you can remove the instances with the CLI, see Purge a Service. 128 | 129 | ### Purging a service 130 | 131 | If a service broker has been shut down or removed without first deleting service instances from <%= vars.platform_name %>, you can be unable to remove the service broker or its services and plans from the Marketplace. In development environments, broker authors often destroy their broker deployments and need a way to clean up the Cloud Controller database. 132 | 133 | The following command deletes a service offering, all of its plans, and all associated service instances and bindings from the Cloud Controller database, without making any API calls to a service broker. Once all services for a broker have been purged, the broker can be removed normally. 134 | 135 | 
136 | $ cf purge-service-offering service-test
137 | Warning: This operation assumes that the service broker responsible for this
138 | service offering is no longer available, and all service instances have been
139 | deleted, leaving orphan records in <%= vars.platform_name %>'s database. All knowledge of
140 | the service can be removed from <%= vars.platform_name %>, including service instances and
141 | service bindings. No attempt is made to contact the service broker; running
142 | this command without destroying the service broker causes orphan service
143 | instances. After running this command you might want to run either
144 | delete-service-auth-token or delete-service-broker to complete the cleanup.
145 | 
146 | Really purge service offering service-test from <%= vars.platform_name %>? y
147 | OK
148 |
149 | 150 | ### Purging a service instance 151 | 152 | The following command deletes a single service instance, its service bindings and its service keys from the Cloud Controller database, without making any API calls to a service broker. 153 | This helps in instances when a Service Broker is not conforming to the Service Broker API and not returning a 200 or 410 to requests to delete the service instance. 154 | 155 | 
156 | $ cf purge-service-instance mysql-dev
157 | WARNING: This operation assumes that the service broker responsible for this
158 | service instance is no longer available or is not responding with a 200 or 410,
159 | and the service instance has been deleted, leaving orphan records in Cloud
160 | Foundry's database. All knowledge of the service instance is removed from
161 | <%= vars.platform_name %>, including service bindings and service keys.
162 | 
163 | Really purge service instance mysql-dev from <%= vars.platform_name %>?> y
164 | Purging service mysql-dev...
165 | OK
166 |
167 | 168 | `purge-service-instance` requires cf-release v218 and cf CLI 6.14.0. 169 | 170 | When multiple brokers provide two or more service instances with the same name, you must specify the broker by including 171 | the -b BROKER flag in the cf purge-service-instance command. 172 | 173 | ## Catalog validation behaviors 174 | 175 | When <%= vars.platform_name %> fetches a catalog from a broker, and compares the 176 | broker's id for services and plans with the `unique_id` values for services and 177 | plans in the Cloud Controller database. 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 202 | 203 | 204 | 205 |
EventAction
The catalog fails to load or validate.<%= vars.platform_name %> returns a meaningful error that the broker could not be reached or the catalog was not valid.
A service or plan in the broker catalog has an ID that is not present among the unique_id values in the marketplace database.A new record must be added to the marketplace database.
A service or plan in the marketplace database are found with a unique_id that matches the broker catalog's ID.The marketplace must update the records to match the broker's catalog.
The database has plans that are not found in the broker catalog, and there are no associated service instances.The marketplace must remove these plans from the database, and then delete services that do not have associated plans from the database. 201 |
The database has plans that are not found in the broker catalog, but there are provisioned instances.The marketplace must mark the plan inactive and no longer allow it to be provisioned.
206 | 207 | ## Possible errors 208 | 209 | If incorrect basic auth credentials are provided: 210 | 211 | 
212 | Server error, status code: 500, error code: 10001, message: Authentication
213 | failed for the service broker API.
214 | Verify that the username and password are correct:
215 |     https://github-broker.a1-app.example.com/v2/catalog
216 |
217 | 218 | If you receive the following errors, check your broker logs. 219 | You might have an internal error. 220 | 221 | 
222 | Server error, status code: 500, error code: 10001, message:
223 |     The service broker response was not understood
224 | 
225 | Server error, status code: 500, error code: 10001, message:
226 |     The service broker API returned an error from
227 |     https://github-broker.a1-app.example.com/v2/catalog: 404 Not Found
228 | 
229 | Server error, status code: 500, error code: 10001, message:
230 |     The service broker API returned an error from
231 |     https://github-broker.primo.example.com/v2/catalog: 500 Internal Server Error
232 |
233 | 234 | If your broker's catalog of services and plans violates validation of presence, 235 | uniqueness, and type, you can receive meaningful errors. 236 | 237 | 
238 | Server error, status code: 502, error code: 270012, message: Service broker catalog is invalid:
239 | Service service-name-1
240 |   service id must be unique
241 |   service description is required
242 |   service "bindable" field must be a boolean, but has value "true"
243 |   Plan plan-name-1
244 |     plan metadata must be a hash, but has value [{"bullets"=>["bullet1", "bullet2"]}]
245 |
246 | -------------------------------------------------------------------------------- /overview.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cloud Foundry Services 3 | owner: Core Services 4 | --- 5 | 6 | This topic tells you about the services in <%= vars.app_runtime_first %>. 7 | 8 | ## Services and service instances 9 | 10 | <%= vars.app_runtime_abbr %> offers a marketplace of services that operators can use to provision reserved resources on demand. 11 | Marketplace services include resources such as databases on a shared or dedicated server, or accounts on a SaaS app. 12 | These resources are known as service instances and the systems that deliver and operate these resources are known as services. 13 | 14 | For a service to be available in the Marketplace, an operator must integrate the service with <%= vars.app_runtime_abbr %> using APIs. 15 | 16 | <% if vars.guide_name == 'Tile Developer' %> 17 | For more information about provisioning service instances and other life cycle operations, see 18 | [Managing Service Instances](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-managing-services.html). 19 | 20 | <%= vars.app_runtime_abbr %> enables users to use services that are not available 21 | in the Marketplace using user-provided service instances (UPSI). 22 | For more information, see [User-Provided Service Instances](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-user-provided.html). 23 | <% else %> 24 | For more information about provisioning service instances and other life cycle operations, see 25 | [Managing Service Instances](../devguide/services/managing-services.html). 26 | 27 | <%= vars.app_runtime_abbr %> enables users to use services that are not available 28 | in the Marketplace using user provided service instances (UPSI). 29 | For more information, see [User-Provided Service Instances](../devguide/services/user-provided.html). 30 | <% end %> 31 | 32 | 33 | ## Architecture and terminology 34 | 35 | Services are integrated with <%= vars.app_runtime_abbr %> by using a documented API for which the Cloud Controller is the client, called the Service Broker API. 36 | This cannot be confused with the Cloud Controller API (CAPI), often used to refer to the version of Cloud Foundry. 37 | The Service Broker API is versioned independently of CAPI. 38 | 39 | The component of the service that uses the Service Broker API is called the _service broker_. 40 | This component was formerly referred to as a service gateway. 41 | However, as traffic between apps and services does not flow through the service broker, the term caused confusion. 42 | Although "gateway" still appears in old code, the term "broker" is used in conversation, in new code, and in documentation. 43 | 44 | Service brokers advertise a catalog of service offerings and service plans, as well as interpreting calls for provision, bind, unbind, and deprovision. 45 | What a broker does with each call can vary between services. In general, 'provision' reserves resources on a service and 'bind' delivers information to an app necessary for accessing the resource. The reserved resource is called a _service instance_. What a service instance represents can vary by service. It could be a single database on a multi-tenant server, a dedicated cluster, or even an account on a web app. 46 | 47 | ![Services interact with the Cloud Foundry. The diagram shows the following components: 'Service Broker', 'cloud controller', 'App environment', and 'service instances.](./images/managed-services.png) 48 | 49 | ## Service Instance credentials 50 | 51 | <%= vars.app_runtime_abbr %> enables users to provision credentials needed to interface with a service instance. You can use app binding to deliver these credentials to your <%= vars.app_runtime_abbr %> app. For external and local clients, you can use service keys to generate credentials to communicate directly with a service instance. 52 | 53 | 54 | ### Binding Apps 55 | 56 | Service instance credentials can be delivered to apps running on 57 | <%= vars.app_runtime_abbr %> in an environment variable. For more information, see 58 | <% if vars.guide_name == 'Tile Developer' %> 59 | [Delivering Service Credentials to an App](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-application-binding.html). 60 | <% else %> 61 | [Delivering Service Credentials to an App](../devguide/services/application-binding.html). 62 | <% end %> 63 | 64 | For information about binding to a specific app development framework, see <%= vars.buildpacks_link %>. 65 | 66 | ### Service keys 67 | 68 | Credentials managed manually are known as service keys. Use service keys when you want a set of credentials for use by clients other than the app in the same space. For instance, you can use service keys to connect to a service instance from a local client, or from an app in another space, or even from outside of <%= vars.app_runtime_abbr %>. 69 | 70 | <% if vars.guide_name == 'Tile Developer' %> 71 | For more information about creating a user-provided service instance with service keys, 72 | see [User-Provided Service Instances](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-user-provided.html). 73 | For more information about service keys, see [Managing Service Keys](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-service-keys.html). 74 | <% else %> 75 | For more information about creating a user-provided service instance with service keys, 76 | see the [User-Provided Service Instances](../devguide/services/user-provided.html) topic. 77 | For more information about service keys, see the [Managing Service Keys](../devguide/services/service-keys.html) topic. 78 | <% end %> 79 | 80 |

Not all services support service keys. Some services support credentials through app binding only.

81 | 82 | 83 | ## Implementation and deployment 84 | 85 | How a service is implemented is up to the service provider or developer. <%= vars.app_runtime_abbr %> only requires that the service provider implement the Service Broker API. A broker can be implemented as a separate app, or by adding the required HTTP endpoints to an existing service. 86 | 87 | Because <%= vars.app_runtime_abbr %> only requires that a service implements the Service Broker API to be available to <%= vars.app_runtime_abbr %> end users, many deployment models are possible. The following are examples of valid deployment models: 88 | 89 | * Entire service packaged and deployed by BOSH alongside <%= vars.app_runtime_abbr %> 90 | * Service broker packaged and deployed by BOSH alongside <%= vars.app_runtime_abbr %>, rest of the service deployed and maintained by other means 91 | * Broker (and optionally service) pushed as an app to <%= vars.app_runtime_abbr %> user space 92 | * Entire service, including broker, deployed and maintained outside of <%= vars.app_runtime_abbr %> by other means 93 | 94 | 95 | ## Communication between Apps and Service Instances 96 | 97 | To allow an app to communicate with a service external to <%= vars.app_runtime_abbr %>, you might need to configure the service to accept connections from your app based on its outbound IP address. 98 | 99 | In your external service configuration, you must do one of the following: 100 | 101 | * Add the entire IP address range for the Diego Cell where the app is deployed to your allow list. 102 | * Derive the app IP address from its DNS name using a command-line tool such as `dig`, `host`, or `nslookup`. In your external service configuration, add the IP address or range of the app instance to your allow list. 103 | 104 | 105 | ## Streaming App Logs to Log Management Services 106 | 107 | To learn how your app logs can be streamed to third-party log management services, see 108 | <% if vars.guide_name == 'Tile Developer' %> 109 | [Streaming App Logs to Log Management Services](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-log-management.html). 110 | <% else %> 111 | [Streaming App Logs to Log Management Services](../devguide/services/log-management.html). 112 | <% end %> 113 | 114 | User provided service instances can be used to drain app logs to a service not available in the Marketplace. 115 | This is also known as setting up a syslog drain. 116 | For guidance on configuring some third party log management services, see 117 | <% if vars.guide_name == 'Tile Developer' %> 118 | [Service-Specific Instructions for Streaming App Logs](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-log-management-thirdparty-svc.html). 119 | <% else %> 120 | [Service-Specific Instructions for Streaming App Logs](../devguide/services/log-management-thirdparty-svc.html). 121 | <% end %> 122 | 123 | 124 | ## Managing App Requests with Route Services 125 | 126 | To learn how Marketplace services (and user-provided service instances) can be 127 | used to perform preprocessing on app requests, see 128 | <% if vars.guide_name == 'Tile Developer' %> 129 | [Managing App Requests with Route Services](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/services-route-binding.html). 130 | <% else %> 131 | [Managing App Requests with Route Services](../devguide/services/route-binding.html). 132 | <% end %> 133 | 134 | ## Migrating a Database Schema 135 | 136 | If your app relies on a relational database, you must apply schema changes periodically. To perform database schema migrations on <%= vars.app_runtime_abbr %>-managed services, run a database migration task with the <%= vars.app_runtime_abbr %> Command Line Interface (cf CLI) tool. 137 | 138 | For more information about running cf CLI tasks, see 139 | <% if vars.guide_name == 'Tile Developer' %> 140 | [Running Tasks](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/using-tasks.html). 141 | <% else %> 142 | [Running Tasks](../devguide/using-tasks.html). 143 | <% end %> 144 | 145 |

To run tasks with the cf CLI, you must install cf CLI v6.23.0 or later. For information about downloading, installing, and uninstalling 146 | the cf CLI, see <%= vars.cli_install_link %>.

147 | 148 | To run a database schema migration with the cf CLI: 149 | 150 | 1. Push the app: 151 | 152 | 
$ cf push APP-NAME
153 | 154 | Where `APP-NAME` is the name of the app. 155 | 156 |

To run a task without starting the app, you can push the app with cf push -i 0 and then run the task. You can run the app later 157 | by scaling up the instance count.

158 | 159 | 1. Run database schema migration as a task on the app: 160 | 161 | 
162 |     $ cf run-task APP-NAME --command "bin/rails db:migrate" --name TASK-NAME
163 |     Creating task for app APP-NAME in org jdoe-org / space development as jdoe@pivotal.io...
164 |     OK
165 |     Task 1 has been submitted and ran successfully.
166 |
167 | 168 | Where: 169 | 173 | -------------------------------------------------------------------------------- /route-services.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Offering route services 3 | owner: Core Services 4 | --- 5 | 6 | You can offer a service to a <%= vars.app_runtime_full %> (<%= vars.app_runtime_abbr %>) services 7 | Marketplace. 8 | 9 | For information about consuming these services, see 10 | <% if vars.guide_name == 'Tile Developer' %> 11 | [Managing apps and services using Apps Manager](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/6.0/tas-for-vms/manage-apps.html). 12 | <% else %> 13 | [Managing App Requests with Route Services](../devguide/services/route-binding.html). 14 | <% end %> 15 | 16 | <% if vars.platform_code == 'CF' %> 17 |

Route services require Diego. Your deployment must use the Diego architecture or you must enable Diego for your app. 18 |

19 | <% end %> 20 | 21 | <%= vars.app_runtime_abbr %> app developers might want to apply 22 | transformation or processing to requests before they reach an 23 | app. Common use cases include authentication, rate 24 | limiting, and caching services. 25 | 26 | Route services are a kind of 27 | Marketplace service that you can use to apply various 28 | transformations to app requests by binding an app's route to a service 29 | instance. Through integrations with service brokers and, optionally, 30 | with the <%= vars.app_runtime_abbr %> routing tier, providers can 31 | offer these services with a familiar, automated, 32 | self-service, and on-demand user experience. 33 | 34 | <% if vars.platform_code != 'CF' && vars.guide_name == 'Tile Developer' %> 35 |

The procedures in this topic use the Cloud Foundry Command Line Interface (cf CLI). 36 | You can also manage route services using Apps Manager. 37 | For more information, see the 38 | Route Services 39 | section of the Managing Apps and Service Instances using Apps Manager topic. 40 |

41 | <% end %> 42 | 43 | <% if vars.platform_code != 'CF' && vars.guide_name != 'Tile Developer' %> 44 |

The procedures in this topic use the Cloud Foundry Command Line Interface (cf CLI). 45 | You can also manage route services using Apps Manager. 46 | For more information, see the 47 | Manage Route Services 48 | section of the Managing Apps and Service Instances Using Apps Manager topic. 49 |

50 | <% end %> 51 | 52 | ## Architecture 53 | 54 | <%= vars.app_runtime_abbr %> supports the following models for 55 | route services, each of which is described in this topic: 56 | 57 | * [Fully-brokered services](#fully-brokered) 58 | * [Static, brokered services](#static-brokered) 59 | * [User-provided services](#user-provided) 60 | 61 | In each model, you configure a route service to process traffic 62 | addressed to an app. 63 | 64 | ### Fully-brokered service 65 | 66 | In the fully-brokered service model, the <%= vars.app_runtime_abbr %> 67 | router receives all traffic to apps in the deployment before any 68 | processing by the route service. You can bind a route service 69 | to any app, and if an app is bound to a route service, the <%= vars.app_runtime_abbr %> router sends 70 | the traffic to the 71 | service. After the route service processes requests, it sends it 72 | back to the load balancer in front of the <%= vars.app_runtime_abbr %> 73 | router. The second time through, the <%= vars.app_runtime_abbr %> 74 | router recognizes that the route service has already handled them, and 75 | forwards them directly to app instances. 76 | 77 | ![Fully brokered service model](./images/route-services-fully-brokered.png) 78 | 79 | The route service can run inside or outside of <%= vars.app_runtime_abbr %>, as long as it 80 | fulfills the [Service Instance 81 | responsibilities](#service-instance-responsibilities) to integrate it 82 | with the <%= vars.app_runtime_abbr %> router. 83 | 84 | A service broker 85 | publishes the route service to the <%= vars.app_runtime_abbr %> 86 | marketplace, and makes it available to developers. 87 | 88 | You can then 89 | create an instance of the service and bind it to your apps with the 90 | following commands: 91 | 92 | ```console 93 | cf create-service BROKER-SERVICE-PLAN SERVICE-INSTANCE 94 | 95 | cf bind-route-service YOUR-APP-DOMAIN SERVICE-INSTANCE [--hostname HOSTNAME] [--path PATH] 96 | ``` 97 | 98 | You can configure the service either through the service provider web interface or by passing 99 | <% if vars.guide_name == 'Tile Developer' %> 100 | [arbitrary parameters](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/6.0/tas-for-vms/services-managing-services.html#arbitrary-parameters) 101 | <% else %> 102 | [arbitrary parameters](../devguide/services/managing-services.html#arbitrary-params-create) 103 | <% end %> 104 | to their `cf create-service` call through the `-c` flag. 105 | 106 | **Advantages:** 107 | 108 | * Developers can use a Service Broker to dynamically configure how the 109 | route service processes traffic to specific apps. 110 | 111 | * Adding route services requires no manual infrastructure 112 | configuration. 113 | 114 | * Traffic to apps that do not use the service makes fewer network hops because requests for those apps do not pass through the route service. 115 | 116 | **Disadvantages:** 117 | 118 | * Traffic to apps that use the route service makes additional network 119 | hops, as compared to the static model. 120 | 121 | ### Static, brokered service 122 | 123 | In the static brokered service model, an operator installs a static 124 | routing service, which might be a piece of hardware, in front of the 125 | load balancer. The routing service runs outside of <%= vars.app_runtime_abbr %> and receives traffic 126 | to all apps running in 127 | the <%= vars.app_runtime_abbr %> deployment. The service provider 128 | creates a service broker to publish the service to the <%= vars.app_runtime_abbr %> marketplace. 129 | As with a fully-brokered 130 | service, you can use the service by instantiating it with `cf 131 | create-service` and binding it to an app with `cf bind-route-service`. 132 | 133 | ![Static brokered service model.](./images/route-services-static-brokered.png) 134 | 135 | In this model, you configure route services on an app-by-app 136 | basis. When you bind a service to an app, the service broker directs 137 | the routing service to process that app's traffic rather than passing the 138 | requests through unchanged. 139 | 140 | **Advantages:** 141 | 142 | * Developers can use a service broker to dynamically configure how the 143 | route service processes traffic to specific apps. 144 | 145 | * Traffic to apps that use the route service takes fewer network hops. 146 | 147 | **Disadvantages:** 148 | 149 | * Adding route services requires manual infrastructure configuration. 150 | * Traffic to apps that do not use the route service make unnecessary 151 | network hops. Requests for all apps hosted by the deployment pass 152 | through the route service component. 153 | 154 | ### User-provided service 155 | 156 | If a route service is not listed in the <%= vars.app_runtime_abbr %> 157 | marketplace by a broker, you can still bind it to your app as 158 | a user provided service. The service can run anywhere, either inside 159 | or outside of <%= vars.app_runtime_abbr %>, but it must fulfill the 160 | integration requirements described in [Service Instance responsibilities](#service-instance-responsibilities). 161 | The service also needs to be reachable by an outbound connection from the <%= vars.app_runtime_abbr %> router. 162 | 163 | ![Bound to your app as user provided service.](./images/route-services-user-provided.png) 164 | 165 | This model is identical to the fully-brokered service model, except 166 | without the broker. You can configure the service manually, outside 167 | of <%= vars.app_runtime_abbr %>. 168 | 169 | You can then create a user provided 170 | service instance and bind it to your app with the following commands,that supply the URL of their route 171 | service: 172 | 173 | ```console 174 | cf create-user-provided-service SERVICE-INSTANCE -r ROUTE-SERVICE-URL 175 | 176 | cf bind-route-service DOMAIN SERVICE-INSTANCE [--hostname HOSTNAME] 177 | ``` 178 | 179 | **Advantages:** 180 | 181 | * Adding route services requires no manual infrastructure configuration. 182 | * Traffic to apps that do not use the service makes fewer network hops 183 | because requests for those apps do not pass through the route 184 | service. 185 | 186 | **Disadvantages:** 187 | 188 | * You must manually provision and configure route services out 189 | of the context of <%= vars.app_runtime_abbr %> because no service 190 | broker automates these operations. 191 | * Traffic to apps that use the route service makes additional network 192 | hops, as compared to the static model. 193 | 194 | ### Architecture comparison 195 | 196 | The previous models require the broker and service instance 197 | responsibilities summarized in the following table: 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 |
Route Services ArchitectureFulfills <%= vars.app_runtime_abbr %>
Service Instance Responsibilities (1)		Fulfills <%= vars.app_runtime_abbr %>
Broker Responsibilities (2)
Fully-BrokeredYesYes
Static BrokeredNoYes
User-ProvidedYesNo
219 | 1 - See Service Instance Responsibilities 220 | 221 | 2 - See Broker Responsibilities 222 | 223 | 224 | ## Service instance 225 | 226 | The following information applies only when a broker returns `route_service_url` 227 | in a bind response. 228 | 229 | Binding a service instance to a route associates the 230 | `route_service_url` with the route in the <%= vars.app_runtime_abbr %> 231 | router. All requests for the route are proxied to the URL specified by 232 | `route_service_url`. 233 | 234 | The <%= vars.app_runtime_abbr %> router includes the `X-CF-Forwarded-Url` header 235 | containing the originally requested URL, as 236 | well as the `X-CF-Proxy-Signature` and `X-CF-Proxy-Metadata` headers used 237 | by the router to validate that the route-service sent the 238 | request. These headers are described in the [Headers](#headers) section. 239 | 240 | ### Service instance responsibilities 241 | 242 | The route service must handle requests by either: 243 | 244 | * Accepting the request, making a new request to the original 245 | requested URL, or to another location, and then responding to the 246 | original requestor 247 | * Rejecting the request by responding with a non-`2xx` HTTP status code 248 | 249 | When forwarding a request to the originally requested URL, the route 250 | service must forward the `X-CF-Forwarded-Url`, `X-CF-Proxy-Signature`, and 251 | `X-CF-Proxy-Metadata` headers on the request. If it doesn't, it is rejected. 252 | When forwarding a request to a location other than the originally 253 | requested URL, the route service strips these headers. 254 | 255 | ### Headers 256 | 257 | The following HTTP headers are added by the Gorouter to requests 258 | forwarded to route services. 259 | 260 | #### X-CF-Forwarded-Url 261 | 262 | The `X-CF-Forwarded-Url` header contains the originally requested 263 | URL. The route service might choose to forward the request to this URL 264 | or to another. 265 | 266 | #### X-CF-Proxy-Signature 267 | 268 | When the Gorouter receives a request with this header, it accepts 269 | and forwards the request to the app only if the URL of the request 270 | matches the one associated with the token, and the request was 271 | received on time. Otherwise, the request is rejected. 272 | 273 | `X-CF-Proxy-Signature` also signals to the Gorouter that a request has 274 | transited a route service. If this header is present, the Gorouter 275 | does not forward the request to a route service. The route service 276 | needs to forward these headers in subsequent requests to the orignal 277 | requested URL, so that it knows not to send the request back to the 278 | route service but to the app. The headers must NOT be sent in the 279 | HTTP response to the GoRouter, only in the new HTTP request to the 280 | GoRouter. 281 | 282 | CF-hosted Route Services cannot be chained: If the route service 283 | forwards the request to a URL to resolve a route for a 284 | different app on <%= vars.app_runtime_abbr %>, the route must not have 285 | a bound route service. Otherwise, the request is rejected as the 286 | requested URL does not match the one in the forwarded 287 | `X-CF-Proxy-Signature` header. 288 | 289 | >**Important** 290 | >The X-CF-Proxy-Signature header is 291 | >an access token. Anyone possessing your X-CF-Proxy-Signature 292 | >token can bypass the route service. Do not share your your X-CF-Proxy-Signature 293 | >token with anyone. 294 | 295 | #### X-CF-Proxy-Metadata 296 | 297 | The `X-CF-Proxy-Metadata` header aids in the encryption and 298 | description of `X-CF-Proxy-Signature`. 299 | 300 | ### SSL certificates 301 | 302 | When <%= vars.app_runtime_abbr %> is deployed in a development 303 | environment, certificates hosted by the load balancer are self-signed, 304 | and not signed by a trusted Certificate Authority. When the route 305 | service finishes processing an inbound request and makes a call to the 306 | value of `X-CF-Forwarded-Url`, be prepared to accept the self-signed 307 | certificate when integrating with a non-production deployment of <%= vars.app_runtime_abbr %>. 308 | 309 | ### Timeouts 310 | 311 | <% if vars.platform_code == 'CF' %> 312 | 313 | Route services must forward the 314 | request to the app route within the number of seconds configured by 315 | the `router.route_service_timeout` property (defaults to 60 seconds). 316 | 317 | In addition, all requests must respond in the number of seconds 318 | configured by the `request_timeout_in_seconds` property (defaults to 900 seconds). 319 | 320 | Timeouts are configurable for the router using the cf-release BOSH 321 | deployment manifest. For more information, see the [spec](https://github.com/cloudfoundry/routing-release/blob/master/jobs/gorouter/spec). 322 | 323 | <% else %> 324 | 325 | Route services must forward the request to the app route 326 | within 60 seconds. 327 | 328 | In addition, all requests must respond in 900 seconds. 329 | 330 | <% end %> 331 | 332 | ## Broker responsibilities 333 | 334 | ### Catalog endpoint 335 | 336 | Brokers must include `requires: ["route_forwarding"]` for a service in 337 | the catalog endpoint. If this is not present, <%= vars.app_runtime_abbr %> does not permit users to bind an instance of 338 | the service to a route. 339 | 340 | ### Binding endpoint 341 | 342 | When you bind a route to a service instance, <%= vars.app_runtime_abbr %> sends a bind request to the broker, including 343 | the route address, with `bind_resource.route`. A route is an address 344 | used by clients to reach apps mapped to the route. The broker might 345 | return `route_service_url`, containing a URL where <%= vars.app_runtime_abbr %> proxies requests for the route. This URL 346 | must have an `https` scheme, or the Cloud Controller rejects the 347 | binding. `route_service_url` is optional, and not returning this field 348 | allows a broker to dynamically configure a network component already 349 | in the request path for the route, requiring no change in the <%= vars.app_runtime_abbr %> router. 350 | 351 | For more information about bind requests, see the 352 | [Binding](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#binding) section of the _Open Service Broker API 353 | (v2.13)_ specification on GitHub. 354 | 355 | ## Route services examples 356 | 357 | * [Logging Route Service](https://github.com/cloudfoundry/cf-acceptance-tests/tree/release-candidate/assets/logging-route-service): 358 | This route service can be pushed as an app to <%= vars.app_runtime_abbr %>. It fulfills the service instance 359 | responsibilities and logs requests received and sent. It can 360 | be used to see the route service integration in action by tailing 361 | its logs. 362 | 363 | * [Rate Limiting Route Service](https://github.com/cloudfoundry-samples/ratelimit-service): 364 | This example route service is a simple <%= vars.app_runtime_abbr %> 365 | app that provides rate limiting to control the rate of traffic to an 366 | app. 367 | 368 | * [Spring Boot examples](https://github.com/in28minutes/spring-boot-examples). 369 | 370 | ## Tutorial 371 | 372 | The following instructions show how to use the Logging Route 373 | Service described in [Route Services examples](#examples) to verify that when a 374 | route service is bound to a route, requests for that route are proxied 375 | to the route service. 376 | 377 | For a video of this tutorial, see [Route Services in Pivotal Cloud 378 | Foundry 1.7](https://youtu.be/VaaZJE2E4jI) on YouTube. 379 | 380 | These commands require the Cloud Foundry Command Line Interface (cf 381 | CLI) v6.16 or later. 382 | 383 | To use the logging route service: 384 | 385 | 1. Push the logging route service as an app by running: 386 | 387 | ```console 388 | cf push logger 389 | ``` 390 | 391 | 1. Create a user provided service instance, and include the route of 392 | the logging route service you pushed as `route_service_url`. Make sure 393 | to use `https` for the scheme. 394 | 395 | Run: 396 | 397 | ```console 398 | cf create-user-provided-service mylogger -r https://logger.cf.example.com 399 | ``` 400 | 401 | 1. Push a sample app such as [Spring 402 | Music](https://github.com/cloudfoundry-samples/spring-music). By 403 | default, this creates a route `spring-music.cf.example.com`. 404 | 405 | Run: 406 | 407 | ``` 408 | cf push spring-music 409 | ``` 410 | 411 | 1. Bind the user provided service instance to the route of your sample 412 | app. The `bind-route-service` command takes a route and a service 413 | instance. 414 | 415 | The route is specified in the following example by domain 416 | `cf.example.com` and hostname `spring-music`. 417 | 418 | Run: 419 | 420 | ```console 421 | cf bind-route-service cf.example.com mylogger --hostname spring-music 422 | ``` 423 | 424 | 1. Tail the logs for your route service by running: 425 | 426 | ``` 427 | cf logs logger 428 | ``` 429 | 430 | 1. Send a request to the sample app and view in the route service logs 431 | that the request is forwarded to it by running: 432 | 433 | ```console 434 | curl spring-music.cf.example.com 435 | ``` 436 | 437 | <% if vars.platform_code == 'CF' %> 438 | 439 | ## Security considerations 440 | 441 | The contract between route services and the Gorouter, applicable for 442 | fully-brokered and user-provided models, allows a <%= vars.app_runtime_abbr %> operator to suggest 443 | whether or not requests 444 | forwarded from the route service to a load balancer are encrypted. The 445 | <%= vars.app_runtime_abbr %> operator makes this suggestion by setting 446 | the `router.route_services_recommend_https` manifest property. 447 | 448 | This suggestion does not allow the platform to guarantee that a route 449 | service obeys the scheme of the `X-Forwarded-Url` header. If a route 450 | service ignores the scheme and downgrades the request to plain text, the requester can intercept, and use, or edit the data 451 | within it. 452 | 453 | For increased security, follow these recommendations: 454 | 455 | * A load balancer stops TLS and can sanitize and reset 456 | `X-Forwarded-Proto` based on whether the request it received was 457 | encrypted or not. Set the `router.sanitize_forwarded_proto: false` 458 | manifest property for the Gorouter. 459 | 460 | * A load balancer configured for TCP passthrough can sanitize and 461 | reset the header based on whether the request it received was 462 | encrypted or not. Set the `router.sanitize_forwarded_proto: true` 463 | manifest property for the Gorouter. 464 | 465 | When a route service is mapped 466 | to a route, the Gorouter sanitizes the X-Forwarded-Proto 467 | header once, even though requests pass through the Gorouter more than 468 | once. 469 | 470 | For more information about 471 | securing traffic into <%= vars.app_runtime_abbr %>, see [Securing Traffic into <%= vars.app_runtime_abbr %>](../adminguide/securing-traffic.html). 472 | 473 | 474 | ## Recommendations for securing route services 475 | 476 | To best secure communications through route services, <%= vars.app_runtime_abbr %> operators: 477 | 478 | 1. Set the `router.route_services_recommend_https: true` manifest 479 | property. 480 | 481 | 1. Set the `router.disable_http: true` manifest property. Setting this 482 | property deactivates the HTTP listener, and forces all communication to the 483 | Gorouter to be HTTPS. This assumes all route services communicate 484 | over HTTPS with the Gorouter. This causes requests from other clients 485 | made to port 80 to be rejected. You must confirm that clients of all 486 | apps make requests over TLS. 487 | 488 | 1. Confirm that route services do not change the value of the 489 | `X-Forwarded-Proto` header. 490 | 491 | ## Web socket communications through route services 492 | 493 | Web socket communications through route services are supported by default and can be disabled by the following property: 494 | 495 | 1. Set the `router.route_services.enable_websockets: false` manifest 496 | property to disable web socket communications. 497 | Http status code 503, `StatusServiceUnavailable`, with an error message `Websocket requests are not supported for routes bound to Route Services` will be returned if one tries to establish a web socket connection via a route service. 498 | 499 | <% end %> 500 | -------------------------------------------------------------------------------- /supporting-multiple-cf-instances.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Supporting multiple instances 3 | owner: Core Services 4 | --- 5 | 6 | 7 | You can register your service broker with multiple <%= vars.app_runtime_first %> instances. 8 | 9 | It might be necessary for the broker to know which <%= vars.app_runtime_abbr %> instance is making a given request. For example, when using [Dashboard Single Sign-on](dashboard-sso.html), the broker is expected to interact with the authorization and token endpoints for a given <%= vars.app_runtime_abbr %> instance. 10 | 11 | There are two strategies that can be used to discover which <%= vars.app_runtime_abbr %> instance is making a given request. 12 | 13 | 14 | ## Routing and authentication 15 | 16 | The broker can use unique credentials, a unique URL, or both for each <%= vars.app_runtime_abbr %> instance. When registering the broker, you can configure different <%= vars.app_runtime_abbr %> instances to use different base URLs that include a unique ID. For example: 17 | 18 | * On <%= vars.app_runtime_abbr %> instance 1, the service broker is registered with the URL `broker.example.com/123`. 19 | 20 | * On <%= vars.app_runtime_abbr %> instance 2, the service broker is registered with the URL `broker.example.com/456`. 21 | 22 | 23 | ## X-Api-Info-Location header 24 | 25 | All calls to the broker from <%= vars.app_runtime_abbr %> include an `X-Api-Info-Location` header containing the `/v2/info` URL for that instance. The `/v2/info` endpoint returns further information, including the location of that <%= vars.app_runtime_abbr %> instance's UAA. 26 | 27 | Support for this header was introduced in cf-release v212. 28 | --------------------------------------------------------------------------------