CF CLI Cheatsheet

As mentioned in a previous post, CF (Cloud Foundry) is our preferred multi-cloud application PaaS solution, helping us to abstract away the infrastructure and focus on application innovation instead. It comes with a command line interface (CLI) to help with the deployment of applications.

The scope of this blog post is to give you a list of useful command lines to use for deploying your applications.

We don’t want to turn you into a superhero (we’ll tackle this in a future blog post), but we want to give you the CF CLI superpower.

To be able to use CF’s CLI, you will need to download and install it either following the GitHub repository instructions or the online documentation.

Once you have this setup, using your preferred terminal, have a look at the available commands:

cf --helpcf cf_command_name --help

Let’s say you want to push an application to your preferred cloud IaaS, like AWS, Azure or GCP. You already have automated your infrastructure as code using Terraform, but you want to easily be able to build, deploy, run, monitor and scale your application. For this, we will be deploying Cloud Foundry using BOSH and we will manage the applications using CF CLI commands.

LOGIN

Once you have CF CLI set up, use your preferred terminal and start by logging into CF.

You will need to specify the API endpoint to use either directly or when logging in:

cf api api_urlcf login [-a api_url] \
 [-u username] [-p password] \
 [-org org_name] [-s space_name]

When you login without specifying the username, password and the organisation and space names you want to log into, you will be prompted to add your credentials and choose the org and space where you want to deploy your applications.

Once logged in, you can check your current selected deployment environment (the API endpoint, org, and space) and the fact that you are logged in with the desired user, by running the following command:

cf target

MANAGING YOUR APPLICATION

Once you have an application ready to push, cd into its directory and run the following command to deploy the application:

cf push app_name \
 [-p ./artifact.jar] \
 [-m 128M] \
 [--random-route] \
 [--no-start]

If the application has the artifact path and the required memory specified via a manifest.yml file, simply push the app without specifying the artifact path and memory parameters.

A simple manifest.yml file for a Java application might look like this:

---applications:- name: app_nameinstances: 1host: app_namememory: 128Mbuildpack: java_buildpackpath: ./artifact.<war/jar>

Make sure for Java applications to define a manifest with java_buildpack specified as the buildpack entry.

When deploying an application, your application goes through the staging step, where its droplet is being built. Then a Diego cell is chosen for your droplet and the application is started unless otherwise specified.

A droplet is the Cloud Foundry unit of execution.

If you deployed your application and chose to add the --no-start parameter, then you will need to start your application yourself:

cf start app_name

In case you make changes to the environment variables (VCAP_SERVICES), in order to make sure these are set/injected correctly in the application container, you will need to restart your application:

cf restart app_name

CF makes it easy for you to scale up (by increasing the dedicate application memory) or out (by increasing the application instances) your application:

cf scale app_name \
 -m memory_size \
 -i instances

You can choose to deploy more than a single application. To list all your deployed applications in the current space, simply run:

cf apps

If you want to learn more about one single application you’ve deployed:

cf app app_name

THE MARKETPLACE

CF allows you access to a pool of services you can choose from to connect to your application.

Let’s say you require a specific database connected to your application.

You can view all the available services by calling:

cf marketplace# or simply:cf m

If you know what service you require, you can easily check its service plan like this:

cf m -s market_service_name

You will see a list of service plans available, some of which can be free and then you can bind this to your application. But later on this subject later in this blog post.

ENVIRONMENT VARIABLES (VCAP_SERVICES)

Are the means by which the Cloud Foundry (CF) runtime communicates with a deployed application about its environment.

You can view your application’s environment variables by simply calling:

cf env app_name

To set up an environment variable:

cf set-env app_name env_name env_value1,env_value2[,...]# make sure to restart your app for the env vars to take effect:
cf restart app_name

WIRING A SERVICE TO YOUR APPLICATION

Now that you’ve deployed your application and have seen what service you want to connect to it, let’s bind this service to your application.

First of all, you will need to provision a route service instance:

cf create-service market_service_name \
 market_service_plan_name \
 service_name

Now bind the route service to your application:

cf bind-service app_name service_name      # restart your app so that the app can have access to the env vars:     
cf restart app_name

You can view all the services you’ve created:

cf services

WIRING APPLICATIONS TOGETHER

Let’s imagine now that your architecture contains more than one microservice and that you want to use those microservices together.

Once you deployed the other microservice you require, create a user-provided service instance, which will allow you to connect to any legacy system within your CF.

# hook an app to another:     
cf create-user-provided-service user_provided_service_name \
 -p uri
# uri will wait for the app url, 
# e.g.: http://uri_to_reach_your_app      # now bind the app you want to this user-provided service:    
cf bind-service app_to_hook_name user_provided_service_name      # and restart your application for changes to take effect:
cf restart app_to_hook_name

REBUILDING THE APPLICATION DROPLET

