Tips and Tricks

Making a Change (in Ruby)

Test Driving

First write a test for the behavior you want. It should fail at this point.

To run only this test via command-line:

be rspec <full_path_with_file_name_and_suffix>:<test_line_number>

If you need to add a break-point, just add the following in your code:

binding.pry

Then test the entire file:

be rspec <full_path_with_file_name_and_suffix>

Alternatively, you can run the individual test and test file in Rubymine, using the key-bindings configured by sprout-wrap

Once those tests are passing, run the default rake task. This will run all tests, and then run rubocop.

be rake

If there's an issue to fix for rubocop or a particular spec file, you can run them individually:

Just RuboCop: (~/workspace/cf-release/src/cloud_controller_ng)

be rubocop

Just SPECS: (~/workspace/cf-release/src/cloud_controller_ng)

be rspec spec/

Getting a bosh-lite

Preferred - Claim a bosh-lite from GCP pool

The following command will claim a bosh-lite from a pool on GCP and print help text showing how to interact with that bosh-lite and deploy CF.

# alias from sprout-capi
claim_bosh_lite
# when finished
unclaim_bosh_lite <ENV_NAME>

Alternatively - Use Virtualbox on your workstation

This command will spin up a bosh-lite as a Virtualbox VM on your local workstation. We've had stability issues with Virtualbox in the past, so the GCP approach is preferred.

# alias from sprout-capi
recreate_gosh_lite
cd ~/workspace/capi-env-pool/vbox/
# direnv will show help text to deploy a CF

Using the CF CLI

Logging in

cf auth <user> <password> # credentials: admin/admin

