Customizing the Cloud Foundry Deployment Manifest for Azure

Page last updated:

NOTE: Cloud Foundry on Microsoft Azure is supported by the community and Microsoft, but the Cloud Foundry Foundation does not currently test it.

This topic describes how to customize the Cloud Foundry deployment manifest for Azure.

To create a Cloud Foundry manifest, you must perform the following steps:

  1. Prepare workspace environment, download cf-release and install spiff.
  2. Use the BOSH CLI to retrieve your BOSH Director UUID, which you use to customize your manifest stub.
  3. Create a manifest stub in YAML format.
  4. Use spiff to merge the manifest stub with azure IaaS configuration and other configuration files in the cf-release repository to generate your deployment manifest.

Step 1: Preparation

  1. Prepare a work environment

    $ mkdir workspace
    $ cd workspace
    $ export WORK_DIR=$(pwd)
    
  2. Clone the cf-release GitHub repository. Use git clone to clone the latest Cloud Foundry configuration files onto your machine.

    $ git clone https://github.com/cloudfoundry/cf-release.git
    
  3. From the cf-release directory, run the update script to fetch all the submodules.

    $ ${WORK_DIR}/cf-release/scripts/update
    
  4. Install spiff, a command line tool for generating deployment manifests.

Step 2: Retrieve Your BOSH Director UUID

