├── CONTRIBUTING.md ├── README.md ├── getting-started-local.md ├── getting-started-pcf.md └── images └── getting-started ├── configuration-pcf.png └── configuration.png /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | If you have not previously done so, please fill out and 2 | submit the [Contributor License Agreement](https://cla.pivotal.io/sign/pivotal). 3 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Tutorials 2 | 3 | ### Spring Cloud Config Server 4 | 5 | 6 | * [Getting Started with Steeltoe and Spring Cloud OSS](getting-started-local.md)
7 | This tutorial will walk you through setting up and running a Spring Cloud Config Server on your local machine, then pulling configuration values into an ASP.NET Core application. 8 | 9 | * [Getting Started with Steeltoe and Spring Cloud Services on PCF](getting-started-pcf.md)
10 | This tutorial will walk you through pulling configuration values into an ASP.NET Core application running on PCF with Spring Cloud Services. 11 | -------------------------------------------------------------------------------- /getting-started-local.md: -------------------------------------------------------------------------------- 1 | This page shows how to quickly set up the Steeltoe Configuration extension in an ASP.NET Core application for accessing configuration values served by a [Spring Cloud Config](http://cloud.spring.io/spring-cloud-config/) Config Server. 2 | 3 | ### Step 0: Run a Config Server 4 | 5 | We will need a running Config Server from which our application can request configuration. To run the Config Server, we'll also need the Java Development Kit (JDK). [Download](http://www.oracle.com/technetwork/java/javase/downloads/index.html) the JDK from the Oracle website and follow the instructions to [install](http://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html) it. Then open Control Panel, search for and select "Edit the system environment variables", and add a system environment variable called `JAVA_HOME`, with the JDK installation's path (something like `C:\Program Files\Java\jdk1.8.0_91`) as the value. 6 | 7 | We will need [Git](https://git-scm.com) in order to obtain the code for the Config Server that we'll be using. If you haven't already installed Git, follow the [instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to do so. You may wish to look at [Git for Windows](https://git-for-windows.github.io). 8 | 9 | Now for the Config Server! Visit the [SteeltoeOSS/configserver](https://github.com/SteeltoeOSS/configserver) repository on GitHub. Copy the URL given in the "Clone or download" dropdown and use `git clone` to get a local copy of the repository: 10 | 11 | ``` 12 | > git clone git@github.com:SteeltoeOSS/configserver.git 13 | ``` 14 | 15 | When the clone operation has finished, `cd` into the Config Server's directory. The Config Server is built using [Apache Maven](https://maven.apache.org), and the project that we've just downloaded includes a Maven "wrapper" file (`mvnw.cmd`) that can be used in place of an actual Maven installation to run build commands. 16 | 17 | Start up the Config Server with the `mvnw spring-boot:run` command. This will take a little while as Maven downloads the necessary dependencies before starting the application: 18 | 19 | ``` 20 | configserver> mvnw spring-boot:run 21 | 22 | (...Startup output...) 23 | 24 | 2016-05-25 15:25:44.295 INFO 98987 --- [ main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8888 (http) 25 | 2016-05-25 15:25:44.298 INFO 98987 --- [ main] o.s.c.c.server.ConfigServerApplication : Started ConfigServerApplication in 2.634 seconds (JVM running for 58.236) 26 | ``` 27 | 28 | ### Step 1: Add the Steeltoe Configuration dependency 29 | 30 | [Generate](https://docs.asp.net/en/latest/client-side/yeoman.html) a new ASP.NET Core application using Yeoman. When the generator asks what type of application you want to create, select the "Web Application Basic [without Membership and Authorization]" option. Call the application “Steeltoe-OSS-Example”. Then create a `nuget.config` file, and within it, list the Steel Toe feeds: 31 | 32 | ``` 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | ``` 42 | 43 | In the `dependencies` block of our `project.json` file, add the `Steeltoe.Extensions.Configuration.ConfigServer` dependency: 44 | 45 | ``` 46 | "dependencies": { 47 | ... 48 | "Microsoft.VisualStudio.Web.BrowserLink.Loader": "14.0.0-rc2-final", 49 | "Steeltoe.Extensions.Configuration.ConfigServer": "1.0.0-dev-*" 50 | }, 51 | ``` 52 | 53 | ### Step 2: Configure the Config Server settings 54 | 55 | Next, open `appsettings.json`. We need to specify a couple of settings for Steel Toe Configuration to locate the Config Server and then to request our application's specific configuration from it: 56 | 57 | ``` 58 | { 59 | "spring": { 60 | "application": { 61 | "name": "steeltoe-oss-example" 62 | }, 63 | "cloud": { 64 | "config": { 65 | "uri": "http://localhost:8888" 66 | } 67 | } 68 | }, 69 | ... 70 | } 71 | 72 | ``` 73 | 74 | Spring Cloud commonly uses `spring.application.name` to identify client applications. In the case of the Config Server, the files in the Config Server's Git or Subversion repository will include application names in their filenames, and the Server uses `spring.application.name` to determine which files in its repository contain configuration for our application. 75 | 76 | The other property, `spring.cloud.config.uri`, tells a Steel Toe Configuration client application where to locate its Config Server. We give this the URL of the Config Server that we have running on port 8888. 77 | 78 | ### Step 3: Add the Config Server configuration provider 79 | 80 | In the constructor of our `Startup.cs`, where we use the `ConfigurationBuilder`, we need to add the Config Server as a configuration source. 81 | 82 | ``` 83 | using Steeltoe.Extensions.Configuration; 84 | 85 | namespace Steeltoe_OSS_Example 86 | { 87 | public class Startup 88 | { 89 | public Startup(IHostingEnvironment env) 90 | { 91 | var builder = new ConfigurationBuilder() 92 | .SetBasePath(env.ContentRootPath) 93 | .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true) 94 | .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true) 95 | .AddEnvironmentVariables() 96 | 97 | .AddConfigServer(env); 98 | Configuration = builder.Build(); 99 | } 100 | ``` 101 | 102 | (Don't forget the `using` statement at the top.) 103 | 104 | Now drop down to `ConfigureServices()` and add the Config Server to our `IServiceCollection`. 105 | 106 | ``` 107 | // This method gets called by the runtime. Use this method to add services to the container. 108 | public void ConfigureServices(IServiceCollection services) 109 | { 110 | services.AddConfigServer(Configuration); 111 | 112 | // Add framework services. 113 | services.AddMvc(); 114 | } 115 | ``` 116 | 117 | This method also takes care of adding the `IOptions` service and adds `IConfigurationRoot` as a service. This will become important in the next step, which is... 118 | 119 | ### Step 4: Use configuration in the application 120 | 121 | Open our `HomeController.cs` file. We need to give this controller an `IConfigurationRoot` property and a constructor to proceed further: 122 | 123 | ``` 124 | using Microsoft.Extensions.Configuration; 125 | using Steeltoe.Extensions.Configuration.ConfigServer; 126 | 127 | namespace Steeltoe_OSS_Example.Controllers 128 | { 129 | public class HomeController : Controller 130 | { 131 | 132 | private IConfigurationRoot Config { get; set; } 133 | 134 | public HomeController(IConfigurationRoot config) 135 | { 136 | Config = config; 137 | } 138 | ``` 139 | 140 | (Again, don't forget the `using` statements.) 141 | 142 | We now have access to our configuration within the controller (the `Config` property). Next, let's add a `ConfigServer()` action. This action's view will display the value of a configuration property that we obtain from the Config Server, so let's set that value here: 143 | 144 | ``` 145 | public IActionResult ConfigServer() 146 | { 147 | ViewData["Foo"] = Config["Foo"]; 148 | return View(); 149 | } 150 | ``` 151 | 152 | Create the `ConfigServer.cshtml` view in `Views/Home/`. It should look like this: 153 | 154 | ``` 155 |

Configuration from the Spring Cloud Config Server

156 | 157 |

Here is the value.

158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 168 |
PropertyValue
Foo 166 | @ViewData["Foo"] 167 |
169 | ``` 170 | 171 | ### Step 5: Voila! 172 | 173 | That's it! Run `dotnet restore` to install all of our dependencies: 174 | 175 | ``` 176 | Steeltoe-OSS-Example> dotnet restore 177 | ... 178 | Feeds used: 179 | https://www.myget.org/F/steeltoemaster/api/v3/index.json 180 | https://www.myget.org/F/steeltoedev/api/v3/index.json 181 | https://api.nuget.org/v3/index.json 182 | ``` 183 | 184 | Then run the application: 185 | 186 | ``` 187 | Steeltoe-OSS-Example> dotnet run 188 | ... 189 | Now listening on: http://localhost:5000 190 | Application started. Press Ctrl+C to shut down. 191 | ``` 192 | 193 | And in a browser, visit http://localhost:5000/Home/ConfigServer. You should see something like this: 194 | 195 | ![Steeltoe-OSS-Example Config Server page](images/getting-started/configuration.png) 196 | 197 | -------------------------------------------------------------------------------- /getting-started-pcf.md: -------------------------------------------------------------------------------- 1 | This page shows how to quickly set up the Steeltoe Configuration extension in an ASP.NET Core application for accessing configuration values served by a [Spring Cloud Services](https://network.pivotal.io/products/p-spring-cloud-services) Config Server service instance on [Pivotal Cloud Foundry®](https://network.pivotal.io/products/pivotal-cf) (PCF). We'll use [PCF Dev](http://pivotal.io/pcf-dev) for this purpose; if you don't yet have PCF Dev installed, follow the [tutorial at pivotal.io](http://pivotal.io/platform/pcf-tutorials/getting-started-with-pivotal-cloud-foundry-dev/introduction) before proceeding with these instructions. 2 | 3 | ### Step 0: Create a Config Server Service Instance 4 | 5 | We will need a Config Server service instance from which our application can request configuration. To make this Spring Cloud Services service available, you must start PCF Dev with the flag `-s scs`: 6 | 7 | ``` 8 | > cf dev start -s scs 9 | ... 10 | Starting VM... 11 | Provisioning VM... 12 | Waiting for services to start... 13 | 46 out of 46 running 14 | ... 15 | ``` 16 | 17 | Run `cf marketplace` to view the available services: 18 | 19 | ``` 20 | > cf marketplace 21 | Getting services from marketplace in org pcfdev-org / space pcfdev-space as user... 22 | OK 23 | 24 | service plans description 25 | p-circuit-breaker-dashboard standard Circuit Breaker Dashboard for Spring Cloud Applications 26 | p-config-server standard Config Server for Spring Cloud Applications 27 | ... 28 | ``` 29 | 30 | Using the `cf create-service` command, create a new Config Server service instance. Use the `-c` flag to provide configuration parameters for the instance--the only parameter we'll need in this case is the URI of a Git repository from which the Config Server can retrieve configuration, so use the following command: 31 | 32 | ``` 33 | > cf create-service p-config-server standard config-server -c '{"git": {"uri": "https://github.com/spring-cloud-samples/cook-config" } }' 34 | Creating service instance config-server in org pcfdev-org / space pcfdev-space as admin... 35 | OK 36 | 37 | Create in progress. Use 'cf services' or 'cf service config-server' to check operation status. 38 | ``` 39 | 40 | The Config Server service instance will take a little while to be provisioned. As the command output says, we can use the command `cf service config-server` to check on the instance's status; when it's been created, the command will give us the output `Status: create succeeded`. 41 | 42 | ``` 43 | > cf service config-server 44 | 45 | Service instance: config-server 46 | Service: p-config-server 47 | Bound apps: 48 | Tags: 49 | Plan: standard 50 | Description: Config Server for Spring Cloud Applications 51 | Documentation url: http://docs.pivotal.io/spring-cloud-services/ 52 | Dashboard: https://spring-cloud-broker.local2.pcfdev.io/dashboard/p-config-server/37f28420-3074-49f9-bfc8-500a977c3ccb 53 | 54 | Last Operation 55 | Status: create succeeded 56 | ... 57 | ``` 58 | 59 | ### Step 1: Add the Steeltoe Configuration dependency 60 | 61 | [Generate](https://docs.asp.net/en/latest/client-side/yeoman.html) a new ASP.NET Core application using Yeoman. When the generator asks what type of application you want to create, select the "Web Application Basic [without Membership and Authorization]" option. Call the application “Steeltoe PCF Example”. Then create a `nuget.config` file, and within it, list the Steel Toe feeds: 62 | 63 | ``` 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | ``` 73 | 74 | In the `dependencies` block of our `project.json` file, add the `Pivotal.Extensions.Configuration.ConfigServer` dependency: 75 | 76 | ``` 77 | "dependencies": { 78 | ... 79 | "Microsoft.VisualStudio.Web.BrowserLink.Loader": "14.0.0", 80 | "Pivotal.Extensions.Configuration.ConfigServer": "1.0.0-dev-*" 81 | }, 82 | ``` 83 | 84 | ### Step 1.5: 85 | 86 | Create a Cloud Foundry manifest for our application. It should be a file called `manifest.yml` and should look like so: 87 | 88 | ``` 89 | --- 90 | applications: 91 | - name: steeltoe-pcf-example 92 | memory: 512M 93 | disk_quota: 1G 94 | random-route: true 95 | path: . 96 | buildpack: https://github.com/cloudfoundry-community/dotnet-core-buildpack 97 | services: 98 | - config-server 99 | ``` 100 | 101 | This sets up our application to use the Config Server service instance we've created. It also tells PCF Dev to stage this application using the [cloudfoundry-community/dotnet-core-buildpack](https://github.com/cloudfoundry-community/dotnet-core-buildpack). 102 | 103 | ### Step 2: Configure the Config Server settings 104 | 105 | Next, open `appsettings.json`. We need to specify a setting for Steel Toe Configuration to request our application's specific configuration from the Config Server: 106 | 107 | ``` 108 | { 109 | "spring": { 110 | "application": { 111 | "name": "steeltoe-pcf-example" 112 | }, 113 | "cloud": { 114 | "config": { 115 | "uri": "http://localhost:8888" 116 | } 117 | } 118 | }, 119 | ... 120 | } 121 | 122 | ``` 123 | 124 | Spring Cloud commonly uses `spring.application.name` to identify client applications. In the case of the Config Server, the files in the Config Server's Git or Subversion repository will include application names in their filenames, and the Server uses `spring.application.name` to determine which files in its repository contain configuration for our application. 125 | 126 | The other property, `spring.cloud.config.uri`, is optional in our case. This tells a Steeltoe Configuration client application where to locate its Config Server. We give this a value of `http://localhost:8888` (the default port on which a Spring Cloud Config Server runs). As we'll soon see, however, this will be overridden when we bring in the Cloud Foundry Config Server, in: 127 | 128 | ### Step 3: Add the Config Server configuration provider 129 | 130 | In the constructor of our `Startup.cs`, where we use the `ConfigurationBuilder`, we need to add the Config Server as a configuration source. 131 | 132 | ``` 133 | using Pivotal.Extensions.Configuration; 134 | 135 | namespace Steeltoe_PCF_Example 136 | { 137 | public class Startup 138 | { 139 | public Startup(IHostingEnvironment env) 140 | { 141 | var builder = new ConfigurationBuilder() 142 | .SetBasePath(env.ContentRootPath) 143 | .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true) 144 | .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true) 145 | .AddEnvironmentVariables() 146 | 147 | .AddConfigServer(env); 148 | Configuration = builder.Build(); 149 | } 150 | ``` 151 | 152 | Don't forget the `using` statement at the top. In fact, take special note of that `using` statement. Steeltoe's Cloud Foundry configuration provider parses the special `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables provided to Cloud Foundry applications. When we push this application to PCF Dev, `VCAP_APPLICATION` will be set to contain application information (such as our application's space name, space ID, URIs, host, and port), and `VCAP_SERVICES` will be set to contain information for the services that are bound to the application (including a service instance's name, plan, tags, and connection information). 153 | 154 | The connection information for our Config Server service instance, once it's made available to our application via the environment variables, will override what we specified in our `appsettings.json`. That setting is still useful to have for running an application locally against a local Config Server, but since we've placed the environment variables configuration provider higher in priority than `appsettings.json` (it's added _after_ `appsettings.json`), the information from the environment will override our hard-coded setting. 155 | 156 | With the provider in place, we'll next add the Config Server to the set of services that we set up in the `ConfigureServices()` method. 157 | 158 | ``` 159 | // This method gets called by the runtime. Use this method to add services to the container. 160 | public void ConfigureServices(IServiceCollection services) 161 | { 162 | services.AddConfigServer(Configuration); 163 | 164 | // Add framework services. 165 | services.AddMvc(); 166 | } 167 | ``` 168 | 169 | The `AddConfigServer()` method also takes care of adding the `IOptions` service and adds `IConfigurationRoot` as a service. This will become important in the next step, which is... 170 | 171 | ### Step 4: Use configuration in the application 172 | 173 | Open our `HomeController.cs` file. We need to give this controller an `IConfigurationRoot` property and a constructor to proceed further: 174 | 175 | ``` 176 | using Pivotal.Extensions.Configuration.ConfigServer; 177 | using Microsoft.Extensions.Configuration; 178 | 179 | namespace Steeltoe_PCF_Example.Controllers 180 | { 181 | public class HomeController : Controller 182 | { 183 | 184 | private IConfigurationRoot Config { get; set; } 185 | 186 | public HomeController(IConfigurationRoot config) 187 | { 188 | Config = config; 189 | } 190 | ``` 191 | 192 | (Again, don't forget the `using` statements.) 193 | 194 | We now have access to our configuration within the controller (the `Config` property). Next, let's add a `ConfigServer()` action. This action's view will display the value of a configuration property that we obtain from the Config Server, so let's set that value here: 195 | 196 | ``` 197 | public IActionResult ConfigServer() 198 | { 199 | ViewData["Foo"] = Config["Foo"]; 200 | return View(); 201 | } 202 | ``` 203 | 204 | Create the `ConfigServer.cshtml` view in `Views/Home/`. It should look like this: 205 | 206 | ``` 207 |

Configuration from the Spring Cloud Config Server

208 | 209 |

Here is the value.

210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 220 |
PropertyValue
Foo 218 | @ViewData["Foo"] 219 |
221 | ``` 222 | 223 | ### Step 5: Voila! 224 | 225 | That's it! Run `dotnet restore` to install all of our dependencies: 226 | 227 | ``` 228 | Steeltoe-PCF-Example> dotnet restore 229 | ... 230 | Feeds used: 231 | https://www.myget.org/F/steeltoemaster/api/v3/index.json 232 | https://www.myget.org/F/steeltoedev/api/v3/index.json 233 | https://api.nuget.org/v3/index.json 234 | ``` 235 | 236 | Then push the application to PCF Dev: 237 | 238 | ``` 239 | Steeltoe-PCF-Example> cf push 240 | ... 241 | 242 | 0 of 1 instances running, 1 starting 243 | 1 of 1 instances running 244 | 245 | App started 246 | 247 | ... 248 | 249 | state since cpu memory disk details 250 | #0 running 2016-07-14 03:24:25 PM 0.0% 0 of 512M 0 of 1G 251 | ``` 252 | 253 | In a browser, visit the path `/Home/ConfigServer` on the application. You should see something like this: 254 | 255 | ![Steeltoe-PCF-Example Config Server page](images/getting-started/configuration-pcf.png) 256 | 257 | -------------------------------------------------------------------------------- /images/getting-started/configuration-pcf.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SteeltoeOSS/Tutorials/157726206d3268daf52ef0ae143c3a5f5e6523b2/images/getting-started/configuration-pcf.png -------------------------------------------------------------------------------- /images/getting-started/configuration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SteeltoeOSS/Tutorials/157726206d3268daf52ef0ae143c3a5f5e6523b2/images/getting-started/configuration.png --------------------------------------------------------------------------------