getting-started.md

Get started with Application Service Adapter

This get-started walkthrough gives you hands-on experience of Application Service Adapter: creating an org and space, deploying an app, and more.

Create orgs and spaces

You can use cf create-org and cf create-space the same way that you do with Tanzu Application Service. Under the hood, these commands create a Kubernetes namespace for each org and each space and propagate required resources into the namespace.

To create orgs and spaces:

1. Create the Cloud Foundry org and space.

   cf create-org ORG-NAME
   cf target -o ORG-NAME
   cf create-space SPACE-NAME
   cf target -s SPACE-NAME

   Where:

   • ORG-NAME is the name of the org you want to create.
   • SPACE-NAME is the name of the space you want to create.

2. (Optional) Assign the SpaceDeveloper role to other users in the Kubernetes cluster.

   cf set-space-role USER-NAME ORG-NAME SPACE-NAME SpaceDeveloper
   

   Where USER-NAME is the name of another user in the Kubernetes cluster.

Deploy a sample app

Use the cf CLI to deploy a sample app to the Application Service Adapter installation.

cf push APP-NAME

Where APP-NAME is the name of your app.

Route to an app

Applications automatically receive a default HTTP route unless pushed with the --no-route flag. This default route uses the name of the app as the route host name. To configure additional routes for the app that you pushed, use the cf CLI to map a route to your app.

cf map-route APP-NAME apps.example.com --hostname my-app

Create and bind to a user-provided service instance

Service credentials are provided to apps through user-provided service instances. See User-Provided Service Instances in the Cloud Foundry documentation.

To create and bind user-provided service instances, do the following:

1. Create a user-provided service instance containing the credentials necessary for accessing your service:

   cf create-user-provided-service SERVICE-INSTANCE-NAME -p '{"credential-name": "credential-value"}' --tags "list, of, optional, tags"

   Where SERVICE-INSTANCE-NAME is the name of your service instance.

2. Bind the service instance to your app:

   cf bind-service APP-NAME SERVICE-INSTANCE-NAME

3. Restart (or restage if a buildpack relies on the service) the app to make the service credentials available:

   cf restart APP-NAME

User-provided service instance credentials are provided to the app and staging tasks in two ways to support both existing Tanzu Application Service applications and next-generation frameworks, such as Spring Cloud Bindings:

• As part of the traditional Cloud Foundry VCAP_SERVICES environment variable
• As volume mounted secrets in accordance with the Service Bindings for Kubernetes specification
  • This workload projection handles the Service Bindings Package from Tanzu Application Platform

Applications relying on the VCAP_SERVICES presentation of service credentials typically look up service credential values by using either the "tags" or "labels" field in the payload. For more information, see Application environment variables. For a user-provided service instance, you can specify a list of tags during service creation by using the --tags flag. The "label" key can be specified by manipulating the corresponding CFServiceInstance resource directly by using the kubectl CLI patch command.

kubectl -n $(cf space $SPACE_NAME --guid) patch cfserviceinstance $(cf service $SERVICE_INSTANCE_NAME --guid) \
--patch '{"spec": {"serviceLabel": "custom-service-label"}}' --type=merge