btp-cloud-foundry

name	btp-cloud-foundry
description	SAP BTP Cloud Foundry runtime — CF CLI operations, deployment, service lifecycle, troubleshooting, manifest authoring.
trigger	["cloud foundry","cf push","cf deploy","cf org","cf space","cf marketplace","cf logs","manifest.yml","buildpack","cf route","btp cf","cf create-service","cf bind-service"]
prerequisites	["CF CLI v8+ installed (https://github.com/cloudfoundry/cli/releases)","BTP subaccount with Cloud Foundry environment enabled","Org and space already created in BTP Cockpit","Network access to CF API endpoint"]

BTP Cloud Foundry — Deploy, Manage, & Troubleshoot

1. Login and Target

# Login to BTP CF API (region-specific endpoint)
cf login -a https://api.cf.us10.hana.ondemand.com

# Target specific org and space
cf target -o my-org -s dev

# Verify current target
cf target

2. Deploy Application

# Standard push (uses manifest.yml if present)
cf push my-app

# Push with custom manifest
cf push my-app -f manifest-prod.yml

# Push with specific buildpack
cf push my-app -b nodejs_buildpack

# Push without starting (for binding services first)
cf push my-app --no-start

3. Author manifest.yml

---
applications:
- name: my-cap-app
  buildpack: nodejs_buildpack
  memory: 256M
  disk_quota: 512M
  instances: 2
  routes:
  - route: my-cap-app.cfapps.us10.hana.ondemand.com
  services:
  - my-xsuaa
  - my-destination
  - my-hdi-container
  env:
    NODE_ENV: production
    CDS_ENVIRONMENT: production
  health-check-type: http
  health-check-http-endpoint: /health

4. Manage Services

# List marketplace services and plans
cf marketplace
cf marketplace -s xsuaa

# Create service instance
cf create-service xsuaa application my-xsuaa -c xs-security.json
cf create-service hana hdi-shared my-hdi-container
cf create-service destination lite my-destination

# Bind service to app
cf bind-service my-app my-xsuaa

# Create and view service keys
cf create-service-key my-xsuaa my-key
cf service-key my-xsuaa my-key

# List all services in space
cf services

5. Zero-Downtime Deploy (Blue-Green)

# Deploy new version with temporary route
cf push my-app-green

# Map production route to new version
cf map-route my-app-green cfapps.us10.hana.ondemand.com -n my-app

# Unmap route from old version
cf unmap-route my-app cfapps.us10.hana.ondemand.com -n my-app

# Stop and rename old version
cf stop my-app
cf rename my-app my-app-old
cf rename my-app-green my-app

6. Troubleshoot

cf logs my-app --recent    # recent logs
cf logs my-app             # stream live logs
cf app my-app              # app status and instances
cf events my-app           # crash/start/stop events
cf env my-app              # VCAP_SERVICES and env vars
cf enable-ssh my-app && cf ssh my-app   # SSH into container
cf restart my-app          # restart with same droplet
cf restage my-app          # rebuild droplet (needed after new bindings)

7. Deploy CAP App with mta.yaml

mbt build                              # build MTA archive
cf deploy mta_archives/my-cap-app_1.0.0.mtar   # deploy to CF
cf mta my-cap-app                      # verify deployment

Verification

# Check app is running
cf app my-app
# Expected: #0 running, state=RUNNING

# Health check endpoint
curl -s https://my-app.cfapps.us10.hana.ondemand.com/health
# Expected: 200 OK

# Verify service bindings
cf env my-app | grep -A5 VCAP_SERVICES
# Expected: JSON with bound service credentials

# Check org quota usage
cf org-quota my-org

Pitfalls

1. App crashes immediately after push (401 on all endpoints)

   • Cause: XSUAA service not bound before app start, or binding created after staging.
   • Solution: cf push my-app --no-start → cf bind-service my-app my-xsuaa → cf start my-app.

2. Memory quota exceeded

   • Cause: BTP CF trial accounts limited to 1GB total. Paid accounts have org-level quotas.
   • Solution: Check cf org-quota my-org. Reduce memory in manifest or stop unused apps.

3. Route collision during blue-green deploy

   • Cause: Both old and new apps mapped to same hostname simultaneously without unique temp name.
   • Solution: Use -green suffix for new version. Map route only after green is healthy.

4. SSH fails with "not enabled"

   • Cause: SSH disabled by default on BTP CF for security.
   • Solution: cf enable-ssh my-app then cf restage my-app. Disable in production.

5. Restage needed after binding new service

   • Cause: VCAP_SERVICES env vars are injected at staging time, not runtime.
   • Solution: After cf bind-service, run cf restage my-app to pick up new credentials.

6. Buildpack version mismatch

   • Cause: SAP buildpacks have version-specific Node.js/Java requirements. Unpinned buildpack auto-updates may break.
   • Solution: Pin buildpack version in manifest: buildpack: nodejs_buildpack#1.8.0.

7. Service plan not available in region

   • Cause: Some BTP service plans are region-specific (e.g. HANA not available in all regions).
   • Solution: Check cf marketplace -s <service> to verify plan availability before creating.