====================
CloudFoundry Bundle
====================

.. image:: https://badge.fury.io/py/charmgen.png
:target: http://badge.fury.io/py/charmgen

.. image:: https://travis-ci.org/bcsaller/charmgen.png?branch=master
:target: https://travis-ci.org/bcsaller/charmgen

.. image:: https://pypip.in/d/charmgen/badge.png
:target: https://pypi.python.org/pypi/charmgen

A juju charm to deploy and manage a Cloud Foundry deployment.

If you are unfamiliar with CloudFoundry we suggest referring to their documentation.

    http://docs.cloudfoundry.org/

Documenting CF is beyond the scope of this project. However, once deployed, using the
system is a normal CF experience as described in the above docs.

We provide a set of helper scripts (in bash) which can be used to assist in the deployment and
management of CF.

Deployment

It is recommended that you obtain a local copy of the charm, as it will give you access
to helper scripts which can auto-configure the system. This is largely because of the way
an orchestrator charm needs admin access to the running deployment.

To obtain the charm:

mkdir trusty
bzr branch lp:~cf-charmers/charms/trusty/cloudfoundry/trunk trusty/cloudfoundry

Then, deploy the system:

./cfdeploy <cf_admin_password>

This will gather the necessary Juju admin credentials and boot up the bundle
orchestrator which will setup and manage a CF deployment using Juju. The command
will block until the deployment is fully up and running. It also will create a
CF "admin" user with the given password, leaving you logged in and ready to push
a CF app. Note that while this can take quite some time, the whole process is
automated.

If you don't have the cf command line client the latest one will be installed
from a .deb package to your local system as part of cfdeploy.

Once the deploy completes, you can push apps. A sample application we recommend
to become familiar with the system is GitHub High Score website. This can be
pushed with the following:

git clone https://github.com/bcsaller/github-high-scores
cd github-high-scores
cf push

Admin UI

By default (unless the admin_ui option is set to false), the charm for the
Administration UI project from cloudfoundry-incubator will be deployed
alongside Cloud Foundry. For security reasons, it will not be exposed
by default. To expose the service and open it in a web browser, you can
use the following:

juju expose webadmin
. helpers.sh
cfadminui  # opens browser to Admin UI URL

You can then use the CF admin user credentials to log in.

Note that, currently, once the Admin UI is deployed, you must manually remove
it if you change the value of the admin_ui option, but that changing the
option is required to prevent the Admin UI from potentially being re-deployed
after being manually removed.

Development

For any given release we support (see cloudfoundry.releases) you should be able
to generate an example of the bundle we'll deploy and manage by doing:

. .tox/py27/bin/activate
python charmgen.generator <release>

This will create a cloudfoundry-r directory with the bundle.yaml and a
trusty repo will all the created charms.

There are currently two experimental tools included with the charm. These are
designed to process a cf-release checkout and examine the differences in
various tagged versions of cf-release.

. .tox/py27/bin/activate
# skip if you have a cf-release checkout
git clone https://github.com/cloudfoundry/cf-release.git ../cf-release
python setup.py develop
get_revisions -d ../cf-release 153..173
diff_revisions 153..173 | less

You can also use the following command on the cc unit to monitor the routes
registered with NATS, which can be very helpful for debugging:

cd /var/vcap/packages/cloud_controller_ng/cloud_controller_ng/vendor/bundle/ruby/1.9.1
/var/vcap/packages/ruby/bin/bundle exec bin/nats-sub -s `grep -o 'nats://.*' /var/vcap/jobs/cloud_controller_ng/config/cloud_controller_ng.yml` ">"

Operational Concerns

Scaling CloudFoundy: CF scales chiefly through expansion of its pool of compute
nodes. This is the DEA (Droplet Execution Agents) Service. To scale this
service you can simply do the following:

juju add-unit dea

Reconciler
~~

Full upgrade support coming soon via the reconciler. To run the
reconciler first run the tests::

tox

Then source the helpers and use runrc with a path to a valid server
config::

. helpers.sh
runrc ./path/to/config

Troubleshooting

[ forward looking statements ]

This CloudFoundry charm will automatically attempt to ensure that the
deployment is in a healthy, functional form. However CloudFoundry itself has a
large set of integration tests which can be triggered and run. Juju automatic
charm testing framework will automatically run these tests to ensure the charm
you use has passed theses test prior to deployment. However if you wish to run
these tests yourself you can try the following:

. .tox/py27/bin/activate
python tests/cats.py

Which will produce a full report. As a caution some of these tests can be
considered destructive and shouldn't be used on a live deployment. We intend to
provide access to a recent non-destructive suite of smoke-tests in the near
future. (These are the tests automatically run by this charm and reported on
elsewhere.)

KNOWN ISSUES and WORKAROUNDS

You get an exception with dig 8.8.8.8 in the traceback:
Expecting outbound connectivity the charm will attempt to find the domain name of
its public IP in such a way that it will work with EC2 internal DNS system. To do this
it asks an external DNS server (google's) for its public name. The
workaround is to set the domain name on the service settings to the
publicly reachable address of CF's haproxy server.

juju set cloudfoundry domain=xxx

Packages fail to download:
Similar to the last possible error this is usually around outbound access to S3 where
all the compiled CF artifacts live. A workaround is to mirror the archive
to the internal network and then use our NFS implementation to share the
assets among the CF units. Scripts for the mirror will be provided and the
configuration is as follows:

    juju set cloudfoundry artifacts_url='' mirror_artifacts=true

This will attempt to mirror the artifacts from S3 to a single node (the
cloudfoundry/0 node) and share those over NFS to the whole deployment. Note
that the cloudfoundry node itself should still have outbound access to the
network for S3. The script to mirror the repository out of band and share
that will be documented in the future.