A droplet is an archive within Cloud Foundry that contains the application ready to run on Diego. A droplet is the result of the application staging process.

Application droplets need to be rebuilt when there are new dependencies to pull in:

cf restage app_name

REVERSE-ENGINEERING A MANIFEST FROM A RUNNING APPLICATION

For an application that has been successfully deployed, you can reverse-engineer its manifest by creating or saving it using the following command:

cf create-app-manifest app_name \
 [-p ./path_to_manifest/manifest.yml]

SECURITY GROUPS

Application Security Groups (ASGs) are a collection of egress rules that specify the protocols, ports, and IP address ranges where the application or task instances send traffic.

Or, in other words, ASGs are virtual firewalls that control egress/outbound traffic for applications.

The way you would create an ASG is as follows:

cf create-security-group sg_name path_to_sg_json_file      # bind the SG to an org and space:     
cf bind-security-group sg_name org_name space_name      # for changes to take effect, restart the app:
cf restart app_name

To see all security groups running and bound to your targeted ops and space, run the following command:

cf security-groups

To check the definition for a security group:

cf security-group app_security_group_name

Staging Security Groups

Staging security groups bound during staging when the application droplet gets created. Admins can define a staging ASG for an application and task staging, with more permissive rules.

To list all staging security groups:

cf staging-security-groups

Running Security Groups

Admins can define a running ASG for an application and task runtime, with less permissive rules.

To see all system-wide running SGs:

cf running-security-groups

To lock down all of the egress traffic for a running application

cf unbind-running-security-group app_security_group_name      # restart your app to see the effects:
cf restart app_name-log-drain

LOG DRAINS

CF does not persist logs. For long-term storage of logs for log analysis, you will need to use 3rd party tools via CF’s capability to drain application logs to some destination.

To create a log drain, follow the below commands:

cf create-user-provided-service app_name-log-drain \
 -l syslog://3rd_party_syslog_endpoint     
# `3rd_party_syslog_endpoint = host:port`     
# of external 3rd party syslog service,     
# like Papertrail or Splunk      # bind your application to this log drain
cf bind-service app_name app_name-log-drain      # restart your application for changes to take effect:
cf restart app_name

LISTING ALL ROUTES IN YOUR ORG AND SPACE

cf routes

BLUE-GREEN DEPLOYMENTS

In order to achieve zero downtime when upgrading, when managing multiple versions of your app, traffic is being divided up by the number of instances bound to the route.

Blue-green deployment is a technique that reduces downtime and risk by running two identical production environments called Blue (the old version of the application) and Green (the new version of the application).

Let’s imagine you have already pushed an older version of your application to production and now you have some new features you want to bring in, so a newer version of your application.

The way to go forward with zero downtime is by having a blue-green deployment:

# scale out your app to multiple instances:
cf scale app_name -i 2      # record the subdomain (host) for your app:     
cf routes      # push the new app version by declaring     
# your production route as `subdomain-temp`:  
cf push app_name-v2 \
-p ./app-v2.jar \
-m 768M \
--hostname initial_app_hostname-temp \
--no-start

Now you will need to bind your v2 application to all the services your application is bound to and map the routes:

# bind the new version app to     
# any dependency apps the old app has:     
cf bind-service app_name-v2 app_name      cf start app_name-v2      # map production route to the new app v2:  
cf map-route app_name-v2 \
initial_app_domain \
--hostname initial_app_hostname \
[--port public_facing_port_to_the_app]

Redirect now v1 application traffic to v2 application:

# scale down your initial app:
cf scale initial_app_name -i 1      # scale out your new app and you will see most traffic    
# leaning in favor for this app:
cf scale app_name-v2 -i 2      # to cut over from the old app,     
# unmap the public route from your old app,     
# thus moving all traffic to app v2:     
cf unmap-route initial_app_name initial_app_domain \
-n initial_app_hostname

And finally, make sure to clean up after your blue-green deployment:

# clean up by unmapping the temporary route:
cf unmap-route app_name-v2 initial_app_domain \
-n initial_app_hostname-temp      # delete the old app:
cf delete app_name      #rename app v2 to app_name:
cf rename app_name-v2 app_name      # restart the app:
cf restart app_name      # scale down app:
cf scale app_name -i 1

AUTOSCALING AND PERFORMANCE TESTING

The marketplace offers an automatic application scaler service.

These services look at your application metrics and scale the application up or down on your behalf during periods of higher and lower traffic.

This is how you can provision an autoscaler service instance:

cf create-service app-autoscaler \
market_service_plan_name \
service_name      # bind the created service to the app you want:
cf bind-service app_name service_name      # restart your app:
cf restart app_name

For performance testing and to see the application autoscaler in progress, let’s generate load on your application:

cf m -s loadimpact

MONITORING YOUR APPLICATION

