_c2c_oss_enable.html.md.erb

This section presents two procedures for enabling CF Networking.
See the table below and choose the procedure that corresponds with your use case. 

<table>
<tr>
  <th>If your deployment runs on ...</th>
  <th>Then follow ...</th>
</tr>
<tr>
  <td>An IaaS, such as AWS or vSphere</td>
  <td><a href="#iaas">Enable on an IaaS</a></td>
</tr>
<tr>
  <td>BOSH-Lite, a Vagrant box for testing or development</td>
  <td><a href="#lite">Enable on BOSH-Lite</a></td>
</tr>
</table>

###<a id="iaas"></a>Enable on an IaaS

If your CF deployment runs on an IaaS, follow these steps to enable CF Networking.

<ol>
    <li>Ensure that you have a database ready. To complete this procedure, you need a v5.7 or later MySQL database, or a PostgreSQL database. 
You can use a database within your Cloud Controller database instance or create a different instance, such as Amazon RDS.</li>
    <li>Target your BOSH Director using the BOSH CLI:<br>
    <pre> $ bosh target BOSH-DIRECTOR-IP </pre>
    </li>

    <li>If you have not already, upload a stemcell that uses Linux kernel 4.4, such as stemcell 3263.2 or later:<br>
    <pre> $ bosh upload stemcell URL-OF-STEMCELL </pre>
    </li>

    <li>Open the CF properties stub that you created when <a href="http://docs.cloudfoundry.org/deploying/index.html">deploying Cloud Foundry</a>
        and do the following:
    <ol type="a">
        <li>Under <code>properties</code> > <code>uaa</code> > <code>scim</code> > <code>users</code> > <code>name: admin</code> > <code>groups</code> 
            add a new group named <code>network.admin</code>.
        <pre>
scim:
  users:
  - name: admin
    password: <admin-password>
    groups:
      - scim.write
      - scim.read
      ...
      - routing.router_groups.write
      <b>- network.admin</b> </pre></li>
        <li>Under <code>properties</code> > <code>uaa</code> > <code>clients</code> > <code>cf</code>, to the line beginning <code>scope: </code>
        add <code>network.admin</code>.</li>
        <pre>
clients:
  cf:
    scope: cloud_controller.read,&nbsp;[...]&nbsp;routing.router_groups.read,<strong>network.admin</strong></pre>
        <li><a name="uaa-secret"></a>Under <code>clients</code>, add a <code>network-policy</code> 
        client as follows and replace <code>REPLACE_WITH_UAA_CLIENT_SECRET</code> with a secure password of your choosing. 
        <pre>
clients:
  cf:
    scope:&nbsp;cloud_controller.read,&nbsp;[...]&nbsp;routing.router_groups.read,network.admin
  <strong>network-policy:
    authorities: uaa.resource,cloud_controller.admin_read_only
    authorized-grant-types: client_credentials,refresh_token
    secret: REPLACE_WITH_UAA_CLIENT_SECRET</strong></pre> 
        </li>
    </ol>
    </li>
    <li>Create a CF Networking stub file <code>stubs/cf-networking/stub.yml</code> and paste in the template below:

<pre>
---
cf_networking_overrides:
  releases:
  - name: cf-networking
    version: latest
  driver_templates:
  - name: garden-cni
    release: cf-networking
  - name: cni-flannel
    release: cf-networking
  - name: netmon
    release: cf-networking
  - name: vxlan-policy-agent
    release: cf-networking
  properties:
    cf_networking:
      vxlan_policy_agent:
        policy_server_url: https://policy-server.service.cf.internal:4003
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          REPLACE_WITH_CA_CERT
          -----END CERTIFICATE-----
        client_cert: |
          -----BEGIN CERTIFICATE-----
          REPLACE_WITH_CLIENT_CERT
          -----END CERTIFICATE-----
        client_key: |
          -----BEGIN RSA PRIVATE KEY-----
          REPLACE_WITH_CLIENT_KEY
          -----END RSA PRIVATE KEY-----
      garden_external_networker:
        cni_plugin_dir: /var/vcap/packages/flannel/bin
        cni_config_dir: /var/vcap/jobs/cni-flannel/config/cni
      plugin:
        etcd_endpoints:
          - (( config_from_cf.etcd.advertise_urls_dns_suffix ))
        etcd_client_cert: (( config_from_cf.etcd.client_cert ))
        etcd_client_key: (( config_from_cf.etcd.client_key ))
        etcd_ca_cert: (( config_from_cf.etcd.ca_cert ))
      policy_server:
        database:
          type: REPLACE_WITH_DB_TYPE
          username: REPLACE_WITH_USERNAME
          password: REPLACE_WITH_PASSWORD
          host: REPLACE_WITH_DB_HOSTNAME
          port: REPLACE_WITH_DB_PORT
          name: REPLACE_WITH_DB_NAME
        skip_ssl_validation: true
        uaa_client_secret: REPLACE_WITH_UAA_CLIENT_SECRET
        uaa_url: (( "https://uaa." config_from_cf.system_domain ))
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          REPLACE_WITH_CA_CERT
          -----END CERTIFICATE-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          REPLACE_WITH_SERVER_CERT
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          REPLACE_WITH_SERVER_KEY
          -----END RSA PRIVATE KEY-----
  garden_properties:
    network_plugin: /var/vcap/packages/runc-cni/bin/garden-external-networker
    network_plugin_extra_args:
    - --configFile=/var/vcap/jobs/garden-cni/config/adapter.json
  jobs:
  - name: policy-server
    instances: 1
    persistent_disk: 256
    templates:
    - name: policy-server
      release: cf-networking
    - name: route_registrar
      release: cf
    - name: consul_agent
      release: cf
    - name: metron_agent
      release: cf
    resource_pool: database_z1
    networks:
      - name: diego1
    properties:
      nats:
        machines: (( config_from_cf.nats.machines ))
        user: (( config_from_cf.nats.user ))
        password: (( config_from_cf.nats.password ))
        port: (( config_from_cf.nats.port ))
      metron_agent:
        zone: z1
      route_registrar:
        routes:
        - name: policy-server
          port: 4002
          registration_interval: 20s
          uris:
          - (( "api." config_from_cf.system_domain "/networking" ))
      consul:
        agent:
          services:
            policy-server:
              name: policy-server
              check:
                interval: 5s
                script: /bin/true

