Feature Flags service Demo Application is a simple Spring Boot application that consumes the Feature Flags service on SAP BTP, Cloud Foundry environment. It implements a feature toggle (evaluation call to the Feature Flags service) and exposes this feature toggle through a Web user interface. There is also one REST end-point that reads the value of VCAP_SERVICES
environment variable.
-
You have set up Maven 3.0.x.
-
You have an SAP BTP enterprise (productive) account on Cloud Foundry environment.
💡NOTE: You can also use a trial account but some functionalities won't be available for you.
-
You have a space on a Cloud Foundry instance - productive or trial.
-
You have set up the curl plug-in for
cmd
. -
You have installed cf CLI.
💡NOTE: This guide uses the eu20 region (https://emea.cockpit.btp.cloud.sap/cockpit#).
To use a different SAP BTP region, you need to modify the domain in the requests. See: Cloud Foundry Regions and API Endpoints
Follow the steps below to run Feature Flags Demo Application
on SAP BTP, Cloud Foundry environment.
- 1. Build the feature-flags-demo Application
- 2. Edit application name in manifest file
- 3. Deploy feature-flags-demo on SAP BTP
- 4. Create a Service Instance of Feature Flags service
- 5. Call the feature-flags-demo Application's /vcap_services End-Point
- 6. Bind feature-flags-demo to feature-flags-instance
- 7. Restage feature-flags-demo
- 8. Ensure that feature-flags-instance is bound to feature-flags-demo
- Accessing the Demo Application
- Accessing the Feature Flags Dashboard
- 9. Evaluate a Missing Feature Flag
- 10. Create a New Boolean Feature Flag
- 11. Evaluate the Newly Created Boolean Feature Flag
- 12. Enable the Boolean Feature Flag
- 13. Verify that the Boolean Feature Flag is Enabled
- 14. Create a New String Feature Flag
- 15. Evaluate the Newly Created String Feature Flag
- 16. Enable the String Feature Flag
- 17. Verify that the String Feature Flag is Enabled
- 18. Specify Direct Delivery Strategy of a Variation of the String Flag
- 19. Evaluate the String Feature Flag Using Identifier
Run the following commands, consequently:
$ git clone [email protected]:SAP/cloud-cf-feature-flags-sample.git
$ cd cloud-cf-feature-flags-sample
$ mvn clean install
Note: Alternatively, you can use the Eclipse IDE. Choose the
clean install
goal from the Run As > Maven Build... menu.
It's quite possible that someone else has already deployed the Feature Flags Demo Application
with the name feature-flags-demo (as it is currently set in the manifest.yml
file).
Cloud Foundry does not allow two applications with the same name to be deployed in the same region! Therefore, we highly recommend that you change the application name in the manifest.yml
file before deploying. For example:
---
applications:
- name: feature-flags-demo123
path: target/feature-flags-demo.jar
💡NOTE: Use the modified value in all commands that require application name, as well as when requesting the application in a browser or via curl
.
-
Log in to your Cloud Foundry landscape. (The
eu20
region is just an example.) Run:$ cf login -a https://api.cf.eu20.hana.ondemand.com
-
Choose your subaccount (org) and space.
-
Deploy the application. Run:
$ cf push
Run the following command:
$ cf marketplace
Result:
-----
Getting services from marketplace in org <ORG_ID> / space <SPACE> as <USER_ID>...
OK
service plans description
...
feature-flags lite, standard Feature Flags service for controlling feature rollout
...
NOTE: If you're using a trial account, the only available service plan will be lite
.
-
For a productive account, run:
$ cf create-service feature-flags standard feature-flags-instance
-
For a trial account, run:
$ cf create-service feature-flags lite feature-flags-instance
Note: Alternatively, you can use the SAP BTP cockpit. See Create a Service Instance.
Note: Expect to receive an empty JSON code - {}.
The /vcap_services
end-point simply returns the content of the VCAP_SERVICES environment variable. As for now, there is no service instance bound to feature-flags-demo
, thus you receive an empty JSON.
In the command you use the following URL: \<application_URL\>/vcap_services
.
To find the value of \<application_URL\>
, go to the SAP BTP cockpit > feature-flag-demo > Overview > Application Routes.
To call the application, run (for example):
$ curl https://feature-flags-demo.cfapps.eu20.hana.ondemand.com/vcap_services
$ cf bind-service feature-flags-demo feature-flags-instance
-----
Binding service feature-flags-instance to app feature-flags-demo in org <ORG_ID> / space <SPACE> as <USER_ID>...
OK
TIP: Use 'cf restage feature-flags-demo' to ensure your env variable changes take effect
Note: Alternatively, you can use the SAP BTP cockpit. See Bind Your Application to the SAP Feature Flags Service Instance.
Restage feature-flags-demo
application so the changes in the application environment take effect.
$ cf restage feature-flags-demo
Note: Expect to receive the injected environment variables by the Feature Flags service.
$ curl https://feature-flags-demo.cfapps.eu10.hana.ondemand.com/vcap_services
Sample JSON response:
{
"feature-flags": [
{
"credentials": {
"x509": {
"certificate": "...",
"key": "...",
"clientid": "...",
"...": "..."
},
"password": "aa_12345678XYZZZZZ000mnopRE+qs0e=",
"uri": "https://feature-flags.cfapps.eu20.hana.ondemand.com",
"username": "sbss_x234osj//pmabsuskr6nshmb2arw6dld4hfb3cj4m2bonkqmm3ts6c68mdpzxz2fma="
},
"syslog_drain_url": null,
"volume_mounts": [ ],
"label": "feature-flags",
"provider": null,
"plan": "standard",
"name": "feature-flags-instance",
"tags": [
"feature-flags"
]
}
]
}
The web interface of the demo application will be accessed multiple times throughout this tutorial. Here is how to open it:
- Go to the SAP BTP cockpit.
- Navigate to the
feature-flags-demo
application overview. - Open the link from the Application Routes section. For example:
https://feature-flags-demo-happy-bear.cfapps.eu20.hana.ondemand.com
- The Evaluation Form opens.
The Feature Flags Dashboard
will be accessed multiple times throughout this tutorial. Here is how to open it:
- Go to the SAP BTP cockpit.
- Navigate to your subaccount.
- Create a subscription to Feature Flags Dashboard. To do that, create an instance of the Feature Flags service, with plan
dashboard
. - Access Feature Flags Dashboard from the list of subscribed applications.
- Select the service instance you are currently working with.
💡NOTE: The dashboard URL always has the following pattern:
https://<subdomain\>.feature-flags-dashboard.cfapps.eu20.hana.ondemand.com/manageinstances/<instance-id\>
The is a unique ID of your Feature Flag service instance.
Note: Expect the feature flag to be missing.
- Open the demo application as described here.
- Enter a feature flag with a random name, for example
my-boolean-flag
. - Choose Evaluate.
- The result should state that a feature flag with this name is missing.
- Open the
Feature Flags Dashboard
as described here. - Choose New Flag.
- Fill in the required fields. For example:
- Name:
my-boolean-flag
- Description:
Super cool feature
- State:
OFF
- Name:
- Choose Save.
Note: Expect the variation to be
false
.
- Open the demo application as described here.
- Enter the Boolean feature flag name.
- Choose Evaluate.
- The result should state that the feature flag is of type
BOOLEAN
and its variation isfalse
.
- Open the
Feature Flags Dashboard
as described here. - Enable the Boolean feature flag using the switch in the Active column.
Note: Expect the variation to be
true
.
- Open the demo application as described here.
- Enter the Boolean feature flag name.
- Choose Evaluate.
- The result should state that the feature flag is of type
BOOLEAN
and its variation istrue
.
The next procedures (14 - 19) are only applicable for productive accounts, which means plan
standard
.
- Open the
Feature Flags Dashboard
as described here. - Choose New Flag.
- Fill in the required fields. For example:
- Name:
my-string-flag
- Description:
Coolest of features
- Type:
String
- State:
OFF
- Name:
- Enter the following values as different variations of the flag:
- Var. 1:
variation-when-inactive
- Var. 2:
variation-when-active
- Var. 3 (choose the Add button with the '+' sign to add a new field):
variation-for-friends-and-family
- Var. 1:
- From the Default Variation, open the Deliver combo box and select
Var. 2
. - Choose Save.
Note: Expect the variation to be
variation-when-inactive
.
- Open the demo application as described here.
- Enter the string feature flag name.
- Choose Evaluate.
- The result should state that the feature flag is of type
STRING
and its variation isvariation-when-inactive
.
- Open the
Feature Flags Dashboard
as described here. - Enable the string feature flag using the switch in the Active column.
Note: Expect the variation to be
variation-when-active
.
- Open the demo application as described here.
- Enter the string feature flag name.
- Choose Evaluate.
- The result should state that the feature flag is of type
STRING
and its variation isvariation-when-active
.
- Open the
Feature Flags Dashboard
as described here. - Select the string feature flag.
- Choose the Edit Flag button.
- Go to the Strategy section, subsection Direct Delivery, and choose the '+' button.
- Select Var. 3 from the combobox and enter
friends-and-family
in the text input. - Choose Save.
Note: Expect the variation to be
variation-for-friends-and-family
.
- Open the demo application as described here.
- Enter the string feature flag name.
- For the Identifier (optional) field, enter
friends-and-family
. - Choose Evaluate.
- The result should state that the feature flag is of type
STRING
and its variation isvariation-for-friends-and-family
.
Once Direct Delivery is configured, the Feature Flags service requires providing an identifier. If such is not present, an error is thrown.
💡NOTE: variation-when-active
is returned for all identifiers - except for those explicitly configured in the Feature Flags Dashboard
for which the provided rules apply (like the friends-and-family
identifier).
Refer to the contrubuting guideline.
Refer to the SAP Open Source Code of Conduct.
See LICENSE file.