Accessing Services with SSH
Page last updated:
This page assumes you are using cf CLI v6.15.0 or later.
This topic describes how to gain direct command line access to your deployed service instance. For example, you may need access to your database to execute raw SQL commands to edit the schema, import and export data, or debug application data issues.
To establish direct command line access to a service, you deploy a host app and utilize its SSH and port forwarding features to communicate with the service instance through the app container. The technique outlined below works with any TCP service, such as MySQL or Redis.
In your terminal window, log in to your deployment with
- List the marketplace services available using the cf marketplace command. In this example, we create a MySQL service instance.
$ cf marketplace mysql 100mb MySQL databases on demand
- Create your service instance. As part of the create-service command, indicate the service name, the service plan, and the name you choose for your service instance.
$ cf create-service MySQL 100mb MY-DB
To push an app that will act as the host for the SSH tunnel, push any app that will successfully deploy to Cloud Foundry.
Note: Your app must be prepared before you push it. See the Deploy an Application topic for details on preparing apps for deployment.
- Push your app.
$ cf push YOUR-HOST-APP
- Enable SSH for your app.
$ cf enable-ssh YOUR-HOST-APP
Note: In order to enable SSH access to your app, SSH access must also be enabled for both the space that contains the app and Cloud Foundry. See the Application SSH Overview topic for further details.
To establish SSH access to your service instance, you need to create a service key that contains critical information for configuring your SSH tunnel.
- Create a service key for your service instance using the cf create-service-key command.
$ cf create-service-key MY-DB EXTERNAL-ACCESS-KEY
- Retrieve your new service key using the cf service-key command.
$ cf service-key MY-DB EXTERNAL-ACCESS-KEY Getting key EXTERNAL-ACCESS-KEY for service instance MY-DB as email@example.com
Configure an SSH tunnel to your service instance using cf ssh. Tailor the example command below with information from your service key.
$ cf ssh -N -L 63306:us-cdbr-iron-east-01.mysql.net:3306 spring-music
- Use any available local port for port forwarding. For example,
us-cdbr-iron-east-01.mysql.netwith the address provided under
hostnamein the service key retrieved above.
3306with the port provided under
spring-musicwith the name of your host app.
Note: Because the SSH tunnel may time out, run
cf ssh in the foreground and restart it if it exits.
To establish direct command-line access to your service instance, use the relevant command line tool for that service. This example uses the MySQL command line client to access the MySQL service instance.
$ mysql -u b5136e448be920 -h 0 -p -D ad_b2fca6t49704585d -P 63306
b5136e448be920with the username provided under
usernamein your service key.
-h 0indicates to
mysqlto connect to your local machine.
mysqlto prompt for a password. When prompted, use the password provided under
passwordin your service key.
ad_b2fca6t49704585dwith the database name provided under
namein your service key.
-P 63306indicates to
mysqlto connect on port 63306.