config_from_cf: (( merge ))
</pre>
</li>

<li>Edit the stub file using the table below as a guide:
<p class="note"><strong>Note</strong>: For a test environment, you can use a script such as the one in the 
<a href="https://github.com/cloudfoundry-incubator/cf-networking-release/blob/develop/scripts/generate-certs">CF Networking Release repository</a> 
to generate the certificates and keys required for the stub. 
For a production deployment, use certificates signed by a Certificate Authority (CA).</p>
<table border="1" class="nice">
  <tr>
    <th style="width:35%">CF Networking Stub Contents</th>
    <th>Editing Instructions</th>
  </tr>
  <tr>
    <td><pre><code>
properties:
  cf_networking:
    vxlan_policy_agent:
      policy_server_url: [...]
      ca_cert: |
        -----BEGIN CERTIFICATE-----
        REPLACE_WITH_CA_CERT
        -----END CERTIFICATE-----
      client_cert: |
        -----BEGIN CERTIFICATE-----
        REPLACE_WITH_CLIENT_CERT
        -----END CERTIFICATE-----
      client_key: |
        -----BEGIN RSA PRIVATE KEY-----
        REPLACE_WITH_CLIENT_KEY
        -----END RSA PRIVATE KEY-----</code></pre></td>
    <td>Paste in certificates and keys for the policy agent. 
        The policy agent communicates with the policy server through TLS. 
        See the <a href="#architecture">Architecture</a> section for more information.
    </td>
  </tr>
  <tr>
    <td><pre><code>
policy_server:
  uaa_client_secret: REPLACE_WITH_UAA_CLIENT_SECRET
    </code></pre></td>
    <td>Paste in the same value you used in the step <a href="#uaa-secret">above</a>.
    </td>
  </tr>
  <tr>
    <td><pre><code>
database:
  type: REPLACE_WITH_DB_TYPE 
  username: REPLACE_WITH_USERNAME
  password: REPLACE_WITH_PASSWORD
  host: REPLACE_WITH_DB_HOSTNAME
  port: REPLACE_WITH_DB_PORT 
  name: REPLACE_WITH_DB_NAME 
   </code></pre></td>
    <td>
    Supply the details for the database from <a href="#enable">step 1</a>.<br>
    The database type must be <code>postgres</code> or <code>mysql</code>.<br>
    Choose a username and password. 
    <br>For <code>host</code>, enter the IP address of the database instance. 
    <br>Supply a port; for MySQL a typical port is <code>3360</code>.
    <br>Supply the name of the database.
    </td>
  </tr>
<tr>
    <td><pre><code>
  ca_cert: |
    -----BEGIN CERTIFICATE-----
    REPLACE_WITH_CA_CERT
    -----END CERTIFICATE-----
  server_cert: |
    -----BEGIN CERTIFICATE-----
    REPLACE_WITH_SERVER_CERT
    -----END CERTIFICATE-----
  server_key: |
    -----BEGIN RSA PRIVATE KEY-----
    REPLACE_WITH_SERVER_KEY
    -----END RSA PRIVATE KEY-----
garden_external_networker:
  cni_plugin_dir: /var/vcap/packages/flannel/bin
  cni_config_dir: /var/vcap/jobs/cni-flannel/config/cni
    </code></pre></td>
    <td>
    Paste in the certificates and keys for the policy server. 
    The policy server communicates with the policy agent through TLS. 
    See the <a href="#architecture">Architecture</a> section for more information.
    </td>
  </tr>
</table>
<li>
Create a file that contains the following bash script. Name the file <code>generate_diego.sh</code>.
<pre>
set -e -x -u