To perform these procedures, you must have installed the BOSH CLI.

  1. Use the bosh target command with the address of your BOSH Director to connect to the BOSH Director. Log in with the default user name and password, admin and admin, or use the username and password that you set when you installed BOSH.
    $ bosh target https://bosh.my-domain.example.com
    Target set to `bosh'
    Your username: admin
    Enter password: *****
    Logged in as 'admin'
    
  2. Use the bosh status --uuid command to view information about your BOSH deployment. Record the UUID of the BOSH Director. You use the UUID when customizing the Cloud Foundry deployment manifest stub.
    $ bosh status --uuid
    abcdef12-3456-7890-abcd-ef1234567890
    

Step 3: Create Your Manifest Stub

Get Cloud Foundry Deployment Manifest Stub for Azure

Get the example manifest stub for Azure, and then follow this editing instructions to customize it for your deployment.

Editing Instructions

Deployment Manifest Stub Contents Editing Instructions

director_uuid: DIRECTOR_UUID
    
Replace DIRECTOR_UUID with the BOSH Director UUID. Run the BOSH CLI command bosh status --uuid to view the BOSH Director UUID.

meta:
  environment: ENVIRONMENT
    
Replace ENVIRONMENT with an arbitrary name describing your environment, for example azure-prod.

  reserved_static_ips:
  - CLOUD_FOUNDRY_PUBLIC_IP
    
Replace CLOUD_FOUNDRY_PUBLIC_IP with an existing public IP address for your Azure network. This is assigned to the ha_proxy job to receive incoming traffic.

networks:
  - name: reserved
    type: vip

  - name: cf1
    type: manual
    subnets:
    - range: 10.0.16.0/24
      gateway: 10.0.16.1
      dns:
      - 168.63.129.16
      reserved:
      - 10.0.16.2 - 10.0.16.3
      static:
      - 10.0.16.4 - 10.0.16.100
      cloud_properties:
        virtual_network_name: VNET_NAME
        subnet_name: SUBNET_NAME_FOR_CLOUD_FOUNDRY
        security_group: NSG_NAME_FOR_CLOUD_FOUNDRY
    
Update the values for range, gateway, reserved, and static to reflect the available networks and IP addresses in your Azure network. Replace VNET_NAME with the virtual network name, SUBNET_NAME_FOR_CLOUD_FOUNDRY with the subnet name, and NSG_NAME_FOR_CLOUD_FOUNDRY with the security group name of your Azure network.

properties:
  system_domain: SYSTEM_DOMAIN
  system_domain_organization: SYSTEM_DOMAIN_ORGANIZATION
    
Replace SYSTEM_DOMAIN with the full domain you want associated with applications pushed to your Cloud Foundry installation. You must have already acquired these domains and configured their DNS records so that these domains resolve to your load balancer. For testing, you can use CLOUD_FOUNDRY_PUBLIC_IP.xip.io if you do not have a domain available. xip.io is not stable, and can sometimes fail to resolve to related IP addresses.

Replace SYSTEM_DOMAIN_ORGANIZATION with your organization name. This organization will be created and configured to own the SYSTEM_DOMAIN.

  ssl:
    skip_cert_verify: true
    
Set skip_cert_verify to true to skip SSL certificate verification if you do not use a real domain and certificate. If you want to use SSL certificates to secure traffic into your deployment, see the Securing Traffic into Cloud Foundry topic.

  cc:
    staging_upload_user: STAGING_UPLOAD_USER
    staging_upload_password: STAGING_UPLOAD_PASSWORD
    bulk_api_password: BULK_API_PASSWORD
    db_encryption_key: DB_ENCRYPTION_KEY
    
The Cloud Controller API endpoint requires basic authentication. Replace STAGING_UPLOAD_USER and STAGING_UPLOAD_PASSWORD with a username and password of your choosing.

Replace BULK_API_PASSWORD with a password of your choosing. Health Manager uses this password to access the Cloud Controller bulk API.

Replace DB_ENCRYPTION_KEY with a secure key that you generate to encrypt sensitive values in the Cloud Controller database. You can use any random string. For example, run the following command from a command line to generate a 32-character random string: LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32 ; echo

  blobstore:
    admin_users:
      - username: BLOBSTORE_USERNAME
        password: BLOBSTORE_PASSWORD
    secure_link:
        secret: BLOBSTORE_SECRET
    tls:
        port: 443
        cert: BLOBSTORE_TLS_CERT
        private_key: BLOBSTORE_PRIVATE_KEY
        ca_cert: BLOBSTORE_CA_CERT
    
Replace BLOBSTORE_USERNAME and BLOBSTORE_PASSWORD with a username and password of your choosing.

Replace BLOBSTORE_SECRET with a secure secret of your choosing.

Replace BLOBSTORE_TLS_CERT, BLOBSTORE_PRIVATE_KEY, and BLOBSTORE_CA_CERT with the blobstore TLS certificate, private key, and CA certificate. You can use the scripts/generate-blobstore-certs script in the cf-release repository to generate self-signed certificates.

  consul:
    encrypt_keys:
      - CONSUL_ENCRYPT_KEY
    ca_cert: CONSUL_CA_CERT
    server_cert: CONSUL_SERVER_CERT
    server_key: CONSUL_SERVER_KEY
    agent_cert: CONSUL_AGENT_CERT
    agent_key: CONSUL_AGENT_KEY
    
See the Security Configuration for Consul topic. You can use the scripts/generate-consul-certs script in the cf-release repository to generate self-signed certificates.

  etcd:
    require_ssl: true
    ca_cert: ETCD_CA_CERT
    client_cert: ETCD_CLIENT_CERT
    client_key: ETCD_CLIENT_KEY
    peer_ca_cert: ETCD_PEER_CA_CERT
    peer_cert: ETCD_PEER_CERT
    peer_key: ETCD_PEER_KEY
    server_cert: ETCD_SERVER_CERT
    server_key: ETCD_SERVER_KEY
    
Generate SSL certs for etcd and replace these values. You can use the scripts/generate-etcd-certs script in the cf-release repository to generate self signed certs.

  loggregator:
    tls:
      ca_cert: LOGGREGATOR_CA_CERT
      doppler:
        cert: DOPPLER_CERT
        key: DOPPLER_KEY
      metron:
        cert: METRON_CERT
        key: METRON_KEY
      trafficcontroller:
        cert: TRAFFICCONTROLLER_CERT
        key: TRAFFICCONTROLLER_KEY
    
Generate SSL certs for loggregator and replace these values. You can use the scripts/generate-loggregator-certs script in the cf-release repository to generate self signed certs.

  loggregator_endpoint:
    shared_secret: LOGGREGATOR_ENDPOINT_SHARED_SECRET
    
Replace LOGGREGATOR_ENDPOINT_SHARED_SECRET with a secure string that you generate.

  nats:
    user: NATS_USER
    password: NATS_PASSWORD
    
Replace NATS_USER and NATS_PASSWORD with a username and secure password of your choosing. Cloud Foundry components use these credentials to communicate with each other over the NATS message bus.

  router:
    status:
      user: ROUTER_USER
      password: ROUTER_PASSWORD
    
Replace ROUTER_USER and ROUTER_PASSWORD with a username and secure password of your choosing.

  uaa:
    admin:
      client_secret: ADMIN_SECRET
    cc:
      client_secret: CC_CLIENT_SECRET
    clients:
      cc_routing:
        secret: CC_ROUTING_SECRET
      cloud_controller_username_lookup:
        secret: CLOUD_CONTROLLER_USERNAME_LOOKUP_SECRET
      doppler:
        secret: DOPPLER_SECRET
      gorouter:
        secret: GOROUTER_SECRET
      tcp_emitter:
        secret: TCP-EMITTER-SECRET
      tcp_router:
        secret: TCP-ROUTER-SECRET
      login:
        secret: LOGIN_CLIENT_SECRET
      notifications:
        secret: NOTIFICATIONS_CLIENT_SECRET
      cc-service-dashboards:
        secret: CC_SERVICE_DASHBOARDS_SECRET
    
Replace the values for all secret keys with secure secrets that you generate.

You can configure container-to-container networking in this section. If you want to deploy container-to-container networking, see the Enable on an IaaS section of the Administering Container-to-Container Networking topic, beginning with step 4.

    jwt:
      verification_key: JWT_VERIFICATION_KEY
      signing_key: JWT_SIGNING_KEY
    
Generate a PEM-encoded RSA key pair, and replace JWT_SIGNING_KEY with the private key, and JWT_VERIFICATION_KEY with the corresponding public key. You can generate a key pair with the following command: openssl genrsa -out jwt_signing_key 2048 && openssl rsa -pubout -in jwt_signing_key -out jwt_verification_key Copy and paste the full keys with correct indentation, including the BEGIN and END delimiter lines.

    scim:
      users:
      - name: admin
        password: ADMIN_PASSWORD
        groups:
        - scim.write
        - scim.read
        - openid
        - cloud_controller.admin
        - doppler.firehose
    
Generate a secure password and replace ADMIN_PASSWORD with that value to set the password for the Admin user of your Cloud Foundry installation.

    sslCertificate: UAA_SERVER_CERT
    sslPrivateKey: UAA_SERVER_KEY
    
Replace UAA_SERVER_CERT and UAA_SERVER_KEY with UAA certificates. You can use the scripts/generate-uaa-certs script in the cf-release repository to generate self-signed certificates.

  ccdb:
    roles:
    - name: ccadmin
      password: CCDB_PASSWORD
  uaadb:
    roles:
      - name: uaaadmin
        password: UAADB_PASSWORD
  databases:
    roles:
    - name: ccadmin
      password: CCDB_PASSWORD
    - name: uaaadmin
      password: UAADB_PASSWORD
    - name: diego
      password: DIEGODB_PASSWORD
    
Replace CCDB_PASSWORD, UAADB_PASSWORD, and DIEGODB_PASSWORDwith secure passwords of your choosing.

  hm9000:
    ca_cert: HM9000_CA_CERT
    server_cert: HM9000_SERVER_CERT
    server_key: HM9000_SERVER_KEY
    agent_cert: HM9000_AGENT_CERT
    agent_key: HM9000_AGENT_KEY
    
Generate SSL certificates for HM9000 and replace these values. You can use the scripts/generate-hm9000-certs script in the cf-release repository to generate self-signed certificates.

  login:
    saml:
      serviceProviderKey: SAML_KEY
      serviceProviderKeyPassword: ''
      serviceProviderCertificate: SAML_CERT
    
Generate SSL certificates for SAML and replace these values. You can use the scripts/generate-certs script in the cf-release repository to generate self-signed certificates.

jobs:
  - name: ha_proxy_z1
    networks:
      - name: cf1
        default:
        - dns
        - gateway
    properties:
      ha_proxy:
        ssl_pem: |
          -----BEGIN RSA PRIVATE KEY-----
          RSA_PRIVATE_KEY
          -----END RSA PRIVATE KEY-----
          -----BEGIN CERTIFICATE-----
          SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
          -----END CERTIFICATE-----
    
Replace RSA_PRIVATE_KEY and SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY with the PEM-encoded private key and certificate associated with the system domain and apps domains that you configured to terminate at the floating IP address associated with the ha_proxy job. For self-signed certificates, you can run openssl genrsa -out haproxy_ssl.key 2048 to generate a key, and run openssl req -new -x509 -days 365 -key haproxy_ssl.key -out haproxy_ssl.cert to generate the certificate.

Note: You can configure blacklists of IP address ranges to prevent future apps deployed to your Cloud Foundry installation from attempting to drain syslogs to internal Cloud Foundry components. See the Log Drain Blacklist Configuration topic for more information.

Step 4: Generate Your Manifest

  1. Download Azure infrastructure stub cf-infrastructure-azure.yml for Cloud Foundry from this link. You can also set IaaS configuration by changing this file, for example changing instance_type.
  2. Run the following command from the cf-release directory to create a deployment manifest named cf-deployment.yml:

    $ spiff merge \
      "${WORK_DIR}/cf-release/templates/generic-manifest-mask.yml" \
      "${WORK_DIR}/cf-release/templates/cf.yml" \
      "${WORK_DIR}/cf-infrastructure-azure.yml" \
      "${WORK_DIR}/cf-stub.yml" \
      > "${WORK_DIR}/cf-deployment.yml"
    

  3. Use the bosh deployment command to set your deployment to the generated manifest:

    $ bosh deployment ${WORK_DIR}/cf-deployment.yml
    

You are now ready to deploy Cloud Foundry. See the Deploying Cloud Foundry topic for instructions.

Create a pull request or raise an issue on the source for this page in GitHub