Migrating Apps to Diego

Page last updated:

This topic describes how to migrate the applications in your deployment from the DEA architecture to the Diego architecture. See the Differences Between DEA and Diego Architectures topic for more information.

Migrating Apps After Upgrading to Diego

To avoid downtime, you should migrate your apps to Diego before upgrading CF. If you have already upgraded, you can get your apps running again by redeploying them with cf restage. To do this, run the following for each app:

$ cf restage APP

After this restaging, your apps should run again.

Prepare for Migration

Before migrating your apps you may need to perform the following tasks:

Scale Your VMs

Ensure you have enough VMs allocated to support the newly-migrated apps.

You can scale your VMs by editing your Cloud Foundry and Diego manifests and redeploying. After performing your migration to Diego, you can scale the DEA component VMs down, unless you want to give your users the option of using either the Diego or DEA architectures.

  1. Edit your Diego manifest to configure the following four VMs with one instance per Availability Zone (AZ), or two if you are using only a single AZ. Locate the following component configurations under jobs in your Diego manifest and edit the instances property:

    jobs:
      - name: brain_ZONE-NUMBER
        instances: INSTANCE-NUMBER
     [...]
      - name: cc_bridge_ZONE-NUMBER
        instances: INSTANCE-NUMBER
     [...]
      - name: route_emitter_ZONE-NUMBER
        instances: INSTANCE-NUMBER
     [...]
      - name: access_ZONE-NUMBER
          instances: INSTANCE-NUMBER
    
  2. Edit your Diego manifest to configure the Diego Cell VM for the capacity your apps require. The Diego Cell VM has a similar responsibility to the DEA VM to run applications. For example, if you have allocated three DEA instances with 32 GB of RAM for each, allocate three Diego Cell instances with 32 GB of RAM for each to have similar capacity on Diego as with DEAs. Locate the following component configurations under resource_pools in your Diego manifest and edit the instance_type property:

    resource_pools:
      - name: cell_ZONE-NUMBER
        cloud_properties: 
          instance_type: YOUR-IAAS-INSTANCE-TYPE
    

    Your instance type varies by IaaS. Choose an instance type that corresponds to the ephemeral disk (where the instance will be stored) and RAM requirements of your configuration. For instance, if your deployment uses Amazon Web Services (AWS), this instance type could be r3.xlarge.

    If you do not believe your deployment will utilize all of the available resources, you can set resource limits by locating the following component configurations under properties in your Diego manifest and replacing default with a specific value. If you do not specify values, Cloud Foundry matches the setting to the size of the VM you choose above.

    properties:
      - diego.executor.memory_capacity_mb:
        default: YOUR-CAPACITY-HERE
      - diego.executor.disk_capacity_mb:
        default: YOUR-CAPACITY-HERE
    
  3. Edit your Diego manifest to ensure that you have at least one Database VM instance in each AZ and that the total number of instances is also an odd number. If your total number of AZs is even, you may need to allocate one more instance to ensure the total number of instances is odd. For example, if you have four AZs, allocate a total of five instances for your Database VMs. You must have an odd number of instances to maintain quorum.

    Locate the following component configuration under jobs in your Diego manifest and edit the instances property:

    jobs:
      - name: database_ZONE-NUMBER
        instances: INSTANCE-NUMBER
    
  4. Edit your Cloud Foundry manifest to ensure that you have at least one Consul VM instance in each AZ and that the total number of instances is also an odd number, as above. Locate the following component configuration under jobs in your Cloud Foundry manifest and edit the instances property:

    jobs:
      - name: consul_ZONE-NUMBER
          instances: INSTANCE-NUMBER
    

Enable Diego as Default

  1. Enable Diego as the default architecture by locating the following component configuration under properties.cc.jobs and editing the default_to_diego_backend property:

    properties:
      cc:
        jobs:
          default_to_diego_backend: true
    
  2. Redeploy with the edited Cloud Foundry and Diego manifests.

Install the cf CLI

Note: If you use a Java-based build system like Eclipse, STS, Maven, or Gradle, you may have only the Java cf-client. The Java cf-client does not currently support the migration command nor disabling health checks.

You must install both the Cloud Foundry Command Line Interface (cf CLI) and the Diego-Enabler CLI Plugin. For more information about installing the cf CLI, see the Installing the Cloud Foundry Command Line Interface topic. For more information about installing the Diego-Enabler CLI Plugin, see the Diego-Enabler repository readme.

Disable Port-Based Health Checks

Worker applications pushed with the --no-route option do not report as healthy after migrating to Diego. To prevent this, disable the port-based health check with cf set-health-check APP_NAME none.

Remove Unsupported Variables from your App Code

  • Diego does not use the VCAP_APP_HOST environment variable. If your code references this variable, replace it with 0.0.0.0.

  • Diego does not use the VCAP_APP_PORT environment variable. If your code references this variable, replace it with PORT, which is set to 8080 by default.

List DEA and Diego Applications

To find out what apps you have running on DEAs and Diego Cells, use the commands cf dea-apps and cf diego-apps. See the following example:

$ cf dea-apps

Getting apps on the DEA runtime as example_user...
OK

name        org        space

dea-app1    org1    space1
dea-app2    org1    space2
...

Use the -s flag followed by a space name to limit the search to apps running within the space, or the -o flag followed by an org name to limit the search to apps running within the org. See the following example:

$ cf dea-apps -o MY-ORG

Getting apps on the DEA runtime in org MY-ORG as example_user...
OK

name        org        space

dea-app1    MY-ORG    space1
dea-app2    MY-ORG    space2

Migrate Your Apps

Cloud Foundry provides three approaches to migrating your apps to Diego:

Overwrite-Based Migration

This procedure overwrites existing app instances with new ones on the Diego architecture, resulting in a brief (~1 minute) downtime. This approach requires fewer steps than the zero downtime blue-green deployment procedure described below.

Note: Use overwrite-based migration if a short downtime is acceptable.

  1. Use the Cloud Foundry Command Line Interface (cf CLI) to install the Diego-Enabler plugin.

    $ cf add-plugin-repo CF-Community http://plugins.cloudfoundry.org/
    $ cf install-plugin Diego-Enabler -r CF-Community
    

  2. Run cf enable-diego APP-NAME to enable Diego for your app.

    $ cf enable-diego EXAMPLE-APP
    Setting EXAMPLE-APP Diego support to true
    OK
    
    Verifying EXAMPLE-APP Diego support is set to true OK

  3. Confirm that APP-NAME runs properly.

    $ cf app EXAMPLE-APP
    

Batch Migration

This procedure migrates multiple apps in a single command using overwrite-based migration. The cf migrate-apps command migrates all apps in a deployment unless you specify an org or space.

  • Run cf migrate-apps diego to migrate apps to Diego. You can specify the following options:
    • -o ORG migrates all apps in an org.
    • -s SPACE migrates all apps in a space that exists in your currently targeted org. If you want to migrate apps in a space from another org, you must target that org before running cf migrate-apps.
    • -p MAX_IN_FLIGHT specifies how many apps to migrate in parallel, up to 100. Defaults to 1. Cloud Foundry recommends first trying a migration with the default and then increasing -p if the first migration is stable. Do not set -p to a value greater than the number of Diego cells in the deployment.

Note: Migrating a running app causes a restart. Migrating a stopped app does not cause a restart.

The following example migrates all DEA apps in a deployment to Diego. The apps migrate in the sequence specified by running cf dea-apps.

$ cf migrate-apps diego

Migrating apps to Diego as example_user....

Started migrating app my-app to Diego as example_user...

Completed migrating app my-app to Diego in space with guid a045rw51-o358-4e26-9dfc-4c7365cf987 as example_user

...

Migration to Diego completed: 23 apps, 0 warnings

The following example migrates all DEA apps in space2 to Diego, ten at a time.

$ cf migrate-apps -s space2 -p 10 diego

Blue-Green Migration

The blue-green deployment method migrates your apps with zero downtime. This method temporarily runs your apps in parallel using both the DEA and Diego architectures.

Note: If necessary, complete the Application Rollback procedure below to revert the migration with zero downtime.

Migrate an App from DEA to Diego Architecture

  1. Use the Cloud Foundry Command Line Interface (cf CLI) to install the Diego-Enabler plugin.

    $ cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org/
    $ cf install-plugin Diego-Enabler -r CF-Community
    

  2. Push your application with a new name and a test route for your application. This app will run on the Diego architecture. Do not use the name or route of the existing application.

    $ cf push NEW-APP -d MY-DOMAIN.COM -n TEMP-SUBDOMAIN

    Note: The currently deployed application, OLD-APP, and the application you are pushing, NEW-APP, must be the same version. Otherwise, any static assets served from your application, like CSS and Javascript, will not be consistent across both apps. Now is not the time to upgrade your app.

  3. Confirm that NEW-APP runs properly.

    $ cf app NEW-APP
    

  4. Run has-diego-enabled to confirm that the application is running on the Diego architecture.

    $ cf has-diego-enabled NEW-APP
    

  5. If the has-diego-enabled command returns false, then set the diego boolean to true:

    $ cf enable-diego NEW-APP
    

  6. Map the route for your application running on the DEA architecture to NEW-APP. This remapping creates a second route that splits your traffic between the DEA and Diego architectures.

    $ cf map-route NEW-APP MY-DOMAIN.COM -n MY-SUBDOMAIN

  7. Unmap the route from the application running on the DEA architecture. This action sends all of the traffic to the application that is running on Diego.

    $ cf unmap-route OLD-APP MY-DOMAIN.COM -n MY-SUBDOMAIN
    

  8. After confirming that the new application is running correctly on Diego, stop OLD-APP to route all traffic to NEW-APP and complete the blue-green migration.

    $ cf stop OLD-APP

    Note: Verify that your application is still accessible and runs properly. If there is a problem with your app, do not complete this procedure. Instead, proceed to the Application Rollback procedure below.

  9. Delete the old application.

    $ cf delete OLD-APP

  10. Optional: Delete the route to the TEMP-SUBDOMAIN that you specified when pushing the Diego app for testing. See Delete a Route.

Application Rollback Procedure

If necessary, complete this procedure to revert your application to the DEA architecture with zero downtime.

Note: This procedure only works if you have not deleted your application that runs on the DEA architecture.

  1. Start your app using the pre-migration name.

    $ cf start OLD-APP

  2. Map OLD-APP to your domain.

    $ cf map-route OLD-APP MY-DOMAIN.COM -n MY-SUBDOMAIN

  3. Unmap the app running on the Diego architecture from your domain.

    $ cf unmap-route NEW-APP MY-DOMAIN.COM -n MY-SUBDOMAIN

Verify Migration

To verify a successful migration of your apps from DEA to Diego, perform the following steps:

  1. Run cf dea-apps to list any apps running on DEAs. Verify that the list returned by the command is empty.

    $ cf dea-apps -o MY-ORG
    
    Getting apps on the DEA runtime in org MY-ORG as example_user...
    OK
    
    name        org     space
    
    
  2. Run cf diego-apps to list any apps running on Diego. Verify that all of your apps are running on Diego.

    $ cf diego-apps -o MY-ORG
    
    Getting apps on the Diego runtime in org MY-ORG as example_user...
    OK
    
    name        org     space
    diego-app1  MY-ORG  MY-SPACE
    diego-app2  MY-ORG  MY-SPACE
    

Final Redeploy

After migrating your apps to Diego, perform a final redeploy. This redeploy can end your installation’s support for DEA architecture, or configure it to support Diego and DEA concurrently. The following steps describe how to perform this final redeploy for each of these scenarios.

Diego-only Deployment

To support Diego only, perform the following steps:

  1. Scale down the DEA and Health Manager VMs to 0 instances. Locate the following component configuration under jobs in your Cloud Foundry manifest and edit the instances property:
        jobs:
          - name: hm9000_ZONE-NUMBER
            instances: 0
          [...]
          - name: runner_ZONE-NUMBER
            instances: 0
        
  2. In your Cloud Foundry manifest, locate the following component configuration under properties.cc.jobs and edit the user_can_select_backend property.
        properties:
          cc:
            jobs:
              users_can_select_backend: false
        
  3. Redeploy.

DEA and Diego Deployment

To continue support for both Diego and DEA, perform the following steps:

  1. Scale the DEA component VMs down to a capacity needed for future apps on DEAs. Locate the following component configuration under jobs in your Cloud Foundry manifest and edit the instances property:
        jobs:
          - name: hm9000_ZONE-NUMBER
            instances: INSTANCE-NUMBER
          [...]
          - name: runner_ZONE-NUMBER
            instances: INSTANCE-NUMBER
        
  2. In your Cloud Foundry manifest, locate the following component configuration under properties.cc.jobs and edit the user_can_select_backend property.
        properties:
          cc:
            jobs:
              users_can_select_backend: true
        
  3. Redeploy.

After your final redeploy, you can optionally verify your migration again.

Troubleshoot Migrated Apps

Because Diego was written to be compatible with DEA architecture, most applications migrated from DEAs to Diego cells continue to run on Diego without change. However, there are differences between DEA and Diego architectures. If you have problems with your application after migrating, review the following:

Symptom

Error: Runner error: desired app failed: 503

Explanation

Diego places a 4KB limit on the maximum size of application routes, space for 40 to 50 medium-sized 50-character routes. This error indicates you have exceeded the limit.

Solution

In some cases, you can work around this by using a wildcard route, for example, *.my-domain.com instead of mapping individual routes. If you see this error and you cannot wildcard the routes, create another instance of the same application and bind the remaining routes to the second application instance.


Symptom

Large applications may fail to stage, typically resulting in the following error: Copying into the container failed.

Explanation

Large applications may fail to stage because of a known issue where disk usage is over-reported.

Solution

By default, apps have a 1GB disk quota. If your application files are close to this size, use the -k option of cf push to increase your disk quota.


Symptom

Running the cf files command results in the error: Request failed for app: APP_NAME, instance: INST_NUM and path: PATH

Explanation

Diego does not support the cf files command.

Solution

Run the cf ssh APP_NAME command to list files in your application instances.


Symptom

Errors related to environment variables

Explanation

Diego does not support the interpolation of environment variables. In the DEA architecture, when you set environment variables with the cf set-env or in your manifest file, you could include one environment variable in the definition of another variable, such as SOMEPATH=$HOME/SOME/PATH.

Solution

Remove interpolation from any environment variables.

View the source for this page in GitHub