environment_path=STUBS-DIRECTORY
output_path=MANIFEST-DIRECTORY
diego_release_path=LOCAL-DIEGO-REPO

pushd cf-release
  ./scripts/generate_deployment_manifest aws \
    ${environment_path}/stubs/director-uuid.yml \
    ${diego_release_path}/examples/aws/stubs/cf/diego.yml \
    ${environment_path}/stubs/cf/properties.yml \
    ${environment_path}/stubs/cf/instance-count-overrides.yml \
    ${environment_path}/stubs/cf/stub.yml \
    > ${output_path}/cf.yml
popd

pushd diego-release
  ./scripts/generate-deployment-manifest \
    -g \
    -c ${output_path}/cf.yml \
    -i ${environment_path}/stubs/diego/iaas-settings.yml \
    -p ${environment_path}/stubs/diego/property-overrides.yml \
    -n ${environment_path}/stubs/diego/instance-count-overrides.yml \
    -N ${environment_path}/stubs/cf-networking/stub.yml \
    -v ${environment_path}/stubs/diego/release-versions.yml \
    > ${output_path}/diego.yml
popd
</pre>
Replace the variables as follows:<br>
<ul>
<li><code>STUBS-DIRECTORY</code>:  The directory containing your stubs for CF, Diego, and CF Networking.</li>
<li><code>MANIFEST-DIRECTORY</code>: The directory where you want the manifest created.</li>
<li><code>LOCAL-DIEGO-REPO</code>: The directory of the local copy of the <code>diego-release</code> repository.</li>
</ul>
</li>
<li>
Enter the following commands to make the script executable and run the script.
<pre>
$ chmod u+x generate_diego.sh
$ ./generate_diego.sh
</pre>
</li>
<li>
Enter the following command to target your BOSH director:
<pre>
$ bosh target BOSH-DIRECTOR-IP
</pre>
For example,
<pre class="terminal">$ bosh target 192.0.2.1</pre>
</li>
<li>
Enter the following command to set your CF deployment to the manifest you generated.
<pre>
$ bosh deployment ${output_path}/cf.yml
</pre>
</li>
<li>
Enter the following command to deploy CF.
<pre>$ bosh deploy</pre>
</li>
<li>
Enter the following command to set your Diego deployment to the manifest you generated.
<pre>
$ bosh deployment ${output_path}/diego.yml
</pre>
</li>
<li>
Enter the following command to deploy Diego.
<pre>$ bosh deploy</pre>
</li>
<li>(Optional) Try out the <a href="https://github.com/cloudfoundry-incubator/cf-networking-release/tree/develop/src/example-apps/cats-and-dogs">Cats and Dogs</a> 
     example in the CF Networking Release repository. 
     In this tutorial, you deploy two apps and create a CF Networking policy that 
     allows them to communicate directly with each other. 
 </li>
</ol>

###<a id="lite"></a>Enable on BOSH-Lite

If your CF deployment runs on BOSH-Lite, follow these steps to enable CF Networking. 
<ol>
  <li> Ensure your BOSH-Lite version is `9000.131.0` or later. If you need to upgrade, follow the instructions for [Upgrading the BOSH-Lite VM](https://github.com/cloudfoundry/bosh-lite/blob/master/README.md#upgrading-the-bosh-lite-vm). 
  </li>
  <li> Navigate to your `bosh-lite` directory, for example,
    <pre class="terminal">$ cd ~/workspace/bosh-lite </pre>
  </li>
  <li> To enable <a href="http://ebtables.netfilter.org/documentation/bridge-nf.html">bridge-netfilter</a> on the VM running BOSH-Lite, run the following command:
    ```
    $ vagrant ssh -c 'sudo modprobe br_netfilter'
    ```
    <br>CF Networking on BOSH-Lite requires this Linux kernel feature to enforce network policy. 
  </li>

<li> Upload the latest BOSH-Lite stemcell:
  ```
  $ bosh upload stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-trusty-go_agent
  ```
  </li>
  <li>To clone the required CF release repos to your workspace, enter the following commands:<br>
  <code>
  $ git clone https<span>:</span>//github.com/cloudfoundry/diego-release<br>
  $ git clone https<span>:</span>//github.com/cloudfoundry/cf-release<br>
  $ git clone https<span>:</span>//github.com/cloudfoundry-incubator/cf-networking-release
  </code>
  </li>
  <li>To enable CF Networking on BOSH-Lite, change directories into `cf-networking-release` and run the deploy script:<br>
  <code>
  $ cd ~/workspace/cf-networking-release<br>
  $ ./scripts/deploy-to-bosh-lite
  </code>
  </li>
 <li>(Optional) Try out the <a href="https://github.com/cloudfoundry-incubator/cf-networking-release/tree/develop/src/example-apps/cats-and-dogs">Cats and Dogs</a> 
     example in the CF Networking Release repository. 
     In this tutorial, you deploy two apps and create a CF Networking policy that 
     allows them to communicate directly with each other. 
 </li>
</ol>