There are different ways you can monitor your application and we will go through some in the next section.

One way to monitor your application is by checking the application health/status, calling this:

cf app app_name

Another way is to troubleshoot your application or to view its events, as follows:

cf events app_name

And last but not least, you can monitor your application by checking its logs:

# view most recent logs:
cf logs app_name --recent      # tail the logs = view logs in real-time:
cf logs app_name      # filters logs containing API (Cloud Controller logs)
# and CELL (Diego Cell logs);     
# observe this when you scale up & down/out your app:
cf logs app_name | grep "API\|CELL"     # on Windows:     
cf logs app_name | findstr "API CELL"      # filter logs excluding Router logs:
cf logs app_name | grep -v RTR

You can also monitor the state of your application, including your application instances and their CPU usage via the following CF CLI plugin:

# head over to CF plugins catalog:     
# https://plugins.cloudfoundry.org/     
cf top

CF integrates well with application performance monitoring solutions like NewRelic or AppDynamics, making it thus easy to monitor the performance of your application:

# these solutions add overhead to your app     
# so you need to scale up your app in terms of memory:
cf scale app_name -m 1G -i 1      cf create-user-provided-service newrelic_service_name \
-p newrelic_license_key     
# ! newrelic_service_name must be `newrelic` 
    
# OR use the newrelic marketplace service:     
cf create-service newrelic standard newrelic_service_name      cf bind-service app_to_hook_name newrelic_service_name
      
# restage app so that droplet can be rebuilt     
# to include the agent:
cf restage app_name

BUILDPACKS

Buildpacks produce the droplet needed to run our application.

They typically examine your apps to determine what dependencies to download and how to configure the apps to communicate with bound services.

When you push an app, Cloud Foundry automatically detects an appropriate buildpack for it. This buildpack is used to compile or prepare your app for launch.

You can explore system buildpacks, by calling this:

cf buildpacks

If you want to use a custom buildpack, you can do so by calling the following:

# deploy an app with the latest custom buildpack:
cf push app_name -p artifact_path \
-b custom_buildpack_git_repo

The system provided Java buildpack is offline and offers a limited set of dependencies. For both the online and offline packages, unless the Java version is specified, the application is run with the latest Java version available to the buildpack.

In order to reconfigure the Java runtime that the Java buildpack provisions for your application, follow these steps:

# set env variables that you want your app to read:
cf set-end app_name JBP_CONFIG_OPEN_JDK_JRE \     
"{jre: { version: your_desired_version}}"     # where e.g. your_desired_version = 1.8.0_45      # now the droplet needs to be rebuilt:
cf restage app_name

SERVICE BROKERS

Cloud Foundry has a wide marketplace offer, but it also allows you to extend it with managed services.

Managed services can easily be plugged in into CF’s extensible platform and made available in the service marketplace via the space-scoped service brokers feature. After pushing the service broker application to CF, set the following environment variables and create your service broker:

cf set-env service_app_name SERVICE_ID service_broker_id     
cf set-env service_app_name SERVICE_NAME service_name     
cf set-env service_app_name PLAN_ID service_plan_id      cf start service_app_name      cf create-service-broker service_broker_name \
username password \
service_app_name_url \
--space-scoped

Let’s imagine you have just created a MongoDB service broker and you have provisioned a MongoDB AWS instance. You will need now to set up the connectivity to that by defining the MONGODB_HOST environment variable for your service broker (the hostname or IP address of that AWS instance):

cf set-env service_broker_name \
MONGODB_HOST mongodb_aws_instance_ip_address      cf set-env service_broker_name \
MONGODB_PASSWORD mongodb_aws_instance_password      cf restart service_broker_name

You can list all your available service brokers by calling this:

cf service-brokers     # see service broker access level:
cf service-access

To delete a service broker, follow these steps:

# the service created to bind     
# your app to the service-broker:
cf delete-service service_name      cf delete-service-broker service_broker_name      cf delete service_app_name

ROUTE SERVICES

These are a kind of marketplace services that developers use to process traffic addressed to an application or to filter/transform an application’s requests and responses by binding the application’s route to a service instance (e.g.: authentication, rate limiting, caching).

You can create a user-provide route service like this:

cf create-user-provided-service route_service_name \
-r https://uri_to_reach_your_route_service_app

You can now bind the user-provided route service to your intercepted application in the following way:

# capture the domain for your route-service and the     
# hostname of the app you are going to intercept:
cf routes      # bind it:
cf bind-route-service route_service_domain \
route_service_name \
--hostname app_intercepting_hostname

Once you are done with this, don’t forget to clean up after yourself:

cf unbind-route-service route_service_domain \
route_service_name \
--hostname app_intercepting_hostname

Tosum up, the above is a list of CF CLI commands you can use to easily deploy and manage your applications within Cloud Foundry.

A summary of the above can be found here.