833 lines
32 KiB
Plaintext
833 lines
32 KiB
Plaintext
[[cloudfoundry]]
|
|
== Pivotal CloudFoundry
|
|
:geode-name: {apache-geode-name}
|
|
:images-dir: ./images
|
|
:pcc-name: Pivotal Cloud Cache
|
|
:pcf-name: Pivotal CloudFoundry
|
|
|
|
NOTE: As of the VMware, Inc. acquisition of Pivotal Software, Inc., {pcf-name} (PCF) is now known as VMware Tanzu
|
|
Application Service (TAS) for VMs. Also, {pcc-name} (PCC) has been rebranded as VMware Tanzu GemFire for VMS.
|
|
This documentation will eventually be updated to reflect the rebranding.
|
|
|
|
In most cases, when you deploy (that is, `cf push`) your Spring Boot applications to {pcf-name} (PCF), you bind
|
|
your application to one or more instances of the {pcc-name} (PCC) service.
|
|
|
|
In a nutshell, {pivotal-cloudcache-website}[{pcc-name}] (PCC) is a managed version of
|
|
{pivotal-gemfire-website}[{pivotal-gemfire-name}] that runs in {pivotal-cloudfoundry-website}[{pcf-name}] (PCF).
|
|
When running in or across cloud environments (such as AWS, Azure, GCP, or PWS), PCC with PCF offers several advantages
|
|
over trying to run and manage your own standalone {geode-name} clusters. It handles many of the infrastructure-related,
|
|
operational concerns so that you need not do so.
|
|
|
|
[[cloudfoundry-cloudcache-security-auth-runtime-user-configuration]]
|
|
=== Running a Spring Boot application as a specific user
|
|
|
|
By default, Spring Boot applications run as a `cluster_operator` role-based user in {pcf-name} when the application
|
|
is bound to a {pcc-name} service instance.
|
|
|
|
A `cluster_operator` has full system privileges (that is, authorization) to do whatever that user wishes to involving
|
|
the PCC service instance. A `cluster_operator` has read and write access to all the data, can modify the schema (for
|
|
example, create and destroy Regions, add and remove Indexes, change eviction or expiration policies, and so on), start
|
|
and stop servers in the PCC cluster, or even modify permissions.
|
|
|
|
.About cluster_operator as the default user
|
|
****
|
|
One of the reasons why Spring Boot applications default to running as a `cluster_operator` is to allow configuration
|
|
metadata to be sent from the client to the server. Enabling configuration metadata to be sent from the client to the
|
|
server is a useful development-time feature and is as simple as annotating your main `@SpringBootApplication` class
|
|
with the `@EnableClusterConfiguration` annotation:
|
|
|
|
.Using `@EnableClusterConfiguration`
|
|
====
|
|
[source,java]
|
|
----
|
|
@SpringBootApplication
|
|
@EnableClusterConfiguration(useHttp = true)
|
|
class SpringBootApacheGeodeClientCacheApplication { }
|
|
----
|
|
====
|
|
|
|
With `@EnableClusterConfiguration`, Region and OQL Index configuration metadata that is defined on the client can be
|
|
sent to servers in the PCC cluster. {geode-name} requires matching Regions by name on both the client and the servers
|
|
in order for clients to send and receive data to and from the cluster.
|
|
|
|
For example, when you declare the Region where an application entity is persisted by using the `@Region` mapping
|
|
annotation and declare the `@EnableEntityDefinedRegions` annotation on the main `@SpringBootApplication` class
|
|
in conjunction with the `@EnableClusterConfiguration` annotation, not only does SBDG create the required client Region,
|
|
but it also sends the configuration metadata for this Region to the servers in the cluster to create the matching,
|
|
required server Region, where the data for your application entity is managed.
|
|
****
|
|
|
|
However...
|
|
|
|
> With great power comes great responsibility. - Uncle Ben
|
|
|
|
Not all Spring Boot applications using PCC need to change the schema or even modify data. Rather, certain applications
|
|
may need only read access. Therefore, it is ideal to be able to configure your Spring Boot applications to run with
|
|
a different user at runtime other than the auto-configured `cluster_operator`, by default.
|
|
|
|
A prerequisite for running a Spring Boot application in PCC with a specific user is to create a user with restricted
|
|
permissions by using {pcf-name} AppsManager while provisioning the PCC service instance to which the Spring Boot
|
|
application is bound.
|
|
|
|
Configuration metadata for the PCC service instance might appear as follows:
|
|
|
|
.{pcc-name} configuration metadata
|
|
====
|
|
[source,json]
|
|
----
|
|
{
|
|
"p-cloudcache":[{
|
|
"credentials": {
|
|
"distributed_system_id": "0",
|
|
"locators": [ "localhost[55221]" ],
|
|
"urls": {
|
|
"gfsh": "https://cloudcache-12345.services.cf.pws.com/gemfire/v1",
|
|
"pulse": "https://cloudcache-12345.services.cf.pws.com/pulse"
|
|
},
|
|
"users": [{
|
|
"password": "*****",
|
|
"roles": [ "cluster_operator" ],
|
|
"username": "cluster_operator_user"
|
|
}, {
|
|
"password": "*****",
|
|
"roles": [ "developer" ],
|
|
"username": "developer_user"
|
|
}, {
|
|
"password": "*****",
|
|
"roles": [ "read-only-user" ],
|
|
"username": "guest"
|
|
}],
|
|
"wan": {
|
|
"sender_credentials": {
|
|
"active": {
|
|
"password": "*****",
|
|
"username": "gateway-sender-user"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"name": "jblum-pcc",
|
|
"plan": "small",
|
|
"tags": [ "gemfire", "cloudcache", "database", "pivotal" ]
|
|
}]
|
|
}
|
|
----
|
|
====
|
|
|
|
In the PCC service instance configuration metadata shown in the preceding example, we see a `guest` user with
|
|
the `read-only-user` role. If the `read-only-user` role is properly configured with read-only permissions as the name
|
|
implies, we could configure our Spring Boot application to run as `guest` with read-only access:
|
|
|
|
.Configuring a Spring Boot application to run as a specific user
|
|
====
|
|
[source,properties]
|
|
----
|
|
# Spring Boot application.properties for PCF when using PCC
|
|
|
|
spring.data.gemfire.security.username=guest
|
|
----
|
|
====
|
|
|
|
TIP: The `spring.data.gemfire.security.username` property corresponds directly to the SDG `@EnableSecurity` annotation's
|
|
`securityUsername` attribute. See the
|
|
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#securityUsername--[Javadoc]
|
|
for more details.
|
|
|
|
The `spring.data.gemfire.security.username` property is the same property used by Spring Data for {geode-name} (SDG) to
|
|
configure the runtime user of your Spring Data application when you connect to an externally managed {geode-name}
|
|
cluster.
|
|
|
|
In this case, SBDG uses the configured username to look up the authentication credentials of the user to set
|
|
the username and password used by the Spring Boot `ClientCache` application when connecting to PCC while running in PCF.
|
|
|
|
If the username is not valid, an `IllegalStateException` is thrown.
|
|
|
|
By using {spring-boot-docs-html}/#boot-features-profiles[Spring profiles], it would be a simple matter to configure
|
|
the Spring Boot application to run with a different user depending on environment.
|
|
|
|
See the {pcc-name} documentation on {pivotal-cloudcache-docs}/security.html[security] for configuring users with
|
|
assigned roles and permissions.
|
|
|
|
[[cloudfoundry-cloudcache-security-auth-autoconfiguration-override]]
|
|
==== Overriding Authentication Auto-configuration
|
|
|
|
It should be understood that auto-configuration for client authentication is available only for managed environments,
|
|
such as {pcf-name}. When running in externally managed environments, you must explicitly set a username and password
|
|
to authenticate, as described in <<geode-security-auth-clients-non-managed>>.
|
|
|
|
To completely override the auto-configuration of client authentication, you can set both a username and a password:
|
|
|
|
.Overriding Security Authentication Auto-configuration with explicit username and password
|
|
====
|
|
[source,txt]
|
|
----
|
|
# Spring Boot application.properties
|
|
|
|
spring.data.gemfire.security.username=MyUser
|
|
spring.data.gemfire.security.password=MyPassword
|
|
----
|
|
====
|
|
|
|
In this case, SBDG's auto-configuration for authentication is effectively disabled and security credentials are not
|
|
extracted from the environment.
|
|
|
|
[[cloudfoundry-cloudcache-serviceinstance-targeting]]
|
|
=== Targeting Specific {pcc-name} Service Instances
|
|
|
|
It is possible to provision multiple instances of the {pcc-name} service in your {pcf-name} environment. You can then
|
|
bind multiple PCC service instances to your Spring Boot application.
|
|
|
|
However, Spring Boot for {geode-name} (SBDG) only auto-configures one PCC service instance for your Spring Boot
|
|
application. This does not mean that it is not possible to use multiple PCC service instances with your Spring Boot
|
|
application, just that SBDG only auto-configures one service instance for you.
|
|
|
|
You must select which PCC service instance your Spring Boot application automatically auto-configures for you when
|
|
you have multiple instances and want to target a specific PCC service instance to use.
|
|
|
|
To do so, declare the following SBDG property in Spring Boot `application.properties`:
|
|
|
|
.Spring Boot application.properties targeting a specific PCC service instance by name
|
|
====
|
|
[source,properties]
|
|
----
|
|
# Spring Boot application.properties
|
|
|
|
spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name=pccServiceInstanceTwo
|
|
----
|
|
====
|
|
|
|
The `spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name` property tells SBDG which PCC service instance
|
|
to auto-configure.
|
|
|
|
If the PCC service instance identified by the property does not exist, SBDG throws an `IllegalStateException`
|
|
stating the PCC service instance by name could not be found.
|
|
|
|
If you did not set the property and your Spring Boot application is bound to multiple PCC service instances,
|
|
SBDG auto-configures the first PCC service instance it finds by name, alphabetically.
|
|
|
|
If you did not set the property and no PCC service instance is found, SBDG logs a warning.
|
|
|
|
[[cloudfoundry-cloudcache-multiinstance-using]]
|
|
=== Using Multiple {pcc-name} Service Instances
|
|
|
|
If you want to use multiple PCC service instances with your Spring Boot application, you need to configure multiple
|
|
connection `Pools` connected to each PCC service instance used by your Spring Boot application.
|
|
|
|
The configuration would be similar to the following:
|
|
|
|
.Multiple {pcc-name} Service Instance Configuration
|
|
====
|
|
[source,java]
|
|
----
|
|
@Configuration
|
|
@EnablePools(pools = {
|
|
@EnablePool(name = "PccOne"),
|
|
@EnablePool(name = "PccTwo"),
|
|
...,
|
|
@EnablePool(name = "PccN")
|
|
})
|
|
class PccConfiguration {
|
|
// ...
|
|
}
|
|
----
|
|
====
|
|
|
|
You would then externalize the configuration for the individually declared `Pools` in Spring Boot
|
|
`application.properties`:
|
|
|
|
.Configuring Locator-based Pool connections
|
|
====
|
|
[source,properties]
|
|
----
|
|
# Spring Boot `application.properties`
|
|
|
|
spring.data.gemfire.pool.pccone.locators=pccOneHost1[port1], pccOneHost2[port2], ..., pccOneHostN[portN]
|
|
|
|
spring.data.gemfire.pool.pcctwo.locators=pccTwoHost1[port1], pccTwoHost2[port2], ..., pccTwoHostN[portN]
|
|
----
|
|
====
|
|
|
|
NOTE: Though less common, you can also configure the `Pool` of connections to target specific servers in the cluster
|
|
by setting the `spring.data.gemfire.pool.<named-pool>.severs` property.
|
|
|
|
TIP: Keep in mind that properties in Spring Boot `application.properties` can refer to other properties:
|
|
`property=$\{otherProperty}`. This lets you further externalize properties by using Java System properties
|
|
or environment variables.
|
|
|
|
A client Region is then assigned the Pool of connections that are used to send data to and from the specific
|
|
PCC service instance (cluster):
|
|
|
|
.Assigning a Pool to a client Region
|
|
====
|
|
[source,java]
|
|
----
|
|
@Configuration
|
|
class GeodeConfiguration {
|
|
|
|
@Bean("Example")
|
|
ClientRegionFactoryBean exampleRegion(GemFireCache gemfireCache,
|
|
@Qualifier("PccTwo") Pool poolForPccTwo) {
|
|
|
|
ClientRegionFactoryBean exampleRegion = new ClientRegionFactoryBean();
|
|
|
|
exampleRegion.setCache(gemfireCache);
|
|
exampleRegion.setPool(poolForPccTwo);
|
|
exampleRegion.setShortcut(ClientRegionShortcut.PROXY);
|
|
|
|
return exampleRegion;
|
|
}
|
|
}
|
|
----
|
|
====
|
|
|
|
You can configure as many Pools and client Regions as your application needs. Again, the `Pool` determines
|
|
the {pcc-name} service instance and cluster in which the data for the client Region resides.
|
|
|
|
NOTE: By default, SBDG configures all `Pools` declared in a Spring Boot `ClientCache` application to connect to
|
|
and use a single PCC service instance. This may be a targeted PCC service instance when you use the
|
|
`spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name` property
|
|
as discussed <<cloudfoundry-cloudcache-multiinstance-using,earlier>>.
|
|
|
|
[[cloudfoundry-geode]]
|
|
=== Hybrid {pcf-name} and {geode-name} Spring Boot Applications
|
|
|
|
Sometimes, it is desirable to deploy (that is, `cf push`) and run your Spring Boot applications in {pcf-name}
|
|
but still connect your Spring Boot applications to an externally managed, standalone {geode-name} cluster.
|
|
|
|
Spring Boot for {geode-name} (SBDG) makes this a non-event and honors its "_little to no code or configuration changes
|
|
necessary_" goal. Regardless of your runtime choice, it should just work!
|
|
|
|
To help guide you through this process, we cover the following topics:
|
|
|
|
. Install and Run PCFDev.
|
|
. Start an {geode-name} cluster.
|
|
. Create a User-Provided Service (CUPS).
|
|
. Push and Bind a Spring Boot application.
|
|
. Run the Spring Boot application.
|
|
|
|
[[cloudfoundry-geode-pcfdev]]
|
|
==== Running PCFDev
|
|
|
|
For this exercise, we use https://docs.pivotal.io/pcf-dev/install-osx.html[PCF Dev].
|
|
|
|
PCF Dev, much like PCF, is an elastic application runtime for deploying, running, and managing your Spring Boot
|
|
applications. However, it does so in the confines of your local development environment -- that is, your workstation.
|
|
|
|
Additionally, PCF Dev provides several services, such as MySQL, Redis, and RabbitMQ. You Spring Boot application
|
|
can bind to and use these services to accomplish its tasks.
|
|
|
|
However, PCF Dev lacks the {pcc-name} service that is available in PCF. This is actually ideal for this exercise since
|
|
we are trying to build and run Spring Boot applications in a PCF environment but connect to an externally managed,
|
|
standalone {geode-name} cluster.
|
|
|
|
As a prerequisite, you need to follow the steps outlined in the
|
|
https://pivotal.io/platform/pcf-tutorials/getting-started-with-pivotal-cloud-foundry-dev/introduction[tutorial]
|
|
to get PCF Dev set up and running on your workstation.
|
|
|
|
To run PCF Dev, execute the following `cf` CLI command, replacing the path to the TGZ file with the file you acquired
|
|
from the https://network.pivotal.io/products/pcfdev[download]:
|
|
|
|
.Start PCF Dev
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf dev start -f ~/Downloads/Pivotal/CloudFoundry/Dev/pcfdev-v1.2.0-darwin.tgz
|
|
----
|
|
====
|
|
|
|
You should see output similar to the following:
|
|
|
|
.Running PCF Dev
|
|
====
|
|
[source,txt]
|
|
----
|
|
Downloading Network Helper...
|
|
Progress: |====================>| 100.0%
|
|
Installing cfdevd network helper (requires administrator privileges)...
|
|
Password:
|
|
Setting up IP aliases for the BOSH Director & CF Router (requires administrator privileges)
|
|
Downloading Resources...
|
|
Progress: |====================>| 100.0%
|
|
Setting State...
|
|
WARNING: PCF Dev requires 8192 MB of RAM to run. This machine may not have enough free RAM.
|
|
Creating the VM...
|
|
Starting VPNKit...
|
|
Waiting for the VM...
|
|
Deploying the BOSH Director...
|
|
|
|
Deploying PAS...
|
|
Done (14m34s)
|
|
Deploying Apps-Manager...
|
|
Done (1m41s)
|
|
|
|
██████╗ ██████╗███████╗██████╗ ███████╗██╗ ██╗
|
|
██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██║ ██║
|
|
██████╔╝██║ █████╗ ██║ ██║█████╗ ██║ ██║
|
|
██╔═══╝ ██║ ██╔══╝ ██║ ██║██╔══╝ ╚██╗ ██╔╝
|
|
██║ ╚██████╗██║ ██████╔╝███████╗ ╚████╔╝
|
|
╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚══════╝ ╚═══╝
|
|
is now running!
|
|
|
|
To begin using PCF Dev, please run:
|
|
cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
|
|
|
|
Admin user => Email: admin / Password: admin
|
|
Regular user => Email: user / Password: pass
|
|
|
|
To access Apps Manager, navigate here: https://apps.dev.cfdev.sh
|
|
|
|
To deploy a particular service, please run:
|
|
cf dev deploy-service <service-name> [Available services: mysql,redis,rabbitmq,scs]
|
|
----
|
|
====
|
|
|
|
To use the `cf` CLI tool, you must login to the PCF Dev environment:
|
|
|
|
.Login to PCF Dev using `cf` CLI
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
|
|
----
|
|
====
|
|
|
|
You can also access the https://apps.dev.cfdev.sh/[PCF Dev Apps Manager] tool from your Web browser at the following URL:
|
|
|
|
https://apps.dev.cfdev.sh/
|
|
|
|
Apps Manager provides a nice UI to manage your org, space, services and apps. It lets you push and update apps,
|
|
create services, bind apps to the services, and start and stop your deployed applications, among many other things.
|
|
|
|
[[cloudfoundry-geode-cluster]]
|
|
==== Running an {geode-name} Cluster
|
|
|
|
Now that PCF Dev is set up and running, you need to start an external, standalone {geode-name} cluster to which our
|
|
Spring Boot application connects and uses to manage its data.
|
|
|
|
You need to install a {apache-geode-website}/releases/[distribution] of {geode-name} on your computer. Then you must
|
|
set the `$GEODE` environment variable. It is also convenient to add `$GEODE/bin` to your system `$PATH`.
|
|
|
|
Afterward, you can launch the Geode Shell (_Gfsh_) tool:
|
|
|
|
.Running Gfsh
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ echo $GEODE
|
|
/Users/jblum/pivdev/apache-geode-1.6.0
|
|
|
|
$ gfsh
|
|
_________________________ __
|
|
/ _____/ ______/ ______/ /____/ /
|
|
/ / __/ /___ /_____ / _____ /
|
|
/ /__/ / ____/ _____/ / / / /
|
|
/______/_/ /______/_/ /_/ 1.6.0
|
|
|
|
Monitor and Manage Apache Geode
|
|
gfsh>
|
|
----
|
|
====
|
|
|
|
We have provided the Gfsh shell script that you can use to start the {geode-name} cluster:
|
|
|
|
.Gfsh shell script to start the {geode-name} cluster
|
|
====
|
|
[source,txt]
|
|
----
|
|
include::{docs-resources-dir}/geode/bin/start-cluster.gfsh[]
|
|
----
|
|
====
|
|
|
|
The `start-cluster.gfsh` shell script starts one Geode Locator and one Geode server.
|
|
|
|
A Locator is used by clients to discover and connect to servers in a cluster to manage its data. A Locator is also used
|
|
by new servers that join a cluster as peer members, which lets the cluster be elastically scaled out (or scaled down,
|
|
as needed). A Geode server stores the data for the application.
|
|
|
|
You can start as many Locators or servers as necessary to meet the availability and load demands of your application.
|
|
The more Locators and servers your cluster has, the more resilient it is to failure. However, you should size your
|
|
cluster accordingly, based on your application's needs, since there is overhead relative to the cluster size.
|
|
|
|
You see output similar to the following when starting the Locator and server:
|
|
|
|
.Starting the {geode-name} cluster
|
|
====
|
|
[source,txt]
|
|
----
|
|
gfsh>start locator --name=LocatorOne --log-level=config --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar --J=-Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager --J=-Dgemfire.http-service-port=8080
|
|
Starting a Geode Locator in /Users/jblum/pivdev/lab/LocatorOne...
|
|
..
|
|
Locator in /Users/jblum/pivdev/lab/LocatorOne on 10.99.199.24[10334] as LocatorOne is currently online.
|
|
Process ID: 14358
|
|
Uptime: 1 minute 1 second
|
|
Geode Version: 1.6.0
|
|
Java Version: 1.8.0_192
|
|
Log File: /Users/jblum/pivdev/lab/LocatorOne/LocatorOne.log
|
|
JVM Arguments: -Dgemfire.enable-cluster-configuration=true -Dgemfire.load-cluster-configuration-from-dir=false -Dgemfire.log-level=config -Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager -Dgemfire.http-service-port=8080 -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
|
|
Class-Path: /Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-core-1.6.0.jar:/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar:/Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-dependencies.jar
|
|
|
|
Security Manager is enabled - unable to auto-connect. Please use "connect --locator=10.99.199.24[10334] --user --password" to connect Gfsh to the locator.
|
|
|
|
Authentication required to connect to the Manager.
|
|
|
|
gfsh>connect
|
|
Connecting to Locator at [host=localhost, port=10334] ..
|
|
Connecting to Manager at [host=10.99.199.24, port=1099] ..
|
|
user: admin
|
|
password: *****
|
|
Successfully connected to: [host=10.99.199.24, port=1099]
|
|
|
|
gfsh>start server --name=ServerOne --log-level=config --user=admin --password=admin --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar
|
|
Starting a Geode Server in /Users/jblum/pivdev/lab/ServerOne...
|
|
....
|
|
Server in /Users/jblum/pivdev/lab/ServerOne on 10.99.199.24[40404] as ServerOne is currently online.
|
|
Process ID: 14401
|
|
Uptime: 3 seconds
|
|
Geode Version: 1.6.0
|
|
Java Version: 1.8.0_192
|
|
Log File: /Users/jblum/pivdev/lab/ServerOne/ServerOne.log
|
|
JVM Arguments: -Dgemfire.default.locators=10.99.199.24[10334] -Dgemfire.security-username=admin -Dgemfire.start-dev-rest-api=false -Dgemfire.security-password=******** -Dgemfire.use-cluster-configuration=true -Dgemfire.log-level=config -XX:OnOutOfMemoryError=kill -KILL %p -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
|
|
Class-Path: /Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-core-1.6.0.jar:/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar:/Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-dependencies.jar
|
|
----
|
|
====
|
|
|
|
Once the cluster has been started successfully, you can list the members:
|
|
|
|
.List members of the cluster
|
|
====
|
|
[source,txt]
|
|
----
|
|
gfsh>list members
|
|
Name | Id
|
|
---------- | -----------------------------------------------------------------
|
|
LocatorOne | 10.99.199.24(LocatorOne:14358:locator)<ec><v0>:1024 [Coordinator]
|
|
ServerOne | 10.99.199.24(ServerOne:14401)<v1>:1025
|
|
----
|
|
====
|
|
|
|
Currently, we have not defined any regions in which to store our application's data:
|
|
|
|
.No Application Regions
|
|
====
|
|
[source,txt]
|
|
----
|
|
gfsh>list regions
|
|
No Regions Found
|
|
----
|
|
====
|
|
|
|
This is deliberate, since we are going to let the application drive its schema structure, both on the client
|
|
(application) as well as on the server-side (cluster). We cover this in more detail later in this chapter.
|
|
|
|
[[cloudfoundry-geode-cups]]
|
|
==== Creating a User-Provided Service
|
|
|
|
Now that we have PCF Dev and a small {geode-name} cluster up and running, it is time to create a user-provided service
|
|
to the external, standalone {geode-name} cluster that we started in <<cloudfoundry-geode-cluster,step 2>>.
|
|
|
|
As mentioned, PCF Dev offers MySQL, Redis and RabbitMQ services (among others). However, to use {geode-name} in the same
|
|
capacity as you would {pcc-name} when running in a production-grade PCF environment, you need to create a user-provided
|
|
service for the standalone {geode-name} cluster.
|
|
|
|
To do so, run the following `cf` CLI command:
|
|
|
|
.cf cups command
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf cups <service-name> -t "gemfire, cloudcache, database, pivotal" -p '<service-credentials-in-json>'
|
|
----
|
|
====
|
|
|
|
NOTE: It is important that you specify the tags (`gemfire`, `cloudcache`, `database`, `pivotal`) exactly as shown
|
|
in the preceding `cf` CLI command.
|
|
|
|
The argument passed to the `-p` command-line option is a JSON document (object) containing the credentials for our
|
|
user-provided service.
|
|
|
|
The JSON object is as follows:
|
|
|
|
.User-Provided Service Crendentials JSON
|
|
====
|
|
[source,json]
|
|
----
|
|
{
|
|
"locators": [ "<hostname>[<port>]" ],
|
|
"urls": { "gfsh": "https://<hostname>/gemfire/v1" },
|
|
"users": [{ "password": "<password>", "roles": [ "cluster_operator" ], "username": "<username>" }]
|
|
}
|
|
----
|
|
====
|
|
|
|
The complete `cf` CLI command would be similar to the following:
|
|
|
|
.Example `cf cups` command
|
|
====
|
|
[source,txt]
|
|
----
|
|
cf cups apacheGeodeService -t "gemfire, cloudcache, database, pivotal" \
|
|
-p '{ "locators": [ "10.99.199.24[10334]" ], "urls": { "gfsh": "https://10.99.199.24/gemfire/v1" }, "users": [{ "password": "admin", "roles": [ "cluster_operator" ], "username": "admin" }] }'
|
|
----
|
|
====
|
|
|
|
We replaced the `<hostname>` placeholder with the IP address of our standalone {geode-name} Locator. You can find
|
|
the IP address in the Gfsh `start locator` command output shown in the preceding example.
|
|
|
|
Additionally, the `<port>` placeholder has been replaced with the default Locator port, `10334`,
|
|
|
|
Finally, we set the `username` and `password` accordingly.
|
|
|
|
TIP: Spring Boot for {geode-name} (SBDG) provides template files in the `{docs-dir}/src/main/resources` directory.
|
|
|
|
Once the service has been created, you can query the details of the service from the `cf` CLI:
|
|
|
|
.Query the CF Dev Services
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf services
|
|
Getting services in org cfdev-org / space cfdev-space as admin...
|
|
|
|
name service plan bound apps last operation broker
|
|
apacheGeodeService user-provided boot-pcc-demo
|
|
|
|
|
|
$ cf service apacheGeodeService
|
|
Showing info of service apacheGeodeService in org cfdev-org / space cfdev-space as admin...
|
|
|
|
name: apacheGeodeService
|
|
service: user-provided
|
|
tags: gemfire, cloudcache, database, pivotal
|
|
|
|
bound apps:
|
|
name binding name status message
|
|
boot-pcc-demo create succeeded
|
|
----
|
|
====
|
|
|
|
You can also view the "apacheGeodeService" from Apps Manager, starting from the `Service` tab in your org and space:
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-services.png[]
|
|
|
|
By clicking on the "apacheGeodeService" service entry in the table, you can get all the service details, such as
|
|
the bound apps:
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-service-boundapps.png[]
|
|
|
|
You can also view and set the configuration:
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-service-configuration.png[]
|
|
|
|
This brief section did not cover all the capabilities of the Apps Manager. We suggest you explore its UI to see all
|
|
that is possible.
|
|
|
|
TIP: You can learn more about CUPS in the
|
|
{pivotal-cloudfoundry-docs}/devguide/services/user-provided.html[PCF documentation].
|
|
|
|
[[cloudfoundry-geode-app]]
|
|
==== Push and Bind a Spring Boot application
|
|
|
|
Now it is time to push a Spring Boot application to PCF Dev and bind the application to the `apacheGeodeService`.
|
|
|
|
Any Spring Boot `ClientCache` application that uses SBDG works for this purpose. For this example, we use the
|
|
https://github.com/jxblum/PCCDemo/tree/sbdg-doc-ref[PCCDemo] application, which is available in GitHub.
|
|
|
|
After cloning the project to your computer, you must run a build to produce the artifact to push to PCF Dev:
|
|
|
|
.Build the PCCDemo application
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ mvn clean package
|
|
----
|
|
====
|
|
|
|
Then you can push the application to PCF Dev with the following `cf` CLI command:
|
|
|
|
.Push the application to PCF Dev
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf push boot-pcc-demo -u none --no-start -p target/client-0.0.1-SNAPSHOT.jar
|
|
----
|
|
====
|
|
|
|
Once the application has been successfully deployed to PCF Dev, you can get the application details:
|
|
|
|
.Get details for the deployed application
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf apps
|
|
Getting apps in org cfdev-org / space cfdev-space as admin...
|
|
OK
|
|
|
|
name requested state instances memory disk urls
|
|
boot-pcc-demo stopped 0/1 768M 1G boot-pcc-demo.dev.cfdev.sh
|
|
|
|
|
|
$ cf app boot-pcc-demo
|
|
Showing health and status for app boot-pcc-demo in org cfdev-org / space cfdev-space as admin...
|
|
|
|
name: boot-pcc-demo
|
|
requested state: stopped
|
|
routes: boot-pcc-demo.dev.cfdev.sh
|
|
last uploaded: Tue 02 Jul 00:34:09 PDT 2019
|
|
stack: cflinuxfs3
|
|
buildpacks: https://github.com/cloudfoundry/java-buildpack.git
|
|
|
|
type: web
|
|
instances: 0/1
|
|
memory usage: 768M
|
|
state since cpu memory disk details
|
|
#0 down 2019-07-02T21:48:25Z 0.0% 0 of 0 0 of 0
|
|
|
|
type: task
|
|
instances: 0/0
|
|
memory usage: 256M
|
|
|
|
There are no running instances of this process.
|
|
----
|
|
====
|
|
|
|
You can bind the PPCDemo application to the `apacheGeodeService` using the `cf` CLI command:
|
|
|
|
.Bind application to `apacheGeodeService` using CLI
|
|
====
|
|
[source,txt]
|
|
----
|
|
cf bind-service boot-pcc-demo apacheGeodeService
|
|
----
|
|
====
|
|
|
|
Alternatively, you can create a YAML file (`manifest.yml` in `src/main/resources`) that contains
|
|
the deployment descriptor:
|
|
|
|
.Example YAML deployment descriptor
|
|
====
|
|
[source,yml]
|
|
----
|
|
\---
|
|
applications:
|
|
- name: boot-pcc-demo
|
|
memory: 768M
|
|
instances: 1
|
|
path: ./target/client-0.0.1-SNAPSHOT.jar
|
|
services:
|
|
- apacheGeodeService
|
|
buildpacks:
|
|
- https://github.com/cloudfoundry/java-buildpack.git
|
|
----
|
|
====
|
|
|
|
You can also use Apps Manager to view application details and bind and unbind additional services.
|
|
Start by navigating to the `App` tab under your org and space:
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-apps.png[]
|
|
|
|
From there, you can click on the desired application and navigate to the `Overview`:
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-app-overview.png[]
|
|
|
|
You can also review the application `Settings`. Specifically, we are looking at the configuration of the applicatinon
|
|
once it is bound to the `apacheGeodeService`, as seen in the `VCAP_SERVICES` environment variable:
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-app-settings-envvars.png[]
|
|
|
|
This JSON document structure is not unlike the configuration used to bind your Spring Boot `ClientCache` application
|
|
to the {pcc-name} service when deploying the same application to {pcf-name}. This is actually key if you want to
|
|
minimize the amount of boilerplate code and configuration changes when you migrate between different CloudFoundry
|
|
environments, even https://www.cloudfoundry.org/[Open Source CloudFoundry].
|
|
|
|
Again, SBDG's goal is to simply the effort for you to build, run, and manage your application, in whatever context
|
|
your application lands, even if it changes later. If you follow the steps in this documentation, you can realize
|
|
that goal.
|
|
|
|
[[cloudfoundry-geode-app-run]]
|
|
==== Running the Spring Boot application
|
|
|
|
All that is left to do now is run the application.
|
|
|
|
You can start the PCCDemo application from the `cf` CLI by using the following command:
|
|
|
|
.Start the Spring Boot application
|
|
====
|
|
[source,txt]
|
|
----
|
|
$ cf start boot-pcc-demo
|
|
----
|
|
====
|
|
|
|
Alternatively, you can also start the application from Apps Manager. This is convenient, since you can then tail
|
|
and monitor the application log file.
|
|
|
|
image::{images-dir}/pcfdev-appsmanager-org-space-app-logs.png[]
|
|
|
|
Once the application has started, you can click the https://boot-pcc-demo.dev.cfdev.sh/[VIEW APP] link
|
|
in the upper right corner of the `APP` screen.
|
|
|
|
image::{images-dir}/PCCDemo-app-screenshot.png[]
|
|
|
|
You can navigate to any of the application Web Service, Controller endpoints. For example, if you know the ISBN
|
|
of a book, you can access it from your Web browser:
|
|
|
|
image::{images-dir}/PCCDemo-app-book-by-isbn-screenshot.png[]
|
|
|
|
You can also access the same data from the Gfsh command-line tool. However, the first thing to observe is that our
|
|
application informed the cluster that it needed a Region called `Books`:
|
|
|
|
.Books Region
|
|
====
|
|
[source,txt]
|
|
----
|
|
gfsh>list regions
|
|
List of regions
|
|
---------------
|
|
Books
|
|
|
|
|
|
gfsh>describe region --name=/Books
|
|
..........................................................
|
|
Name : Books
|
|
Data Policy : partition
|
|
Hosting Members : ServerOne
|
|
|
|
Non-Default Attributes Shared By Hosting Members
|
|
|
|
Type | Name | Value
|
|
------ | ----------- | ---------
|
|
Region | size | 1
|
|
| data-policy | PARTITION
|
|
----
|
|
====
|
|
|
|
The PCCDemo app creates fake data on startup, which we can query in Gfsh:
|
|
|
|
.Query Books
|
|
====
|
|
[source,txt]
|
|
----
|
|
gfsh>query --query="SELECT book.isbn, book.title FROM /Books book"
|
|
Result : true
|
|
Limit : 100
|
|
Rows : 1
|
|
|
|
isbn | title
|
|
------------- | ---------------------
|
|
1235432BMF342 | The Torment of Others
|
|
----
|
|
====
|
|
|
|
[[cloudfoundry-geode-summary]]
|
|
=== Summary
|
|
|
|
The ability to deploy Spring Boot, {geode-name} `ClientCache` applications to {pcf-name} yet connect your application to
|
|
an externally managed, standalone {geode-name} cluster is powerful.
|
|
|
|
Indeed, this is a useful arrangement and stepping stone for many users as they begin their journey towards Cloud-Native
|
|
platforms such as {pcf-name} and using services such as {pcc-name}.
|
|
|
|
Later, when you need to work with real (rather than sample) applications, you can migrate your Spring Boot applications
|
|
to a fully managed and production-grade {pcf-name} environment, and SBDG figures out what to do, leaving you to focus
|
|
entirely on your application.
|