6. Metadata: Overview
Cloud Foundry provides the ability to add metadata to resources such as spaces and apps. This metadata provides additional information about the resources in your Cloud Foundry deployment. This can be a useful tool when operating, monitoring, and auditing Cloud Foundry.
There are two types of metadata: labels and annotations.
6.1 Labels
Labels are key-value pairs that allow you to identify and select Cloud Foundry resources. Labels are searchable. For example, if you have labeled all apps running in development, or all spaces containing internet-facing apps, you can then find those apps by searching for their labels.Labels can be set via the CLI. Let’s add some labels to our training-app:
cf set-label app training-app env=dev
We should be able to see that our labels have been set correctly in the app details:
cf labels app training-app
Now we can use labels as a search function to list all of the apps with the key/value env=dev:
cf apps --labels 'env=dev'
Multiple labels can be used to filter search results. Let’s add another:
cf set-label app training-app sensitive=true
Now we can search for both labels using a comma-separated list:
cf apps --labels 'env=dev,sensitive=true'
The only app shown in the output should be the training-app.
Like always, labels should be added to the app manifest.
metadata: labels: sensitive: true
6.2 Annotations
Annotations allow you to add non-identifying metadata to CF resources. Unlike labels, you can’t query based on annotations, and there are fewer restrictions than for key-value pairs. For example, you could include information about how the resource was deployed (via CI or non-CI), or tool information for debugging purposes.
Annotations cannot be added using a regular CLI command. Instead you’ll need to add them via the app manifest. In an app manifest, annotations are included in the metadata block:
metadata: annotations: contact: "bob@example.com" labels: env: dev
7. scale
7.1 Horizontal Scaling
When you scale an application horizontally, you manipulate the number of instances of that application up or down, usually in response to an increased or reduced user load.
In Cloud Foundry, horizontal scaling doesn’t result in downtime as traffic is only routed to available instances. When new instances are created, traffic isn’t routed to those instances until they pass a healthcheck (we’ll cover healthchecks later in this course).
Let’s start by scaling the training-app up to two instances:
cf scale -i 2 training-app
You can see the instances have been scaled successfully by running cf app training-app and observing instances: 2/2 in the output.
7.2 Vertical Scaling
When you scale an application vertically, you are manipulating the resources allocated for each application instance container. In Cloud Foundry, you can change memory and disk allocations.
Let’s scale the training-app instances down in both disk and memory.
cf scale -m 48M -k 256M training-app
What happened? Scaling vertically involves downtime as the containers are recreated with different resource allocations. This is an important point to consider when scaling vertically in production. Therefore, you should strive to right-size your resource allocations per instance during development and rely on horizontal scaling in production.
You can view the allocations for an app by running cf app .
As always, if you’d like to make any scaling changes permanent, these values should be updated in a version-controlled app manifest. For example:
--- applications: - name: training-app memory: 48M disk-quota: 256M instances: 2
7.3 A Quick Word on the App Autoscaler
The scaling techniques described on the previous pages are manual; they must be performed by a human to take effect. The App Autoscaler is an optional component that may be available in the Cloud Foundry instance you are using. This is a Cloud Foundry extension project, implemented as a marketplace service, and automatically scales apps based on performance metrics or a schedule.
Here are a few examples:
Automatically scale down the number of app instances over the weekend and back up Monday morning.
Automatically scale up the number of instances when CPU usage exceeds a custom threshold and back down when it drops below a threshold.
The App Autoscaler is outside the scope of this course, but you can learn more online.
8. Logs: Overview
As a developer, you will frequently access application logs to debug your apps. Cloud Foundry uses a component called ‘Loggregator’ for streaming log output from applications and Cloud Foundry system components (in this course, we’ll focus on application logs). Logs are incredibly helpful when troubleshooting. Common issues you might see are apps running out of memory, route collisions, or pushing the wrong application payload.
8.1 Following Logs in Real-Time
The CLI can stream new logs to your terminal:
cf logs training-app
You won’t see any output until you access the training-app. Open the training-app URL and hit refresh a few times. Now that you’ve generated some traffic, log output should appear. You should see logs from the Cloud Foundry routers tagged with [RTR/].
You can exit streaming with CTRL-C, or you can continue to stream and start a new terminal window.
Note: The log streaming functionality uses a websocket to stream logs in near real-time. If you cannot stream logs while on a corporate network, you should check with the network administrators to ensure websockets are allowed。
8.2 Inspecting Recent Logs
You can also pass the --recent parameter to view only the recent logs for an app. This is useful if your application is producing a large volume of logs:
cf logs --recent training-app
The --recent buffer is finite in both space and time. If your app has been idle for a long period, you may not see anything in the recent logs.
8.3 Log Drains
As mentioned at the start of this section, by default the Loggregator streams logs to your terminal. Logs can be drained to a third-party log management service via syslog forwarding if you need to persist or analyze logs.
Optional information on log drains is available online.
8.4 Events
There are two main types of Cloud Foundry events: audit events and usage events. Audit events are largely used to monitor actions taken against resources, such as app restarts, stops, scaling, route mapping, and many more.You can view the most recent events of an app with
cf events app-name
Alongside each event you should be able to see the user that executed that particular event.
Optional information on events is available here: https://docs.cloudfoundry.org/running/managing-cf/audit-events.html.
Container Metrics
Metrics for Cloud Foundry application containers can be made available for viewing via CLI plugins (more on these later). While container metrics are outside the scope of this course, it is useful to know of their existence. Optional information on metrics is available here: https://docs.cloudfoundry.org/loggregator/container-metrics.html.
9. Resiliency: Overview
By performing cf scale, you asked Cloud Foundry to ensure you have two instances of the app running. Behind the scenes, Cloud Foundry is ensuring this is so. Let’s test it.To see this happen, we can watch the logs. In a terminal window, tail the logs:
cf logs training-app
9.1 Killing an App Instance
The application has a /kill endpoint that will crash the instance programmatically.
WARNING: Don’t build apps with a /kill endpoint! This is for training purposes only.
Go to your application in a browser. Tack on /kill to the URL and hit Enter. You will see a ‘502 Bad Gateway’ error as you will have killed this instance. Quickly switch back to the terminal window where you are tailing the logs. You should see that Cloud Foundry (very quickly) detects an instance is missing and creates a new one.
If you go back to your browser, remove the /kill from the URL, you should be able to refresh and see that you are only being routed to the live instance. Once the new instance starts up, Cloud Foundry once again load balances across the healthy instances.
When you are ready, you can stop tailing the logs by hitting CTRL-C in the terminal window.
9.2 Pretty Cool. So What Happened?
Cloud Foundry is constantly monitoring the actual count of the running application instances and comparing that number to the desired count. If it finds an issue, Cloud Foundry will correct it (in our case, by creating a new instance). And just like during scaling, when the new instance becomes available, Cloud Foundry routes traffic to it. Cloud Foundry knows an instance unhealthy if it fails a health check. We discuss health checks later in the course.
And what didn’t happen?
A lot. All apps get this level of care from Cloud Foundry. You don’t have to do anything other than use Cloud Foundry.
10. Quotas: Review
Quotas are named sets of memory, service, and instance usage limits. They can be applied at the org level or the space level. Org quotas are mandatory, while space quotas are optional. Org-level quotas are shared across all spaces in that org.
Typically, Cloud Foundry operators will establish quotas for orgs, and OrgManagers will establish quotas for spaces. So while it’s not crucial that developers know how to manage quotas, it is important you understand how to view the quotas for your orgs and spaces. After all, resource planning is a collaborative effort.
10.1 Org Quotas
Let’s take a look at what quota is on your current org:
cf org <org-name>
Once you’ve retrieved the quota, you can view its details:
cf org-quota <quota-name>
The output should show the resource limits on your org.
10.2 Space Quotas
As mentioned previously, quotas can be scoped at both the org and space level. Like org quotas, we can check what quota is applied on a space, by running
cf space <space-name>
If a space doesn’t have an associated quota, then this value will be empty in the cf space output. If you have a space quota set, then do
cf space-quota <quota-name>
to see the details of that quota.
11. Application Security Groups: Overview
Application Security Groups (ASGs) are a collection of egress rules that list protocols, ports, and IP address ranges where an app or task is allowed to connect to (where your app can reach out to). ASGs define ‘allow’ rules. When ASGs are applied to the same space or deployment, their order of evaluation is unimportant; ASG’s are additive.
ASGs can only be created or updated by admins. However, as ASGs dictate the outbound connectivity allowed, it is important to understand them as a developer.
Whenever application security groups are added, updated, or removed, you must restart your app for the changes to take effect.
11.1 Staging and Running ASGs
Security groups can be applied globally - to all orgs and spaces - by assigning them to either the staging or running ASG set. ASGs in the staging set determine the egress allowed during app staging, while those in the running set do so for app and task runtime.
When apps and tasks begin staging, they need traffic rules permissive enough to allow them to pull dependencies from the network. A running app or task is likely to have fewer needs of this sort, so ASGs applied during staging are often more permissive than those applied during the running lifecycle.To view the ASGs for staging:
cf staging-security-groups
And for running ASGs:
cf running-security-groups
Once you’ve retrieved the name of the ASG you want to inspect, you can view the details of those rules:
cf security-group <security-group-name>
This will output a JSON object like so:
[ { "protocol": "tcp", "destination": "0.0.0.0/0", "ports": "53" }, { "protocol": "udp", "destination": "0.0.0.0/0", "ports": "53" } ]
The above example is one of the two ASGs preconfigured in open-source installations of Cloud Foundry (commercial distributions may have different defaults). The ASG, named dns, permits egress on port 53 over TCP and UDP to any IP address.
The other default ASG, public_networks, has the effect of blocking outbound traffic to the following private IP address ranges by omitting them from the ranges that it does permit:
10.0.0.0 - 10.255.255.255 169.254.0.0 - 169.254.255.255 172.16.0.0 - 172.31.255.255 192.168.0.0 - 192.168.255.255
Of course, egress to these IP address ranges will be permitted if another ASG is created allowing egress to them.
11.2 Space-scoped ASGs
It is also possible for admins to bind ASGs to a specific space. In such cases, the space-specific ASGs are combined with the platform ASGs to determine the rules for that space.
You will still need an admin to create ASGs that you want to apply to a particular space, but, once created, a Space Manager can bind the ASG to their space with the following command:
cf bind-security-group <SECURITY-GROUP> <ORG> --space <SPACE>
By default, this will apply the ASG as a running security group in the space. To instead set it as a staging security group use the --lifecycle flag.