Creating an org (if you haven't already)

cf create-org <orgname>
cf target -o <orgname> # future commands will operate on this org

Creating a space if you haven't already

cf create-space <spacename>
cf target -s <spacename> # future commands will operate on this space

Lists current services on the space cf services

Push the CATs dummy service broker

cd ~/workspace/cf-release/src/acceptance-tests/assets/service_broker/
ruby setup_new_broker.rb

If you have a different broker than the above and want to set it up:

Create service broker cf create-service-broker async-broker <broker-user> <broker-pw> <broker-url>

Update service broker (if you've changed the catalog/credentials of a service broker)

cf update-service-broker async-broker <broker-user> <broker-pw> <broker-url>

Check for service offerings available in marketplace: cf marketplace

Enable service offerings for use. Service names are declared in the marketplace cf enable-service-access <service-name>

Creating service instance once the service broker is created:

bash
cf create-service <service-name> <service-plan> <service-instance-name>

For the CATs service broker, fake-plan-<guid> is for synchronous service instances:

bash
cf cs fake-service fake-plan-<guid> <service-instance-name>
# Make sure the service instance was created successfully
cf services

For an asynchronously provisioned service instance, use fake-async-plan-<guid> instead:

bash
cf cs fake-service fake-async-plan-<guid> <service-instance-name>
# Make sure the service instance was created successfully
cf services
# To watch progress of async service instance (in another terminal):
watch -n 1 cf s

Operation	Command
list brokers	`cf service-brokers`
create service instance (sync)	`cf create-service fake-service fake-plan <service-instance-name>`
create service instance (async)	`cf create-service fake-service fake-async-plan <service-instance-name>`
update service instance plan	`cf update-service <service-instance-name> -p <new-plan-name>`
rename service instance name	`cf rename-service <old-instance-name> <new-instance-name>`

Mounting SSH Key

If you get a ”Permission denied (publickey)”, insert you USB memory stick and add your ssh key by (select the one which starts with id_rsa, and has no suffix):

bash
ssh-add -t 9h ssh-add -t 9h /Volumes/<your_volume_name>/<your_id_RSA>

This would make your key available for 9 hours, and you can now eject your memory card

Committing a Change to Cloud Controller

Navigate to cloud-controller-ng: (~/workspace/cf-release/src/capi-release/cloud_controller_ng)

First, run all the unit tests and check https://capi.ci.cf-app.com/. If the pipeline is red, don't push changes to cloud_controller_ng.

bash
#assign git pair
git duet <pair1> <pair2> 

#add changes patch by patch
git add -p 

git ci

#rebase, you can also use --rebase
git pull -r 
git push

The commit will start making its way through the CAPI pipeline. If the Cloud Controller unit tests pass, CC will be bumped in capi-release, and capi-release will continue to make its way through the pipeline. If it passes acceptance tests and https://canibump.cfapps.io/ is green, cf-release will be bumped with the new changes in capi-release.

Bumping cf-release manually

You may find yourself wanting to bump a submodule in cf-release manually (for example, if there is special coordination that needs to happen). You can accomplish that by following this workflow after pushing the commit in the relevant submodule (e.g. capi-release).

#go to CF release
cd ~/workspace/cf-release
git pull -r

#update the release to central status
./scripts/update 

#return to capi-release
cd ~/workspace/cf-release/src/capi-release

#check your status - you should show detached head
git st 

#shows the available branches
git branch 

#checkout master, can replace co with checkout
git co master 

#Return to CF release
cd ~/workspace/cf-release

#should show new changes
git st 

#add your changes
git add . 
./scripts/commit_with_shortlog
git push

Running Acceptance Tests

make sure bosh_lite is running and has the latest CF changes

Navigate to cf-release/src/github.com/cloudfoundry/cf-acceptance-tests/

integration_config.json should contain information about your specific deployment. Changing the CONFIG variable can allow tests to run against various environments e.g. local bosh-lite, CI deployment on AWS, etc

bash
GOPATH=~/workspace/cf-release/src #setting GOPATH
CONFIG=‘pwd’/integration_config.json bin/test_default services

If you have run sprout-capi, the cats alias will be available to easily rerun cats from any directory. v3-cats will run the v3 suite.

Updating/Adding to Acceptance Tests

CATs are the CF acceptance tests and are our integration tests for Cloud Foundry.

At times it is appropriate to add tests for CATs. Usually this will be when an integration test is required to properly test a feature. A good way to judge whether a new test is necessary is to see if the feature added requires more components than just the cloud controller to succeed. For example pushing an app onto Cloud Foundry requires cloud controller, diego, as well as a few other components.

Updating Documentation

There are a few documentation websites, each of which should be updated differently. If you wish to update "Doc Book", e.g. api-v#.#.html - you should:

Update the equivalent file in ~/workspace/docs-services/api-v#.#.html.md.erb
Compile it in ~/workspace/docs-book-cloudfoundry - see README.md there for more detail
Send a PR to the docs team with your changes

If you wish to update the v2 API docs, write a test in cf-release/src/cloud_controller_ng/spec/api/documentation to represent the desired documentation.

Documentation for the v3 API live in cf-release/src/cloud_controller_ng/docs. Documentation content lives in cf-release/src/cloud_controller_ng/docs/source.

To view the docs locally while editing, run the following in the docs directory:

bundle install
npm install
npm start

This will start a server on http://localhost:8000 where the current content can be seen.

Other Important notes

Always work off the develop branch of cf-release!
Each time you make a documentation change in CC, you will need to change the API_FOLDER_CHECKSUM in the ~/workspace/cf-release/src/cloud_controller_ng/spec/api/api_version_spec.rb file. In order to quickly generate a new hash run the following command, and copy the expected hash from the failure:

bash
cd ~/workspace/cf-release/src/cloud_controller_ng
be rspec spec/api/api_version_spec.rb

If you wish to open the IDE from a specific point in the CLI, use:

mine . to open RubyMine
subl . to open Sublime

Problem Solving

if you try to rake and receive the following message:

bash
Using postgres
psql -U postgres -c 'drop database if exists cc_test;'
ERROR:  database "cc_test" is being accessed by other users
DETAIL:  There are 10 other sessions using the database.
rake aborted!
Command failed with status (1): [psql -U postgres -c 'drop database if exis...]
lib/tasks/db.rake:89:in `block (2 levels) in <top (required)>'
Tasks: TOP => default => spec => db:recreate => db:drop
(See full trace by running task with --trace)

Solution: you will need to close connection usage --> close terminal and debug session

If you try to push and get the following message:

bash
Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Solution: Mount SSH key, see section above

Kill Commands and what they mean:

https://pthree.org/2012/08/14/appropriate-use-of-kill-9-pid/

Killing the Bosh Locks (So you can delete a deployment when your task won't cancel):

https://blog.starkandwayne.com/2015/06/08/unlocking-bosh-locks/

Harnessing the Power of USR1

If your cloud controller is in a bad state (infinite loop, resource spike, etc.), you may wish to do a diagnostic dump to get more information than is available in the CF logs. This data includes stack traces for running threads and other general metrics.

SSH into the rogue Cloud Controller’s vm
cat /var/vcap/sys/run/cloud_controller_ng/cloud_controller_ng.pid to get the PID of the process
kill -USR1 [pid] You will need root access. This will NOT terminate the CC process.
The diagnostics directory is likely /var/vcap/data/cloud_controller_ng/diagnostics, but if it is not, look for the diagnostics key in /var/vcap/jobs/cloud_controller_ng/config/cloud_controller_ng.yml
In the diagnostics directory, you will find a json file with diagnostic information.

Git

https://github.com/dmuth/git-rebase-i-playground

How to rotate keys

https://docs.cloudfoundry.org/adminguide/encrypting-cc-db.html#rotation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly