Skip to content

Cloud Foundry How Tos

This section describes common activities for managing your Cloud Foundry environment. This collection does only cover some aspects of Cloud Foundry and are not intended to replace the official documentation.

Space Management

Add a New User

After the initial account registration the Tenant Owner will be assigned the Org Manager role within his tenants Cloud Foundry Org. He can then assign roles to new users via the Cloud Foundry CLI.

Attention

Prerequisites for adding a new user:

Info

The tenant role and the Cloud Foundry role are not the same and need to be assigned separately.

Change a User's Permissions

Users can have one or more roles. The combination of these roles defines the user's overall permissions in the Org and within specific app spaces in that Org.

Use the following commands for managing users on an Org level.

Function Command Example
View the organizations belonging to an account cf orgs cf orgs
View all users in an organization by role cf org-users {org_name} cf org-users my-mindsphere-org
Assign an Org role to a user cf set-org-role {user_name} {org_name} {role} cf set-org-role Alice my-mindsphere-org OrgManager
Remove an Org role from a user cf unset-org-role {user_name} {org_name} {role} cf unset-org-role Alice my-mindsphere-org OrgManager

And these for only assigning access to specific spaces.

Function Command Example
View the spaces in an Org cf spaces cf spaces
View all users in a space by role cf space-users {org_name} {space_name} cf space-users my-mindsphere-org development
Assign a space role to a user cf set-space-role {user_name} {org_name} {space_name} {role} cf set-space-role Alice my-example-org development SpaceAuditor
Remove a space role from a user cf unset-space-role {user_name} {org_name} {space_name} {role} cf unset-space-role Alice my-mindsphere-org development SpaceAuditor

Create a New Space

Use cf create-space {space_name} to create a new space within your Org. Next, you can proceed and assign one of your developers the SpaceManager or SpaceDeveloper role by using cf set-space-role {user_name} {org_name} {space_name} {role}. You can list all users of an space with cf space-users.

Assign a User to a Space

Use cf set-space-role {user_name} {org_name} {space_name} {role} to add a user to a space.

Get the Current Usage of my Org

Use the cf org {org_name} command to get information about your Org.

Service Instances

Create a Service Instance

MindSphere provides multiple backing services out of the box that can be used for application development and operation. These services are managed and will be provisioned on a dedicated VM. Depending on your Org quota and settings you can create multiple service instances. Each instance is related to a backing service plan that describes the hardware, capabilities and the number of instances (e.g. clustered instances).

Use cf marketplace or cf m to list all available Backing Services and their associated plans. Choose your desired service and create a new instance with cf create-service {service_name} {plan} {service_instance}. As a next step you can bind this service to one of your apps.

Use cf service {service_instance} to get detailed information about your service instance.

Update a Service Instance to a bigger Service plan_name

You can update a service instance to a bigger service plan with cf update-service {service_instance} -p {a-bigger-plan}.

The following are the possibilities for updating to a bigger plan:

  • It is possible to update from a service plan to another if the new service plan has a bigger disk size than the old one.
  • It is possible to update from a non clustered service plan to a clustered service plan (except LogMe, MongoDB 3.2 and PostgreSQL 9.4).
  • It is not possible to update from a clustered service plan with smaller disk size to a non clustered service plan with a bigger disk size.

Info

Downgrading a service instance to a smaller service plan is not possible. This can only be done by creating a backup, downloading the backup and restoring it into another smaller service instance.

Bind a Service Instance

Bind the service with cf bind-service {app_name} {service_instance} to one of your apps running in the same space as the service. After the binding the service credentials are available as environment variables and can be used within your application.

Backup & Restore Service Instances

You can use the service URL to visit the Backing Service Dashboard and start backups and restore an older one.

Enable Sharing of a Service Instance

  1. Navigate into the Cloud Foundry space where your service instance was created.
  2. Share the service with {another_space} using cf share-service {service_instance} -s {another_space}.

Info

  • For sharing service instances among spaces you need the Space Developer role in both spaces.
  • You cannot share a service instance with a space where a service instance with the same name already exists.

Attention

Avoid overload of service instances when binding them to multiple apps. Refer to the respective service plan specification.

Disable Sharing of a Service Instance

  1. Navigate into the Cloud Foundry space where your service instance was created.
  2. Disable sharing of the service with {another_space} using cf unshare-service {service_instance} -s {another_space}.

Info

  • You need the Space Developer role in the space where the service instance is running to disable its sharing.
  • You cannot delete a service instance while it is being shared with other spaces.

Attention

Unsharing a service instance removes all bindings to apps in the space it was shared with. This may cause apps to fail. Run the cf service {service_instance} command to see if bindings exist in the spaces the service instance is shared with before unsharing it.

Sharing a Backing Service in MindSphere Operator Cockpit

  1. Log into Cloud Foundry: cf login -a https://api.cf.{region}.{mindsphere-domain} --sso
  2. Select your Cloud Foundry org: cf target -o {org_name}
  3. Create a new space: cf create-space {space_name}

Info

To use Auto deployment feature of the Operator Cockpit, the {space_name} should be equal the name of the app to be registered.

  1. Switch to the space with the service instance to be shared:
    cf target -s {service_instance_space_name}
  2. Share the service instance with the new space:
    cf share-service {service_instance} -s {space_name}
    The name of the service instance is the same in all spaces. Make sure it is set correctly in your manifest file.
  3. Deploy your app in the new space and bind the service instance to it.

Attention

It is prohibited to share service instances across multiple organizations and might be blocked in the future.

Create a User-Provided-Service

Refer to the official Cloud Foundry documentation on how to create and use these:

Warning

Heads up! Only use this feature if you are aware about the security and operational consequences of this feature. Consider using restrictive firewall settings or set up a peering connection!

Background Tasks / Processes

Cloud Foundry supports running background processes, for example data crunching. Those background processes are normal Cloud Foundry apps, but without a route. Therefore, it is necessary to use the --no-route parameter for pushing applications or set this as an attribute in your manifest.yml.

Warning

If you forget to disable the route, Cloud Foundry is going to perform periodically health checks that will fail. Due to this failing health checks the Cloud Controller is going to stop your application.

Refer to the official documentation for further details:

Stacks

Stacks are prebuilt root file systems that support specific operating systems. Linux-based systems need /usr and /bin directories at their root.

Find out which Stack an App Uses

The following Cloud Foundry Stacks are currently available:

  • cflinuxfs3: Based on Ubuntu Bionic 18.04
  • cflinuxfs2: Deprecated and based on Ubuntu Trusty 14.04

We advise to always use the latest available stack. You can find out the stack which your application is using with the following command:

1
cf app app_name

The command line will list a summary of the application including the used stack:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
Showing health and status for app app_name in org org_name / space space_name as john.doe@mindsphere.io...

name:              app_name
requested state:   started
instances:         1/1
usage:             500M x 1 instances
routes:            app_name-posthumeral-streptomycin.apps.eu1.mindsphere.io
last uploaded:     Thu 21 Feb 12:37:11 CET 2019
stack:             cflinuxfs3
buildpack:         staticfile_buildpack

    state     since                  cpu    memory         disk         details
#0  running   2019-02-25T14:13:14Z   0.0%   1.5M of 500M   6M of 512M

Update the Stack of an App

To change the stack to cflinuxfs3, either add the stack attribute in your Single Manifest file or use the following command:

1
cf push {app_name} -s cflinuxfs3

The push command causes a restaging of the application and ensures that all statically linked dependencies are updated.

Docker container in Cloud Foundry

Info

Running Docker containers in Cloud Foundry is currently only possible for Developer tenants. Apps cannot be validated by App Validation and will not be forwarded to Operator tenant.

Info

Running Docker containers in Cloud Foundry is currently only supported in region Europe 1.

Docker containers based on docker images, which are stored in a Container Registry, can be directly run in Cloud Foundry.

Prerequisites

The following are the prerequisites for running containers which are stored in MindSphere Container Registry Lite:

  • You have created MindSphere Container Registry Robot Account
  • You have logged into docker registry in command line
  • You have tagged the image
  • You have pushed the image to MindSphere Container Registry

Push a Docker Image from MindSphere Container Registry

To deploy a Docker image from MindSphere Container Registry, execute the following command:

1
2
  export CF_DOCKER_PASSWORD={robot_account_password}
  cf push {app_name} --docker-image mcrbasic.registry.eu1.mindsphere.io/{tenant}/{image}:{tag} --docker-username '{robot_account_user}'

For more information refer Deploying an App with Docker.

Buildpacks

Binary Buildpack

Use the binary buildpack for running arbitrary binary web servers. For further information refer Binary Buildpack.

Compile

The binary_buildpack is running on cflinuxfs3 stack, which is based on Ubuntu Bionic 18.04. Therefore the binary has to be build on Ubuntu Bionic 18.04.

Push

In push command, use the -b option and specify the buildpack binary_buildpack. Alternatively, the buildpack can be specified in manifest.yml with buildpack: binary_buildpack.
In push command, use the -c option to specify the start command, for example ./hello_world. Alternatively, the start command can be specified in Procfile like web: ./hello_world.

Operator Cockpit

For using the Auto deployment in Operator Tenants's Operator Cockpit, specify the following:

  • buildpack in manifest.yml
  • start command in Procfile

Using Custom Buildpack

Custom Buildpack does not generally mean that you have to create the buildpack by your own. You can also use the Custom Buildpack feature to run your app on a specific version of a public buildpack.
This can also be helpful for your app lifecycle. By using a fix version of e.g. NodeJS buildpack, you can be sure, that development team, testing team and operations is using the same version of a buildpack and will not run into any version conflicts.
The Custom Buildpack can be added to manifest.yml or you can push your app with -b argument. E.g. cf push -b https://github.com/cloudfoundry/nodejs-buildpack.git#v1.7.9.

Note

It's recommended to change regularly to the latest version of a buildpack. Every update of a buildpack version fixes security and/or functional issues.
It's in your own responsibility to use Custom Builpack and update to the latest buildpack releases.

For further information, refer to Deploy Apps with a Custom Buildpack.

IPs via which Apps Access the Internet

MindSphere applications running on Cloud Foundry access the internet via a NAT gateway, which uses the following IP addresses:

  • In region Europe 1 / Europe 2:

    1
    2
    3
    35.156.223.10
    18.194.162.141
    18.194.195.179
    
  • In region China 1:

    1
    2
    3
    4
    101.132.123.180
    106.15.159.73
    47.102.201.47
    47.102.210.119
    

How To escape quotes of json objects in command line

There are differences in escaping quotes of json objects in command line. The following example shows the correct escaping for Linux / Mac, Windows Command Line and Windows PowerShell.

  • Linux / Mac:
    cf update-service <servicename> -c '{"update": true}'
  • Windows Command Line:
    cf update-service <servicename> -c "{\"update\": true}"
  • Windows PowerShell:
    cf update-service <servicename> -c '{\"update\": true}'

Develop MindSphere Apps for multiple regions using Cloud Foundry

You can develop apps that run in all regions. You can find more information about regions in the Mindsphere regions document. It is important to understand which APIs and library of MindSphere you use. The following points should be considered when developing such an app:

General

Tenants and resources

You require a DevOps tenant in each region with the required resources (Number of Backing Services, enough storage).

  • The DevOps tenant should have an own URL and name for each region.
  • After the creation of each tenant, you can work on each region with the respective login.

Cloud Foundry

Cloud Foundry is identical in every region. You can push apps in each region without any adjustments.

  • Buildpacks and Backing Services: All buildpacks and Backing Services are equal with respective service plans.
  • Deployment deviations: MindSphere updates are deployed on each region at a different time. This can cause temporary deviations. In order to avoid errors, consider the following:
    • You can use your own custom buildpacks. This allows you to be more independent of MindSphere buildpacks. But, it is required to patch your buildpack and customize the manifest file.
    • Login to Cloud Foundry and check for the available the service plans in "CF Marketplace" and BuildPacks "CF BuildPacks", for each region.
    • Exception on region China 1: The name of the buildpack has a prefix "Offline_". Make sure to adapt the manifest file.

Note

You can avoid dependencies of a buildpack by packing your application into a Docker container and deploying it in Cloud Foundry. If you are using a Docker container to avoid buildpack dependencies, be aware that this functionality is currently only available in region Europe 1.

Credentials

  • The Service Credentials feature is currently only available in region Europe 1. Please do not use this feature in multiple regions apps.
  • You can only use credentials that are permanently stored in an app, in the region they were created.

MindSphere API & Services

For apps in multiple regions, it is important to ensure compatibility with other APIs and Services:

  • You can use older versions of APIs that are compatible on all regions. Please compare the existing versions in the service index and downgrade to the version that is available on each region. You can find the service index under the following link: https://developer.mindsphere.io/apis/index.html.

For example, an API is available in the following versions in each region:

  • Europe 1: 3.12.2
  • Europe 2: 3.11.2
  • China 1: 3.10.1

In order to ensure a compatible API in all regions, use the version 3.10.1.

Performance

Latency and other performance parameters may vary between different regions. This may have impact on the runtime behavior of your application.

Authorization methods

The authorization methods may vary in each region, for example, WebKey with and without MFA login. This can lead to conflicts in automated development pipelines and scripts. Please check the configuration on your automated pipelines.

Outbound IP

The outbound IP addresses may vary in each region. Please check your firewall settings. Detailed information on how to adjust outbound IP addresses for each region can be found here.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.