/20	15	254
/16	255	254	Group of pies and their sizes	`network` on the silk-controller job	An list of CIDR address blocks for the overlay network provided as an + array of strings. Subnets for each Diego Cell are allocated out of this + network. The `subnet_prefix_length` property must be smaller than the + smallest CIDR address block. +	`["10.255.0.0/16"]`
/12	4,095	254	Slice size for each Diego Cell	"subnet_prefix_length" on the silk-controller job	The CIDR mask for each Diego Cell's individual overlay network subnet. + For a `/24` subnet for each Diego Cell, enter `24` This subnet must be + smaller than all individual IP ranges provided in the `network` property. +	`24`

Limitation	Description
Multiple app versions	During a deployment, <%= vars.app_runtime_abbr %> serves both the old and new version of your app at the - same route. This can lead to user issues if you push backwards-incompatible API changes.
Database migrations	Deployments do not handle database migrations. Migrating an app database when the existing - app is not compatible with the migration can result in downtime.
Non-web processes	Canary deployment will only create an instance of the web process.
Quotas	Pushing updates to your app using a canary deployment strategy creates an extra instance - of your app. If you lack sufficient quota, the deployment fails. Administrators might need to increase - quotas to accommodate canary deployments.
Simultaneous apps when interrupting a push	If you push app before your previous push command for the same app has completed, your - first push gets interrupted. Until the last deployment completes, there might be many versions - of the app running at the same time. Eventually, the app runs the code from your most recent - push.
Evaluating the Canary Instance	- Given that the current processes share the same route the best way to validate that traffic is reaching the canary instance by looking at the logs. - The logs for all instance will be tagged with "process_id", and "revision_version". - - Using CF CLI the logs can be retrieved using "cf logs APP_NAME" and search for "revision version" -

`status.value`	`status.reason`	Description
`ACTIVE`	`DEPLOYING`	The deployment is deploying.
`ACTIVE`	`PAUSED`	The deployment is paused waiting for the user to continue with the deployment.
`ACTIVE`	`CANCELLING`	The deployment is cancelling.
`FINALIZED`	`DEPLOYED`	The deployment was deployed.
`FINALIZED`	`CANCELLED`	The deployment was cancelled.
`FINALIZED`	`SUPERSEDED`	The deployment was stopped and did not finish deploying because there was another - deployment created for the app. -

-Note In cf CLI v7+, you can also use --process with cf scale to scale specific processes of your app.

-Important -The following notes include important information about configuring app initialization when you use certain buildpacks: +See the following important information about configuring app initialization when you use certain buildpacks:

Java: Initialization scripts for the Java buildpack require additional configuration. - <% if vars.platform_code != 'CF' %> For more information, see - How to Modify the Application Container Environment prior to Application Execution in the VMware Tanzu Knowledge Base. - <% end %> -

PHP: <%= vars.app_runtime_abbr %> does not support initialization scripts for the PHP buildpack versions prior to v4.3.18. If you use one of these buildpack versions, your app hosts the .profile script's contents. This means that any app staged using the affected buildpack versions can leak credentials placed in the .profile script. @@ -207,7 +201,7 @@ To run initialization tasks: 1. Create a `.profile` script that contains the initialization tasks. -1. Save the `.profile` script to the directory where you run the `cf push` command. +2. Save the `.profile` script to the directory where you run the `cf push` command. The following example `.profile` file uses `bash` to set a value for the environment variable `LANG`: @@ -239,7 +233,7 @@ To specify custom options when pushing an app with `cf push`, you can include th For information about how app settings change from push to push, including how command-line options, manifests, and commands like `cf scale` interact, see [Deploying with App Manifests](manifest.html). -For a full list of `cf push` options, see the [Cloud Foundry CLI reference guide](https://cli.cloudfoundry.org/en-US/cf/push.html). +For a full list of `cf push` options, enter `cf push --help`. ### Configure app services (optional) @@ -253,13 +247,21 @@ For apps that are not already set up for the services that they use: 1. (Optional) Configure the app with the service URL and credentials, if needed. For more information, see [Configuring Service Connections](../../buildpacks/java/configuring-service-connections.html). +### Build custom push workflows (optional) + +The CF CLI includes [composible push sub-step +commands](../push-sub-commands.html) that empower you to build your own push. +These are useful if the default behavior of `cf push` does not match your +needs, or if you want to implement more complicated app build, promotion, and +run workflows. + ## App updates and downtime -When you push an app that is already running, <%= vars.app_runtime_abbr %> stops all existing instances of that app. Users who try to access the app see a `404 Not Found` message while `cf push` runs. +By default, when you push an app that is already running, <%= vars.app_runtime_abbr %> stops all existing instances of that app. Users who try to access the app see a `404 Not Found` message while `cf push` runs. -With some app updates, old and new versions of your code must never run at the same time. A worst-case example is if your app update migrates a database schema, causing old app instances to fail and lose user data. To prevent this, you must stop all running instances of your app before you push the new version. +When old and new versions of your app can run simultaneously, you can avoid app downtime by using [Rolling deployments](./rolling-deploy.html). Alternatively, you can use the blue-green deployment method to swap routes between app versions running in parallel. For more information, see [Using blue-green deployment to reduce downtime and risk](blue-green.html). -When old and new versions of your app can run simultaneously, you can avoid app downtime by using the blue-green deployment method to swap routes between app versions running in parallel. For more information, see [Using blue-green deployment to reduce downtime and risk](blue-green.html). +With some app updates, old and new versions of your code must never run at the same time. A worst-case example is if your app update migrates a database schema, causing old app instances to fail and lose user data. To prevent this, you must stop all running instances of your app before you push the new version. ## Troubleshoot app push problems diff --git a/deploy-apps/environment-variable.html.md.erb b/deploy-apps/environment-variable.html.md.erb index e5bcd749..d2a854bb 100644 --- a/deploy-apps/environment-variable.html.md.erb +++ b/deploy-apps/environment-variable.html.md.erb @@ -15,11 +15,9 @@ Environment variables are the means <%= vars.app_runtime_abbr %> uses to communi For information about setting your own app-specific environment variables, see the [Environment variable](./manifest.html#env-block) in _Deploying with app manifests_.

-Important -Do not use user-provided environment variables for security-sensitive information such as credentials. They might unintentionally show up in cf CLI output and Cloud Controller logs. Use user-provided service instances instead. The system-provided environment variable VCAP_SERVICES is properly redacted for user roles such as Space Supporter and in Cloud Controller log files.

+Do not use user-provided environment variables for security-sensitive information such as credentials. They might unintentionally show up in cf CLI output and Cloud Controller logs. Use user-provided service instances instead. Credentials that are provided to the app through service bindings are redacted for user roles such as Space Supporter and in Cloud Controller log files.

-Important The maximum size of an environment variable is 130 KB. This limit applies also to <%= vars.app_runtime_abbr %> system environment variables such as VCAP_SERVICES and VCAP_APPLICATION.

@@ -27,11 +25,17 @@ The maximum size of an environment variable is 130 KB. This limit applies a Using the Cloud Foundry Command Line Interface (cf CLI), you can run the `cf env` command to view the <%= vars.app_runtime_abbr %> environment variables for your app. The `cf env` command displays the following environment variables: -* The `VCAP_APPLICATION` and `VCAP_SERVICES` variables provided in the container environment - +* The `VCAP_APPLICATION` variable, which contains app metadata * The user-provided variables set using the `cf set-env` command -For more information about the `cf env` command, see [env](http://cli.cloudfoundry.org/en-US/cf/env.html) in the cf CLI documentation. For more information about the `cf set-env` command, see [set-env](http://cli.cloudfoundry.org/en-US/cf/set-env.html) in the cf CLI documentation. +There are 3 possible ways of providing service binding data to apps, see [Credential Delivery Methods](../services/application-binding.html#credential-delivery-methods). Depending on the chosen method there will be one of the following environment variables: + +* [VCAP_SERVICES](#VCAP-SERVICES) +* [SERVICE_BINDING_ROOT](#SERVICE-BINDING-ROOT) (experimental) +* [VCAP_SERVICES_FILE_PATH](#VCAP-SERVICES-FILE-PATH) (experimental) + +For more information about the `cf env` command, enter `cf env --help`.
+For more information about the `cf set-env` command, enter `cf set-env --help`. The following example demonstrates the environment variables `cf env` displays: @@ -102,12 +106,14 @@ The following table lists the system variables available to your application con | `PATH` | x | x | x | | `PORT` | x | | | | `PWD` | x | x | x | +| `SERVICE_BINDING_ROOT` | x | x | x | | `TMPDIR` | x | | x | | `USER` | x | x | x | | `VCAP_APP_HOST` | x | | | | `VCAP_APP_PORT` | x | | | | `VCAP_APPLICATION` | x | x | x | | `VCAP_SERVICES` | x | x | x | +| `VCAP_SERVICES_FILE_PATH` | x | x | x | ### CF_INSTANCE_ADDR @@ -224,6 +230,12 @@ The present working directory where the buildpack that processed the app ran. For example: `PWD=/home/vcap/app` +### SERVICE_BINDING_ROOT (experimental) + +The root directory location, which contains the service binding information. This must be enabled by an app feature flag. See [Service Binding K8s](../services/application-binding.html#service-binding-k8s) for information about how to enable this, and how service binding data is stored in this directory. + +For example: `SERVICE_BINDING_ROOT=/etc/cf-service-bindings` + ### TMPDIR The directory location where temporary and staging files are stored. @@ -272,6 +284,8 @@ This environment variable contains the associated attributes for a deployed app. For bindable services, <%= vars.app_runtime_abbr %> adds connection details to the `VCAP_SERVICES` environment variable when you restart your app, after binding a service instance to your app. For more information about bindable services, see [Services overview](../services/index.html). +This is the default [Credential Delivery Method](../services/application-binding.html#credential-delivery-methods). + <%= vars.app_runtime_abbr %> returns the results as a JSON document that contains an object for each service for which one or more instances are bound to the app. The service object contains a child object for each instance of the service that is bound to the app. The following table defines the attributes that describe a bound service. The key for each service in the JSON document is the same as the value of the "label" attribute. @@ -343,6 +357,11 @@ VCAP_SERVICES= } ~~~ +### VCAP_SERVICES_FILE_PATH (experimental) + +This is the path to the file containing the service binding information in JSON format. It must be enabled by an app feature flag. See [File-based VCAP services](../services/application-binding.html#file-based-vcap-services) for more information. + +For example: `VCAP_SERVICES_FILE_PATH=/etc/cf-service-bindings/vcap_services` ## Environment variable groups diff --git a/deploy-apps/healthchecks.html.md.erb b/deploy-apps/healthchecks.html.md.erb index cba576a8..28b634af 100644 --- a/deploy-apps/healthchecks.html.md.erb +++ b/deploy-apps/healthchecks.html.md.erb @@ -66,11 +66,9 @@ types are `port`, `process`, and `http`. For more information, see [Health check * `LIVENESS-HEALTH-CHECK-TIMEOUT` is the amount of time allowed to elapse between starting an app and the first healthy response. For more information, see [Health check timeouts](#health_check_timeout). -For more information about the `cf push` command, see -[push](http://cli.cloudfoundry.org/en-US/cf/push.html) in the Cloud Foundry CLI Reference Guide. +For more information about the `cf push` command, enter `cf push --help`.

-Important The health check configuration that you provide with cf push overrides any configuration in the app manifest.

@@ -91,15 +89,12 @@ Where: * `CUSTOM-HTTP-ENDPOINT` is the custom HTTP endpoint that you want to add to the health check. By default, an `http` health check uses `/` as its endpoint unless you specify a custom endpoint. For more information, see [Health check HTTP endpoints](#health_check_uri). -You can also change the health check invocation timeout for -an app, use cf set-health-check. This option also requires restarting the app. For more information, see Apps in the Cloud Foundry CLI Reference Guide. +You can also change the health check invocation timeout for an app, use `cf set-health-check`. +This option also requires restarting the app. For more information, enter `cf set-health-check --help`. -For more information about the `cf set-health-check` command, see -[set-health-check](http://cli.cloudfoundry.org/en-US/cf/set-health-check.html) in -the Cloud Foundry CLI Reference Guide. +For more information about the `cf set-health-check` command, enter `cf set-health-check --help`.

-Important After you set the health check configuration of a deployed app with the cf set-health-check command, you must restart the app for the change to take effect.

@@ -145,7 +140,6 @@ circumstances in which to use them: web app is ready to serve HTTP requests. The configured endpoint must respond within one second to be considered healthy.

- Important To prevent false negatives, use a dedicated endpoint for health checks where response time and result do not depend on business logic.

@@ -184,5 +178,4 @@ path portion of a URI that must be served by the app and return `HTTP 200` when This command only checks the health of the default port of the app.

-Important For HTTP apps, <%= vars.company_name %> recommends setting the health check type to http instead of a simple port check.

diff --git a/deploy-apps/large-app-deploy.html.md.erb b/deploy-apps/large-app-deploy.html.md.erb index 6c0130e5..e9290868 100644 --- a/deploy-apps/large-app-deploy.html.md.erb +++ b/deploy-apps/large-app-deploy.html.md.erb @@ -26,6 +26,8 @@ To deploy large apps to <%= vars.app_runtime_abbr %>, ensure that: * The size of each environment variable for your app does not exceed 130 KB. This includes <%= vars.app_runtime_abbr %> system environment variables such as `VCAP_SERVICES` and `VCAP_APPLICATION`. For more information, see [<%= vars.app_runtime_abbr %> environment variables](environment-variable.html). +* If VCAP_SERVICES gets too large, either because of too many service bindings or too much data provided by the services, review the other two [Credential Delivery Methods](../services/application-binding.html#credential-delivery-methods); both of these have a limit of 1 MB. + * You push only the files that are necessary for your app. To meet this requirement, push only the directory for your app, and remove unneeded files or use the `.cfignore` file to specify excluded files. For more information about specifying excluded files, see [Ignore unnecessary files when pushing](prepare-to-deploy.html#exclude) in _Considerations for Designing and Running an App in the Cloud_. * You configure Cloud Foundry Command Line Interface (cf CLI) staging, startup, and timeout settings to override settings in the manifest, as necessary: @@ -37,7 +39,6 @@ To deploy large apps to <%= vars.app_runtime_abbr %>, ensure that: For more information about using the cf CLI to deploy apps, see [Push](../../cf-cli/getting-started.html#push) in _Getting Started with the cf CLI_.

-Important Changing the timeout setting for the cf CLI does not change the timeout limit for <%= vars.app_runtime_abbr %> server-side jobs such as staging or starting apps. You must change server-side timeouts in the manifest. Because of the differences between the <%= vars.app_runtime_abbr %> and cf CLI timeout values, your app might start even though the cf CLI reports App failed. To review the status of your app, run cf apps APP-NAME, where APP-NAME is the name of your app.

diff --git a/deploy-apps/manifest-attributes.html.md.erb b/deploy-apps/manifest-attributes.html.md.erb index df1fce72..db1f6a4e 100644 --- a/deploy-apps/manifest-attributes.html.md.erb +++ b/deploy-apps/manifest-attributes.html.md.erb @@ -32,7 +32,6 @@ applications: ```

-Important If your app name begins with the dash character (-), you cannot interact with the app using the cf CLI. This is because the cf CLI interprets the dash as a flag.

### Add schema version to a manifest @@ -73,7 +72,6 @@ To add variables to an app manifest: command: go_calls_ruby ```

- Note You can also use variables for partial values. For example, you can specify host in your variables file and - route: ((host)).env.com in your manifest file.

1. Run: @@ -115,7 +113,6 @@ memory for `bigapp`. This section explains how to describe optional app attributes in manifests. You can also specify each of these attributes using a command line option. Command-line options override the manifest.

-Important In cf CLI v6, the route component attributes domain, domains, host, hosts, and no-hostname are deprecated in favor of the routes attribute. In cf CLI v7+, these attributes are removed. For more information, see domain, domains, host, hosts, and no-hostname.

@@ -126,7 +123,9 @@ You can refer to a buildpack by name in a manifest or a command-line option. The * **Custom buildpacks:** If your app requires a custom buildpack, you can use the `buildpacks` attribute to specify it in a number of ways: * By name: `BUILDPACK`. - * By GitHub URL: `https://github.com/cloudfoundry/java-buildpack.git`. + * By GitHub URL: + * For the source code repo: `https://github.com/cloudfoundry/java-buildpack.git` or + * For a fully-packaged asset: `https://github.com/cloudfoundry/java-buildpack/releases/download/v4.76.0/java-buildpack-v4.76.0.zip` * By GitHub URL with a branch or tag: `https://github.com/cloudfoundry/java-buildpack.git#v3.3.0` for the `v3.3.0` tag. ``` @@ -138,21 +137,21 @@ You can refer to a buildpack by name in a manifest or a command-line option. The * **Multiple buildpacks:** If you are using multiple buildpacks, you can provide an additional `-b` flag or add an additional value to your manifest: - ``` - --- - ... - buildpacks: - - buildpack_URL - - buildpack_URL - ``` -

- Important -

This feature does not work with the deprecated buildpack attribute. For more information, see - buildpack.
You must specify multiple buildpacks in the correct order: the buildpack uses the app start command given by the final buildpack. For more information, see the multi-buildpack repository on GitHub.

+ ``` + --- + ... + buildpacks: + - buildpack_URL + - buildpack_URL + ``` + +

This feature does not work with the deprecated buildpack attribute. For more information, see + buildpack.
You must specify multiple buildpacks in the correct order: the buildpack uses the app start command given by the final buildpack. For more information, see the multi-buildpack repository on GitHub.

The `-b` command-line flag overrides this attribute. @@ -236,9 +235,24 @@ The `--docker-image` or `-o` command-line flag overrides `docker.image`. The `- The manifest attribute `docker.username` is optional. If it is used, the password must be provided in the environment variable `CF_DOCKER_PASSWORD`. If a Docker user name is specified, then a Docker image must also be specified.

-Important Using the docker attribute with the buildpacks or path attributes causes an error.

+### features + +App features can be set using the manifest attribute `features`. The attribute value is a key-value mapping of app feature names to Boolean values indicating whether the feature is enabled or not. If omitted, a feature is enabled or disabled based on its default value (e.g. `revisions` is enabled by default, and the `ssh` status depends on the configuration of the foundation). + +For example: + +``` +--- + ... + features: + ssh: true + revisions: true + service-binding-k8s: false + file-based-vcap-services: false +``` + ### health-check-type The `health-check-type` attribute sets the `health_check_type` flag to either `port`, `process` or `http`. If you do not provide a `health-check-type` attribute, the default is `port`. @@ -368,6 +382,24 @@ The default number of instances is 1. To ensure that platform maintenance does not interrupt your app, <%= vars.recommended_by %> recommends running at least two instances. +### lifecycle + +The `lifecycle` attribute specifies which application lifecycle to use for staging and running the application. Three variants are supported at the moment: + +- [buildpack](../../buildpacks/classic.html) +- [cnb](../../buildpacks/cnb/index.html) +- [docker](push-docker.html) + +For example: + +``` +--- + ... + lifecycle: buildpack +``` + +The default is `buildpack` unless the [`docker`](#docker) attribute is specified. + ### log-rate-limit-per-second The `log-rate-limit-per-second` attribute specifies the log rate limit for all instances of an app. This attribute requires a unit of measurement: `B`, `K`, `KB`, `M`, `MB`, `G`, or `GB`, in either uppercase or lowercase. @@ -423,7 +455,6 @@ For more information about metadata, see [Using metadata](../../adminguide/metad ### no-route

-Important If you use the no-route flag attribute in the manifest or the flag option, it overrides all route-related attributes.

By default, `cf push` assigns a route to every app. But, some apps process data while running in the background and must not be assigned routes. @@ -536,17 +567,16 @@ The `--random-route` command-line flag overrides this attribute. The `routes` attribute in the manifest provides multiple HTTP and TCP routes. Each route for this app is created if it does not already exist.

-Important This attribute is a combination of push options that include --hostname, -d, and --route-path flags in v6. These flags are not supported in cf CLI v7, so the routes flag must be used.

You can specify the `protocol` attribute to configure which network protocol the route uses for app ingress traffic. This is optional. The available protocols are `http2`, `http1`, and `tcp`.

-Important The protocol route attribute is available only for <%= vars.app_runtime_abbr %> deployments that use HTTP/2 routing. <%= vars.http2_admin_link %>

For example: + ``` --- ... @@ -557,6 +587,26 @@ For example: - route: tcp-example.com:1234 ``` +Under each route, you can optionally include an `options` attribute to configure per-route options as described in [Configuring per-route options](../custom-per-route-options.html). + +Available options are: + +- `loadbalancing` - defines how Gorouter distributes requests across the application backends. Valid values are `round-robin` and `least-connection`. + +For example: + +``` +--- + ... + routes: + - route: example.com + options: + loadbalancing: round-robin + - route: example2.com + options: + loadbalancing: least-connection +``` + #### Manifest attributes If you use the `routes` attribute with the `host`, `hosts`, `domain`, `domains`, or `no-hostname` attributes, an error results. @@ -640,7 +690,6 @@ You can increase the timeout length for very large apps that require more time t The `-t` command-line flag overrides this attribute.

-Important If you configure timeout with a value greater than cc.maximum_health_check_timeout, the Cloud Controller reports a validation error with the maximum limit.

@@ -662,10 +711,9 @@ For example: `cf push` deploys the app to a container on the server. The variables belong to the container environment.

-Important

You must name variables with alphanumeric characters and underscores. Non-conforming variable names might cause unpredictable behavior.
Do not use user-provided environment variables for security sensitive information such as credentials, because they might unintentionally show up in cf CLI output and Cloud Controller logs. Use user-provided service instances instead. The system-provided environment variable VCAP_SERVICES is properly redacted for user roles such as Space Supporter and in Cloud Controller log files.
Do not use user-provided environment variables for security sensitive information such as credentials, because they might unintentionally show up in cf CLI output and Cloud Controller logs. Use user-provided service instances instead. Credentials that are provided to the app through service bindings are redacted for user roles such as Space Supporter and in Cloud Controller log files.

@@ -746,8 +794,7 @@ For example: - instance_XYZ ``` -You can bind an app to a service instance by setting the `VCAP_SERVICES` environment variable. For more information, see [Bind a -service](../services/application-binding.html#bind) in _Delivering Service Credentials to an App_. +For more information, see [Bind a service](../services/application-binding.html#bind) in _Delivering Service Credentials to an App_. ## Deprecated app manifest features @@ -755,7 +802,6 @@ service](../services/application-binding.html#bind) in _Delivering Service Crede This section describes app manifest features that are deprecated in favor of other features.

-Caution Running cf push app -f manifest.yml fails if your manifest uses any of these deprecated features with the feature that replaces it.

### Top-level attributes diff --git a/deploy-apps/push-docker.html.md.erb b/deploy-apps/push-docker.html.md.erb index 5144321f..5929044b 100644 --- a/deploy-apps/push-docker.html.md.erb +++ b/deploy-apps/push-docker.html.md.erb @@ -20,7 +20,6 @@ To push an app based on a Docker image, you need: * The total size of the Docker image file system layers must not exceed the disk quota for the app. The maximum disk allocation for apps is set by the Cloud Controller. The default maximum disk quota is 2048 MB per app.

- Important If the total size of the Docker image file system layers exceeds the disk quota, the app instances do not start.

* The location of the Docker image on Docker Hub or another Docker registry. <%= vars.docker_auth1 %> @@ -276,7 +275,6 @@ Where: * The key.json file must point to the file you created earlier.

-Note For information about specifying YOUR-REGISTRY-URL, see Pushing and Pulling Images in the Google Cloud documentation.

diff --git a/deploy-apps/rolling-deploy.html.md.erb b/deploy-apps/rolling-deploy.html.md.erb index 5bcb3860..28f030aa 100644 --- a/deploy-apps/rolling-deploy.html.md.erb +++ b/deploy-apps/rolling-deploy.html.md.erb @@ -1,12 +1,11 @@ --- -title: Configuring rolling app deployments +title: Configuring app deployments owner: CAPI --- -You can use Cloud Foundry Command Line Interface (cf CLI) commands -or the Cloud Foundry API (CAPI) to push your apps to <%= vars.app_runtime_first %> using a rolling deployment. +This page describes how to use the Cloud Foundry Command Line Interface (cf CLI) or API (CAPI) to push apps to <%= vars.app_runtime_first %> using rolling deployment or canary deployment strategies, which update apps safely and avoid downtime. -For information about the traditional method for addressing app downtime while pushing app updates, +For information about the older method for avoiding app downtime while pushing app updates, see [Using blue-green deployment to reduce downtime and risk](./blue-green.html). For more information about CAPI, see the @@ -19,240 +18,189 @@ The procedures in this topic require one of the following: * **cf CLI v7 or later** -* **CAPI V3:** If you use CAPI V3, you must install the cf CLI. +* **CAPI V3:** If you use CAPI V3 API, you must install the cf CLI. +Or for canary deployments: -## Commands +* **cf CLI v8.8.0 or later** -This section describes the commands for working with rolling app deployments. +* **CAPI V3.173.0 or later** -### Deploy an app +## How Deployment Strategies Work -To deploy an app without incurring downtime: +Cloud Foundry provides two different strategies for deployments: -

-Caution -Review the limitations of this feature before running the command. For more information, see -Limitations.

+* A **Rolling** deployment brings up one or more web processes for the new app version, with the number set by `max-in-flight`, which defaults to 1. After those instances report as healthy and routable, it brings down the same number of instances of the old version. The deployment repeats this process to replace all web process instances, and then updates all old non-web processes. +* A **Canary** deployment brings up one or more web processes for the new app version, defaulting to one. It then pauses to let app operators or developers evaluate the health of a new version instances. App operators can then choose to either `cancel` or `continue` the deployment. When the deployment is continued, the canary deployment proceeds in the same way as a rolling deployment. + * To gradually increase instance counts and check app health in multiple steps, the latest cf CLI v8 supports an `--instance-steps` option that sets a series of increasing instance counts. -* **For cf CLI v7+, run:** +Each rolling or canary deployment increments the `revision` count for the new app deployment, as listed by the `cf revisions` command described in [App Revisions Overview](../revisions.html). - ``` - cf push APP-NAME --strategy rolling - ``` - Where `APP-NAME` is the name that you want to give your app. - -

- Note - cf CLI v7 exits when one instance of each process is healthy. - It also includes a --no-wait flag on push for users who don't want to wait - for the operation to complete. - cf push used with the --no-wait flag exits as soon as one instance is healthy. -

- - If the deployment stops and doesn't restart, cancel it and run it again as described in an earlier step. - To cancel, see [Cancel a deployment](#cancel). - -* **For CAPI V3:** - 1. Log in to the cf CLI. - - ``` - cf login - ``` - 2. Create an empty app by running the following `curl` command with `POST /v3/apps`. Record the - app GUID from the output. - - ``` - cf curl /v3/apps \ - -X POST \ - -H "Content-type: application/json" \ - -d '{ - "name": "APP-NAME", - "relationships": { - "space": { - "data": { - "guid": "SPACE-GUID" - } - } - } - }' - ``` - - Where: -

APP-NAME is the name that you want to give your app.
SPACE-GUID is the space identifier that you want to associate with your app.

- 3. Create a package with the following `curl` command with `POST /v3/packages`. Record the package - GUID from the output. - - ``` - cf curl /v3/packages \ - -X POST \ - -H "Content-type: application/json" \ - -d '{ - "type": "bits", - "relationships": { - "app": { - "data": { - "guid": "APP-GUID" - } - } - } - }' - ``` - Where `APP-GUID` is the app GUID that you recorded in an earlier step. This app GUID is a - unique identifier for your app. - 4. Upload the package bits by running the following `curl` command with - `POST /v3/packages/PACKAGE-GUID/upload`. - - ``` - cf curl /v3/packages/PACKAGE-GUID/upload \ - -X POST \ - -F bits=@"PACKAGED-APP" \ - ``` - - Where: -

PACKAGE-GUID is the package GUID that you recorded in an earlier step.
PACKAGED-APP is your app packaged in a file such as .zip.

- 5. Create the build by running the following `curl` command with `POST /v3/builds`. Record the - droplet GUID from the output. - - ``` - cf curl /v3/builds \ - -X POST \ - -H "Content-type: application/json" \ - -d '{ - "package": { - "guid": PACKAGE-GUID" - } - }' - ``` - Where `PACKAGE-GUID` is the package GUID that you recorded in an earlier step. - 6. Deploy your app by running the following `curl` command with `POST /v3/deployments`. To verify - the status of the deployment or take action on the deployment, record the deployment GUID from the - output. - - ``` - cf curl /v3/deployments \ - -X POST \ - -H "Content-type: application/json" \ - -d '{ - "droplet": { - "guid": "DROPLET-GUID" - }, - "strategy": "rolling", - "relationships": { - "app": { - "data": { - "guid": "APP-GUID" - } - } - } - }' - ``` - Where `DROPLET-GUID` and `APP-GUID` are the GUIDs that you recorded in earlier steps. +The following sections describe the rolling and canary deployment strategies and their limitations. -For more information about this command, see [How it works](#how-it-works). +### Rolling Deployments -### Cancel a deployment +This section describes pushing an app with the rolling deployment strategy. -To stop the deployment of an app that you pushed: +1. The `cf push APP-NAME --strategy rolling` command: + 1. Stages the updated app package. + 2. Creates a droplet with the updated app package. + 3. Creates a deployment with the new droplet and any new configuration. + * This starts up to `max_in_flight` processes that shares the route with the old process. + * If you run `cf app` on your app at this point, you see multiple `web` processes. +
+ For more information about the deployment object, see the [Deployments](http://v3-apidocs.cloudfoundry.org/index.html#deployments) section of the CAPI V3 documentation. -* **For cf CLI v7+, run:** +2. After the command creates the deployment, the `cc_deployment_updater` BOSH job runs in the +background, updating deployments as follows: + 1. Adds up to `max_in_flight` instances of the new web process and removes instances from the old web process. This step repeats until the new web process reaches the required number of instances. +

+ This happens only if all instances of the new web process are running.

+ 2. Removes the old web process. The new web process now fully replaces the old web process. + 3. Restarts all non-web processes of the app. + 4. Sets the deployment to `DEPLOYED`. - ``` - cf cancel-deployment APP-NAME - ``` - Where `APP-NAME` is the name of the app. +### Canary Deployments -* **For CAPI V3, run:** +This section describes pushing an app with the default canary deployment strategy, without specifying specific step weights as described in [Canary Deployments with Step Weights](#canary-step). - ``` - cf curl /v3/deployments/DEPLOYMENT-GUID/actions/cancel" -X POST - ``` - Where `DEPLOYMENT-GUID` is the GUID of the deployment that you recorded after following the - CAPI procedure in [Deploy an app](#deploy). +1. The `cf push APP-NAME --strategy canary` command: + 1. Stages the updated app package. + 2. Creates a droplet with the updated app package. + 3. Creates a deployment with the new droplet and any new configuration. +
+ For more information about the deployment object, see the [Deployments](http://v3-apidocs.cloudfoundry.org/index.html#deployments) section of the CAPI V3 documentation. -This reverts the app to its state from before the deployment started by: +2. After the command creates the deployment, the `cc_deployment_updater` BOSH job runs in the +background, updating deployments as follows: + 1. Adds one instance of the new web process (the `canary` instance). + * This process shares routes with the old process. + * If you run `cf app` on your app at this point, you see multiple `web` processes. + 2. Sets the deployment to `PAUSED`. -* Scaling up the original web process -* Removing any deployment artifacts -* Resetting the `current_droplet` on the app +1. After validating that the canary instance is running as expected, execute the command `cf continue-deployment APP-NAME`: + * Changes the deployment reason to `DEPLOYING` and resumes following the same process as a rolling deployment. -

-Note -The cancel command is designed to revert the app to its -original state as quickly as possible and does not guarantee zero downtime. Additionally, changes -to environment variables and service bindings will not be reverted.

+2. After the command changes the status of the deployment, the `cc_deployment_updater` BOSH job runs in the +background, updating deployments as follows: + 1. Adds MaxInFlight number of instances (**by default it is 1**) of the new web process and removes MaxInFlight number of instance from the old web process. This step repeats until the new web process reaches the required number of instances. +

+ This happens only if all instances of the new web process are running.

+ 2. Removes the old web process. The new web process now fully replaces the old web process. + 3. Restarts all non-web processes of the app. + 4. Sets the deployment to `DEPLOYED`. -### Restart an app +### Canary Deployments with Step Weights -To restart your app without downtime, run the appropriate command. Restart an app to apply -configuration updates that require a restart, such as environment variables or service bindings. +By default, as described in [Canary Deployments](#canary), when you push an app with the canary deployment strategy, the process pauses after it deploys one canary instance, and you manually continue as described in [Continue a canary deployment](#continue) to update the remaining instances to the full-scale deployment. -* **For cf CLI v7+, run:** +To run a canary deployment more gradually, you can pass a series of step weights to the `--instance-steps` option of `cf push`. - ``` - cf restart APP-NAME --strategy rolling - ``` - Where `APP-NAME` is the name of the app. + - The series specifies increasing numbers of canary instances to deploy. + - The deployment will pause after each step, allowing you to manually [continue](#continue) the deployment and proceed to the next step, or [cancel](#cancel) the deployment. + - Each value represents a **percentage** or **weight** of the web process's instances of the web process to be rolled out as canary instances. + - Separate step weights with commas and without spaces, for example `5,10,20`. + - For each canary instance created after the first, a pre-deployment instance is torn down. + - Canary deployments use one extra instance than is normally allocated throughout the deployment process, until the target number of instances has been reached. + - Continuing after the last canary step proceeds to the full-scale deployment. + - As with the default canary deployment process, a rolling deployment strategy updates instances to the new instance count at each step. -* **For CAPI V3, run:** +For example, to update gradually in four steps, running 5, 10, and 20 percent of an app's instances as canary instances before replacing all running instances of an app: - ``` - cf curl /v3/deployments \ - -X POST \ - -H "Content-type: application/json" \ - -d '{ - "droplet": { - "guid": "DROPLET-GUID" - }, - "strategy": "rolling", - "relationships": { - "app": { - "data": { - "guid": "APP-GUID" - } - } - } - }' - ``` - Where `DROPLET-GUID` and `APP-GUID` are the GUIDs that you recorded in earlier steps. + ``` + cf push APP-NAME --strategy canary --instance-steps 5,10,20 + ``` +#### Detailed Example -## How it works +Steps are configured as a percentage of instances rather than as an explicit instance value. This allows the deployment definition to be independent of the number of instances used by a process. -This section describes the rolling deployments and their limitations. +**Cloud Controller matches a step weight to the nearest non-zero instance number, rounding down.** -### Rolling deployment +For example, take an application with 10 instances and the following step configuration: -This section describes pushing an app with a rolling deployment strategy. +``` +cf push APP-NAME --strategy canary --instance-steps 1,20,45,80,100 +``` -1. The `cf push APP-NAME --strategy rolling` command: - 1. Stages the updated app package. - 2. Creates a droplet with the updated app package. - 3. Creates a deployment with the new droplet and any new configuration. - * This starts a new process with one instance that shares the route with the old process. - * Now, if you run `cf app` on your app, you see multiple `web` processes. -
- For more information about the deployment object, see the [Deployments](http://v3-apidocs.cloudfoundry.org/index.html#deployments) section of the CAPI V3 documentation. +This results in the following deployment plan: -2. After the command creates the deployment, the `cc_deployment_updater` BOSH job runs in the -background, updating deployments as follows: - 1. Adds another instance of the new web process and removes an instance from the old web process. This step repeats until the new web process reaches the required number of instances. -

- Important - This happens only if all instances of the new web process are running.

- 2. Removes the old web process. The new web process now fully replaces the old web process. - 3. Restarts all non-web processes of the app. - 4. Sets the deployment to `DEPLOYED`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Step Weight	Original Instances	Canary Instances	Actual Weighting
Pre-deploy	n/a	10	0	0
1	1%	10	1	9%
2	20%	9	2	18%
3	45%	6	5	45%
4	80%	3	8	72%
5	100%	0	10	100%
Post-deploy	n/a	0	10	100%

+ +A **Step Weight** of `100` allows app operators to use the `cancel-deployment` command even after all instances have been replaced. + +

+The cancel command is designed to revert the app to its +original state as quickly as possible and does not guarantee zero downtime. +
It is important to note that changes +to environment variables and service bindings are not reverted.

+ +### Testing Canary Deployments + +To test an in-progress canary deployment, you can route HTTP requests to the canary process, or to an individual canary instance using the `X-Cf-Process-Instance` header, as described in [HTTP headers for process instance routing](../../concepts/http-routing.html#process-instance-routing). + +Alternatively, you can use session affinity to force a particular client to persistently make requests to a canary instance as described in [Session affinity](../../concepts/http-routing.html#sessions). ### Limitations -The following table describes the limitations of when using rolling deployments. +The following table describes the limitations when using these deployments. @@ -262,7 +210,7 @@ The following table describes the limitations of when using rolling deployments. + same route. This can lead to user issues if you push API changes that are not backwards-compatible. @@ -271,7 +219,7 @@ The following table describes the limitations of when using rolling deployments. - - + - @@ -296,17 +244,335 @@ The following table describes the limitations of when using rolling deployments. + + + + + + + + + + + +

Multiple app versions	During a deployment, <%= vars.app_runtime_abbr %> serves both the old and new version of your app at the - same route. This can lead to user issues if you push backwards-incompatible API changes.
Database migrations
Non-web processes	Rolling deployments only run web processes through the rolling update sequence described +	Deployments only run web processes through the update sequence described earlier. The commands restart worker and other non-web processes in bulk after updating all web processes. The CAPI V3 API introduces the concept of processes as runnable units of an app. Each app has a @@ -282,13 +230,13 @@ The following table describes the limitations of when using rolling deployments.
Quotas	Pushing updates to your app using a rolling deployment strategy creates an extra instance - of your app. If you lack sufficient quota, the deployment fails. Administrators might need to increase - quotas to accommodate rolling deployments.	Pushing updates to your app using a deployment strategy creates up to `max_in_flight` new instances (defaults to 1). + Additionally, canary deployments use an extra instance when pausing with the canary instance deployed. + If you lack sufficient quota, the deployment fails. Administrators might need to increase quotas to accommodate deployments.
Simultaneous apps when interrupting a push	If you push app before your previous push command for the same app has completed, your +	If you push an app before your previous push command for the same app has completed, your first push gets interrupted. Until the last deployment completes, there might be many versions of the app running at the same time. Eventually, the app runs the code from your most recent push.
V3 APIs	During a rolling deploy for an app, requests to the V3 APIs for scaling or updating a process fail with an error message - like `Cannot scale this process while a deployment is in flight.`. For more information, see Scale a process + like `Cannot scale this process while a deployment is in flight`. For more information, see Scale a process or Update a process in the CAPI V3 documentation.
New or stopped applications	+ When pushing an application for the first time, or if the app is stopped, no deployment strategy is used and all application instances are started immediately. +
Evaluating the canary instance option 1	+ Because the current processes share the same route, the best way to validate that traffic is reaching the canary instance is by looking at the logs. + If app revision logging is enabled, the logs for all instances will be tagged with `process_id` and `revision_version` values. e.g. `APP/REV/4/PROC/WEB/1` + + + Retrieve the logs by running the cf CLI command `cf logs APP_NAME`. +
Evaluating the canary instance option 2	+ This method only works with routing-release 0.332.0 or higher. + + + Get the canary process guid via `cf curl /v3/deployments?status_values=ACTIVE&app_guid=$(cf app APP_NAME --guid)`. + Add the `X-CF-PROCESS-INSTANCE:` header to traffic + to the app. Optionally, to send traffic to one specific canary instance, + add an index: + `X-CF-PROCESS-INSTANCE::`. +

-## View the status of rolling deployments +## Commands + +This section describes the commands for working with rolling app deployments. + +### Deploy an app + +To deploy an app without incurring downtime: + +#### For cf CLI v7+ + +Run: -You can use CAPI to view the status of rolling deployments. +``` +cf push APP-NAME --strategy rolling +``` -To view the status of a rolling deployment: +Where `APP-NAME` is the name that you want to give your app. + +

+Review the limitations of this feature before running the command. For more information, see +Limitations.

+ +

+cf CLI v7 exits when one instance of each process is healthy. +It also includes a --no-wait flag for users who don't want to wait +for the operation to complete. +When cf push is used with the --no-wait flag, the process exits as soon as one instance is healthy. +

+ +If the deployment stops and doesn't restart, cancel it and run it again as described in an earlier step. +To cancel, see [Cancel a deployment](#cancel). + + +#### For cf CLI v8.8.0+ and CAPI V3.173.0 or later + +Run: + +``` +cf push APP-NAME --strategy STRATEGY --max-in-flight MAX_IN_FLIGHT +``` + +Where: +

APP-NAME is the name that you want to give your app.
MAX_IN_FLIGHT specifies the maximum number of new instances to start up simultaneously until the deployment is complete. This parameter is optional and defaults to 1.
STRATEGY is the strategy you want to use for the deployment. Valid strategies are rolling and canary.

+ +#### For CAPI V3 + +1. Log in to the cf CLI. + + ``` + cf login + ``` + +2. Create an empty app by running the following `curl` command with `POST /v3/apps`.
Record the +app GUID from the output. + + ``` + cf curl /v3/apps \ + -X POST \ + -H "Content-type: application/json" \ + -d '{ + "name": "APP-NAME", + "relationships": { + "space": { + "data": { + "guid": "SPACE-GUID" + } + } + } + }' + ``` + + Where: + +

APP-NAME is the name that you want to give your app.
SPACE-GUID is the space identifier that you want to associate with your app.

+ +1. Create a package with the following `curl` command with `POST /v3/packages`. Record the package +GUID from the output. + + ``` + cf curl /v3/packages \ + -X POST \ + -H "Content-type: application/json" \ + -d '{ + "type": "bits", + "relationships": { + "app": { + "data": { + "guid": "APP-GUID" + } + } + } + }' + ``` + + Where `APP-GUID` is the app GUID that you recorded in an earlier step. This app GUID is a + unique identifier for your app. + +1. Upload the package bits by running the following `curl` command with +`POST /v3/packages/PACKAGE-GUID/upload`. + + ``` + cf curl /v3/packages/PACKAGE-GUID/upload \ + -X POST \ + -F bits=@"PACKAGED-APP" \ + ``` + + Where: + +

PACKAGE-GUID is the package GUID that you recorded in an earlier step.
PACKAGED-APP is your app packaged in a file such as .zip.

+ +1. Create the build by running the following `curl` command with `POST /v3/builds`. Record the +droplet GUID from the output. + + ``` + cf curl /v3/builds \ + -X POST \ + -H "Content-type: application/json" \ + -d '{ + "package": { + "guid": PACKAGE-GUID" + } + }' + ``` + + Where `PACKAGE-GUID` is the package GUID that you recorded in an earlier step. + +1. Deploy your app by running the following `curl` command with `POST /v3/deployments`. To verify +the status of the deployment or take action on the deployment, record the deployment GUID from the +output. + + ``` + cf curl /v3/deployments \ + -X POST \ + -H "Content-type: application/json" \ + -d '{ + "droplet": { + "guid": "DROPLET-GUID" + }, + "strategy": STRATEGY, + "options": { + "max_in_flight": MAX_IN_FLIGHT + }, + "relationships": { + "app": { + "data": { + "guid": "APP-GUID" + } + } + } + }' + ``` + + Where: + +

DROPLET-GUID and APP-GUID are the GUIDs that you recorded in earlier steps.
MAX_IN_FLIGHT is an integer that specifies the maximum number of new instances to start up simultaneously until the deployment is complete. Optional and defaults to 1.
STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

+ +For more information about this command, see [How Deployment Strategies Work](#how-deployment-strategies-work). + +### Cancel a deployment + +To stop the deployment of an app that you pushed: + +* **For cf CLI v7+, run:** + + ``` + cf cancel-deployment APP-NAME + ``` + + Where `APP-NAME` is the name of the app. + +* **For CAPI V3, run:** + + ``` + cf curl /v3/deployments/DEPLOYMENT-GUID/actions/cancel" -X POST + ``` + + Where `DEPLOYMENT-GUID` is the GUID of the deployment that you recorded after following the + CAPI procedure in [Deploy an app](#deploy). + +This reverts the app to its state from before the deployment started by: + +* Scaling up the original web process +* Removing any deployment artifacts +* Resetting the `current_droplet` on the app + +

+ +### Continue a canary deployment + +To finish a canary deployment after the deployment has paused and the canary instance has been validated: + +* **For cf CLI v8+, run:** + + ``` + cf continue-deployment APP-NAME + ``` + Where `APP-NAME` is the name of the app. + +* **For CAPI V3, run:** + + ``` + cf curl /v3/deployments/DEPLOYMENT-GUID/actions/continue" -X POST + ``` + Where `DEPLOYMENT-GUID` is the GUID of the deployment that you recorded after following the + CAPI procedure in [Deploy an app](#deploy). + +This continues the deployment of the app, following the same process as a rolling deployment. + +### Restart an app + +Restart your app to apply configuration updates that require a restart, such as environment variables or service bindings. + +To restart your app without downtime, run the appropriate command as shown here. + +* **For cf CLI v7+, run:** + + ``` + cf restart APP-NAME --strategy STRATEGY + ``` + + Where: +

APP-NAME is the name of the app.
STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

+ +* **For cf CLI v8.8.0+ and CAPI V3.173.0 or later, run:** + + ``` + cf restart APP-NAME --strategy STRATEGY --max-in-flight MAX_IN_FLIGHT + ``` + + Where: +

APP-NAME is the name of the app.
MAX_IN_FLIGHT specifies the maximum number of new instances to restart simultaneous until the deployment is complete. Optional and defaults to 1.
STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

+ +* **For CAPI V3, run:** + + ``` + cf curl /v3/deployments \ + -X POST \ + -H "Content-type: application/json" \ + -d '{ + "droplet": { + "guid": DROPLET-GUID + }, + "strategy": STRATEGY, + "options": { + "max_in_flight": MAX_IN_FLIGHT + }, + "relationships": { + "app": { + "data": { + "guid": APP-GUID + } + } + } + }' + ``` + + Where: +

DROPLET-GUID and APP-GUID are the GUIDs that you recorded in earlier steps.
MAX_IN_FLIGH is an integer that specifies the maximum number of new instances to start up simultaneous until the deployment is complete. Optional and defaults to 1.
STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

+ + +## View the status of deployments + +You can use CAPI to view the status of deployments. + +To view the status of a deployment: 1. Log in to the cf CLI: @@ -319,6 +585,7 @@ To view the status of a rolling deployment: ``` cf app APP-NAME --guid ``` + Where `APP-NAME` is the name of the app. 1. Find the deployment for that app by running: @@ -327,16 +594,16 @@ To view the status of a rolling deployment: cf curl GET /v3/deployments?app_guids=APP-GUID&status_values=ACTIVE ``` Where `APP-GUID` is the GUID of the app. Deployments are listed in chronological order, with - the latest deployment displayed as the last in a list. + the latest deployment displayed as the last in the list. 1. Run: ``` cf curl GET /v3/deployments/DEPLOYMENT-GUID ``` - Where `DEPLOYMENT-GUID` is the GUID of the rolling deployment. + Where `DEPLOYMENT-GUID` is the GUID of the deployment. -`cf curl GET /v3/deployments/DEPLOYMENT-GUID` returns these status properties for rolling deployments: +The `cf curl GET /v3/deployments/DEPLOYMENT-GUID` command returns the following status properties: * `status.value`: Indicates if the deployment is `ACTIVE` or `FINALIZED`. @@ -351,14 +618,20 @@ The following table describes the possible values for the `status.value` and `st properties: - - - + + + + + + + + + @@ -367,7 +640,7 @@ properties: - + @@ -377,8 +650,8 @@ properties: -

`status.value`	`status.reason`	Description
status.value	status.reason	Description
`ACTIVE`	`DEPLOYING`	The deployment is deploying.
`ACTIVE`	`PAUSED`	The deployment is paused waiting for the user to continue with the deployment. Used only for canary Deployments.
`ACTIVE`	`CANCELLING`
`FINALIZED`	`DEPLOYED`	The deployment was deployed.	The deployment is complete.
`FINALIZED`
`FINALIZED`	`SUPERSEDED`	The deployment was stopped and did not finish deploying because there was another - deployment created for the app. +	The deployment was stopped and did not finish deploying because another + deployment was created for the app.

diff --git a/deploy-apps/routes-domains.html.md.erb b/deploy-apps/routes-domains.html.md.erb index 26afe35d..e00a60b8 100644 --- a/deploy-apps/routes-domains.html.md.erb +++ b/deploy-apps/routes-domains.html.md.erb @@ -10,8 +10,8 @@ For more information about routing capabilities in <%= vars.app_runtime_abbr %>, ## Routes -The <%= vars.app_runtime_abbr %> Gorouter routes requests to apps by associating an app with an address, known as a route. This is known as a _mapping_. Use -the cf CLI [cf map-route](https://cli.cloudfoundry.org/en-US/cf/map-route.html) command to associate an app and route. +The <%= vars.app_runtime_abbr %> Gorouter routes requests to apps by associating an app with an address, known as a route. This is known as a _mapping_. +Use the `cf CLI cf map-route` command to associate an app and route. The routing tier compares each request with a list of all the routes mapped to apps and attempts to find the best match. For example, the Gorouter makes the following matches for the two routes `example-app.<%= vars.app_domain %>` and `example-app.<%= vars.app_domain %>/products`: @@ -77,185 +77,195 @@ Apps running on Windows cells cannot use internal, container-to-container routes To create an internal route: 1. Use the [cf map-route](#map-internal-route) command with an [internal domain](#internal-domains). For example: -

-    $ cf map-route app apps.internal --hostname app
-

- * After an internal route is mapped to an app, the route resolves to IP addresses of the app instances. The IP addresses are visible in the application container: -

-        $ cf ssh app
-        vcap@1234:~$ host app.apps.internal
-        app.apps.internal has address 10.255.169.200
-        app.apps.internal has address 10.255.49.7
-        app.apps.internal has address 10.255.49.77
-

- * To resolve individual instances, prepend the index to the internal route. -

-      vcap@1234:~$ host 1.app.apps.internal
-      1.app.apps.internal has address 10.255.49.7
-

- -1. Create a network policy that allows your apps to communicate with each other. By default, apps cannot communicate over the container network. For more -information, see [Configuring container-to-container networking](cf-networking.html) and the [Cloud Foundry CLI reference guide](https://cli.cloudfoundry.org/en-US/cf/add-network-policy.html). + + ```console + $ cf map-route app apps.internal --hostname app + ``` + +

After an internal route is mapped to an app, the route resolves to IP addresses of the app instances. The IP addresses are visible in the application container: + +


+    $ cf ssh app
+    vcap@1234:~$ host app.apps.internal
+    app.apps.internal has address 10.255.169.200
+    app.apps.internal has address 10.255.49.7
+    app.apps.internal has address 10.255.49.77
+

To resolve individual instances, prepend the index to the internal route. + +


+    vcap@1234:~$ host 1.app.apps.internal
+    1.app.apps.internal has address 10.255.49.7
+

+ + +2. Create a network policy that allows your apps to communicate with each other. By default, apps cannot communicate over the container network. For more information, see [Configuring container-to-container networking](cf-networking.html), or enter `cf add-network-policy --help`. ### Create a route When a developer creates a route using the cf CLI, <%= vars.app_runtime_abbr %> determines whether the route is an HTTP or a TCP route based on the domain. To create a HTTP route, a developer must choose an HTTP domain. To create a TCP route, a developer must choose a TCP domain. -Domains in <%= vars.app_runtime_abbr %> provide a namespace from which to create routes. To list available domains for a targeted organization, use the [cf domains](https://cli.cloudfoundry.org/en-US/cf/domains.html) command. For more information about domains, see [Domains](#domains). +Domains in <%= vars.app_runtime_abbr %> provide a namespace from which to create routes. To list available domains for a targeted organization, use the `cf domains` command. For more information about domains, see [Domains](#domains). The following sections describe how developers can create HTTP and TCP routes for different use cases. #### Create an HTTP route with host name -In <%= vars.app_runtime_abbr %>, a host name is the label that indicates a subdomain of the domain associated with the route. Given a domain +In <%= vars.app_runtime_abbr %>, a host name is the label that indicates a subdomain of the domain associated with the route. +Given a domain `<%= vars.app_domain %>`, a developer can create the route `example-app.<%= vars.app_domain %>` by specifying the host name `example-app` with the -[cf create-route](https://cli.cloudfoundry.org/en-US/cf/create-route.html) command as shown in this example: +`cf create-route` command as shown in this example: -

-$ cf create-route <%= vars.app_domain %> --hostname example-app
-Creating route example-app.<%= vars.app_domain %> for org example-org / space example-space as username@example.com...
+```console
+$ cf create-route shared-domain.example.com --hostname example-app
+Creating route example-app.shared-domain.example.com for org example-org / space example-space as username@example.com...
 OK
-

+``` -

-Important -The cf CLI v7 create-route command does not require the space as an argument. It uses the space you are targeting.

+The cf CLI v7 create-route command does not require the space as an argument. It uses the space you are targeting.

This command instructs <%= vars.app_runtime_abbr %> to only route requests to apps mapped to this route for these URLs: -* `http://example-app.<%= vars.app_domain %>` - -* `https://example-app.<%= vars.app_domain %>` +

http://example-app.<%= vars.app_domain %>
https://example-app.<%= vars.app_domain %>
Any path under either of the these URLs, such as http://example-app.<%= vars.app_domain %>/bar

-* Any path under either of the these URLs, such as `http://example-app.<%= vars.app_domain %>/bar` -#### Create an HTTP route without host name +

Create an HTTP route without host name

-This approach creates a route with the same address as the domain itself and is permitted for private domains only. For more information, see [Private -Domains](#private-domains) . +This approach creates a route with the same address as the domain itself and is permitted for private domains only. For more information, see +Private Domains. +
+A developer can create a route from the domain <%= vars.private_app_domain %> with no host name with the cf create-route command: -A developer can create a route from the domain `<%= vars.private_app_domain %>` with no host name with the -[cf create-route](https://cli.cloudfoundry.org/en-US/cf/create-route.html) command: - -

++
 $ cf create-route <%= vars.private_app_domain %>
 Creating route <%= vars.private_app_domain %> for org example-org / space example-space as username@example.com...
 OK
-

+

If DNS is configured correctly, this command instructs <%= vars.app_runtime_abbr %> to route requests to apps mapped to this route from these URLs: +

http://<%= vars.private_app_domain %>
https://<%= vars.private_app_domain %>
Any path under either of these URLs, such as `http://<%= vars.private_app_domain %>/foo

-* `http://<%= vars.private_app_domain %>` - -* `https://<%= vars.private_app_domain %>` - -* Any path under either of these URLs, such as `http://<%= vars.private_app_domain %>/foo` - -If there are no other routes for the domain, requests to any subdomain, such as `http://foo.<%= vars.private_app_domain %>`, fail. +If there are no other routes for the domain, requests to any subdomain, such as http://foo.<%= vars.private_app_domain %>, fail. A developer can also create routes for subdomains with no host names. The following command creates a route from the subdomain -`foo.<%= vars.private_app_domain %>`: +foo.<%= vars.private_app_domain %>: -

++
 $ cf create-route foo.<%= vars.private_app_domain %>
 Creating route foo.<%= vars.private_app_domain %> for org example-org / space example-space as username@example.com...
 OK
-

+

-If DNS is configured for this subdomain, this command instructs <%= vars.app_runtime_abbr %> to route requests to apps mapped to this route from these URLs: +If DNS is configured for this subdomain, this command instructs <%=vars.app_runtime_abbr %> to route requests to apps mapped to this route from these URLs: +

http://foo.<%= vars.private_app_domain %>
https://foo.<%= vars.private_app_domain %>
Any path under either of these URLs, such as http://foo.<%= vars.private_app_domain %>/foo

-* `http://foo.<%= vars.private_app_domain %>` - -* `https://foo.<%= vars.private_app_domain %>` - -* Any path under either of these URLs, such as `http://foo.<%= vars.private_app_domain %>/foo` - -#### Create an HTTP route with wildcard host name +

Create an HTTP route with wildcard host name

An app mapped to a wildcard route acts as a fallback app for route requests if the requested route does not exist. To create a wildcard route, use an asterisk for the host name. - +
A developer can create a wildcard route from the domain `foo.<%= vars.app_domain %>` by running: -

+
 $ cf create-route foo.<%= vars.app_domain %> --hostname '*'
 Creating route *.foo.<%= vars.app_domain %> for org example-org / space example-space as username@example.com...
 OK
-

+

-If a client sends a request to `http://app.foo.<%= vars.app_domain %>` by accident, attempting to reach `example-app.foo.<%= vars.app_domain %>`, -<%= vars.app_runtime_abbr %> routes the request to the app mapped to the route `*.foo.<%= vars.app_domain %>`. +If a client sends a request to http://app.foo.<%= vars.app_domain %> by accident, attempting to reach example-app.foo.<%= vars.app_domain %>, +<%= vars.app_runtime_abbr %> routes the request to the app mapped to the route *.foo.<%= vars.app_domain %>. -#### Create an HTTP route with a path +

Create an HTTP route with a path

Developers can use paths to route requests for the same host name and domain to different apps. - +
A developer can create three routes using the same host name and domain in the space `example-space` by running: +
-

+
 $ cf create-route <%= vars.app_domain %> --hostname store --path products
 Creating route store.<%= vars.app_domain %>/products for org example-org / space example-space as username@example.com...
 OK
-

-+
+
+
 $ cf create-route <%= vars.app_domain %> --hostname store --path orders
 Creating route store.<%= vars.app_domain %>/orders for org example-org / space example-space as username@example.com...
 OK
-

-+
+
+
 $ cf create-route <%= vars.app_domain %> --hostname store
 Creating route store.<%= vars.app_domain %> for org example-org / space example-space as username@example.com...
 OK
-

-
-The developer can then map the new routes to different apps by following the procedure in [Map a route to your app](#map-route).
-
-If the developer maps the first route with path `products` to the `products` app, the second route with path `orders` to the `orders` app, and the last route to the `storefront` app. After this:
+

-* <%= vars.app_runtime_abbr %> routes requests to `http://store.<%= vars.app_domain %>/products` to the `products` app. +The developer can then map the new routes to different apps by following the procedure in +Map a route to your app. -* <%= vars.app_runtime_abbr %> routes requests to `http://store.<%= vars.app_domain %>/orders` to the `orders` app. +If the developer maps the first route with path products to the products app, the second route with path orders to the orders app, and the last route to the storefront app. After this: -* <%= vars.app_runtime_abbr %> routes requests to `http://store.<%= vars.app_domain %>` to the `storefront` app. +

<%= vars.app_runtime_abbr %> routes requests to http://store.<%= vars.app_domain %>/products to the products app.
<%= vars.app_runtime_abbr %> routes requests to http://store.<%= vars.app_domain %>/orders to the orders app.
<%= vars.app_runtime_abbr %> routes requests to http://store.<%= vars.app_domain %> to the storefront app.

<%= vars.app_runtime_abbr %> attempts to match routes with a path, and then attempts to match host and domain.

-Important +Notes:

Routes with the same domain and host name but different paths can only be created in the same space. Private domains do not have this limitation.
<%= vars.app_runtime_abbr %> does not route requests for context paths to the root context of an app. Apps must serve requests on the context path.

-#### Create a TCP route with a port +

Create a TCP route with a port

A developer can create a TCP route for `<%= vars.tcp_app_domain %>` on an arbitrary port. This is the default in the v7 version of the cf CLI. * An arbitrary (random) port is the default. The `--random port` flag is not supported. -

+  ```console
   $ cf create-route example-space <%= vars.tcp_app_domain %> --random-port
   Creating route <%= vars.tcp_app_domain %> for org example-org / space example-space as user@example.com...
   OK
   Route <%= vars.tcp_app_domain %>:60034 has been created
-

+ ``` In this example, <%= vars.app_runtime_abbr %> routes requests to `<%= vars.tcp_app_domain %>:60034` to apps mapped to this route. To request a specific port, a developer can use the `--port` flag, so long as the port is not reserved for another space. To create a TCP route for `<%= vars.tcp_app_domain %>` on port 60035, run: -

+```console
 $ cf create-route example-space <%= vars.tcp_app_domain %> --port 60035
 Creating route <%= vars.tcp_app_domain %>:60035 for org example-org / space example-space as user@example.com...
 OK
-

+``` ### List routes -Developers can list routes for the current space with the [cf routes](https://cli.cloudfoundry.org/en-US/cf/routes.html) command. A route is uniquely identified by the combination of host name, domain, port, and path. +Developers can list routes for the current space with the `cf routes` command. A route is uniquely identified by the combination of host name, domain, port, and path. -

+```console
 $ cf routes
 Getting routes as user@<%= vars.private_app_domain %> ...
 
@@ -266,7 +276,7 @@ example-space   store         <%= vars.app_domain %>		     /products   	      pr
 example-space   store         <%= vars.app_domain %>		     /orders     	      orders
 example-space   store         <%= vars.app_domain %>                	          storefront
 example-space		              <%= vars.app_domain %>	60000 			       tcp    tcp-app
-

+``` Developers can only see routes in spaces where they are a member. Note that cf CLI v7 removes the port and path columns from the output. @@ -276,7 +286,7 @@ Note that cf CLI v7 removes the port and path columns Developers can view a route and its destinations within the current space with the cf route command. A route is uniquely identified by the combination of a host name, domain, port, and path. Note that the `cf route` command is available in cf CLI v8 only. -

+```console
 $ cf route <%= vars.app_domain %> --hostname example-app
 Showing route example-app.<%= vars.app_domain %> in org o / space example-space as admin...
 
@@ -289,27 +299,27 @@ protocol:   http
 Destinations:
         app      process   port   protocol
         mystore  web       8080   http1
-

+``` Developers can only view a route within a space where they are a member. ### Check routes -Developers cannot create a route that is already taken. To find out if a route is available, developers can use the [cf -check-route](https://cli.cloudfoundry.org/en-US/cf/check-route.html) command. +Developers cannot create a route that is already taken. To find out if a route is available, developers can use the +`cf check-route` command. To find out if a route with the host name `store` and the domain `<%= vars.app_domain %>` and the path `products` exists, run: -

+```console
 $ cf check-route <%= vars.app_domain %> --hostname store --path /products
 Checking for route...
 OK
 Route store.<%= vars.app_domain %>/products does exist
-

+``` ### Map a route to your app -For an app to receive requests to a route, developers must map the route to the app with the [cf map-route](https://cli.cloudfoundry.org/en-US/cf/map-route.html) command. If the route does not already exist, this command creates it. +For an app to receive requests to a route, developers must map the route to the app with the `cf map-route` command. If the route does not already exist, this command creates it. Any app that is not routed to port 80 or port 443 must be explicitly mapped using the cf map-route command. Otherwise, the route is mapped to port 443. @@ -317,7 +327,7 @@ You can create and reserve routes for later use by following the procedure in [M Changes to route mappings are run asynchronously. On startup, an app becomes accessible at its route within a few seconds. Similarly, upon mapping a new route to a running app, the app becomes accessible at this route within a few seconds of the CLI exiting. -#### Manually map a route +

Manually map a route

For these routes and apps: @@ -346,57 +356,57 @@ For these routes and apps: The following commands map the routes in the table to their respective apps. Developers use host name, domain, and path to uniquely identify a route to which to map their apps. -

+```console
 $ cf map-route products <%= vars.app_domain %> --hostname store --path products
 $ cf map-route orders <%= vars.app_domain %> --hostname store --path orders
 $ cf map-route storefront <%= vars.app_domain %> --hostname store
 $ cf map-route tcp-app <%= vars.tcp_app_domain %> --port 60000
-

+``` The following command maps the wildcard route `*.foo.<%= vars.app_domain %>` to the app `myfallbackapp`. -

+```console
 $ cf map-route myfallbackapp foo.<%= vars.app_domain %> --hostname '*'
-

+``` In cf CLI v8, the following command maps the route `h2app.<%= vars.app_domain %>` as an HTTP/2 route to the HTTP/2 app `h2app`. -

+```console
 $ cf map-route h2app <%= vars.app_domain %> --hostname h2app --destination-protocol http2
-

+``` -#### Map a route with app push +

Map a route with app push

Developers can map a route to their app with the `cf push` command. As of cf CLI v7, the best way to do this is by using the `routes` property in the manifest. -

+```console
 $ cf push example-app
-

+``` To customize the route during `push`, specify the domain using the `-d` flag and the host name with the `--hostname` flag. The following command creates the `foo.<%= vars.private_app_domain %>` route for `example-app`: -

+```console
 $ cf push example-app -d <%= vars.private_app_domain %> --hostname foo
-

+``` To map a TCP route during `push`, specify a TCP domain and request a random port using `--random-route`. To specify a port, push the app without a route, then create and map the route manually by following the procedure in [Create a TCP route with a port](#create-route-w-port). -

+```console
 $ cf push tcp-app -d <%= vars.tcp_app_domain %> --random-route
-

+``` -#### Map a route using app manifest +

Map a route using app manifest

Developers can map a route to their app with a manifest by editing the `route` attribute to specify the host, domain, port, and path components of the route. For more information, see [Deploying with app manifests](../deploy-apps/manifest.html#routes). -#### Map a route to multiple apps +

Map a route to multiple apps

<%= partial 'routing_conflict' %> For more information about troubleshooting this problem, see [Routing conflict](troubleshoot-app-health.html#routing-conflict) in _Troubleshooting app deployment and health_. -#### Map multiple routes to one app +

Map multiple routes to one app

You can have multiple routes to an app, but those routes cannot have different context paths. @@ -417,7 +427,7 @@ These routes are valid for a single app: -These routes are _not_ valid for a single app: +These routes are not valid for a single app: @@ -434,15 +444,15 @@ These routes are _not_ valid for a single app:

-#### Map an internal route to an app +

Map an internal route to an app

You can map an internal route to any app. This internal route allows your app to communicate with other apps without leaving the platform. After it is mapped, this route becomes available to all other apps on the platform. This example creates a `foo.apps.internal` internal route for `example-app`: -

+```console
 $ cf map-route example-app apps.internal --hostname foo
-

+``` ### Unmap a route @@ -450,19 +460,20 @@ Developers can remove a route from an app using the `cf unmap-route` command. Th To unmap an HTTP route from an app, identify the route using the host name, domain, and path: -

+```console
 $ cf unmap-route tcp-app <%= vars.private_app_domain %> --hostname example-app --path mypath
-

+``` To unmap a TCP route from an app, identify the route using the domain and port: -

+```console
 $ cf unmap-route tcp-app <%= vars.tcp_app_domain %> --port 60000
-

+``` ### Share a route with another space -To follow the procedure in this section, you must use cf CLI v8.5.0 or later. To download cf CLI v8.5.0 or later, see the Cloud Foundry CLI repository on GitHub. +

+To follow the procedure in this section, you must use cf CLI v8.5.0 or later. To download cf CLI v8.5.0 or later, see the Cloud Foundry CLI repository on GitHub.

You can share a route with another space using the `cf share-route` command. To move an app to another space, you can share routes with that space to prevent downtime during the transition. Rather than deleting the route in the original space and re-creating the route in the new space, you can share the route with the new space and map it to the app running in that space. @@ -489,16 +500,14 @@ To share a route with another space: The following example command shares the route `example-app.example.com/example-path` with the `other-space` space in the `other-org` org: -

+      ```console
       cf share-route example.com --hostname example-app --path example-path -s other-space -o other-org
-

+ ``` ### Transfer ownership of a route to another space -

-Important -To follow the procedure in this section, you must use cf CLI v8.5.0 or later. To download cf CLI v8.5.0 or later, see the Cloud Foundry CLI repository on GitHub. -

+To follow the procedure in this section, you must use cf CLI v8.5.0 or later. To download cf CLI v8.5.0 or later, see the Cloud Foundry CLI repository on GitHub.

After sharing a route with another space, you can transfer ownership of the route to that space using the cf move-route command. You can use this command if you are unable to maintain or delete a shared route within the space with which it was shared. For information about sharing routes across spaces, see [Share a route with another space](#share-route). @@ -532,9 +541,9 @@ To move a route: The following example command moves the route `example-app.example.com/example-path` with the `other-space` space in the `other-org` org: -

+      ```console
        cf move-route example.com --hostname example-app --path example-path -s other-space -o other-org
-

+ ``` ### Delete a route @@ -542,47 +551,42 @@ Developers can delete a route from a space using the `cf delete-route` command. To delete a HTTP route, identify the route using the host name, domain, and path: -

+```console
 $ cf delete-route <%= vars.private_app_domain %> --hostname example-app --path mypath
-

+``` To delete a TCP route, identify the route using the domain and port. -

+```console
 $ cf delete-route tcp.<%= vars.private_app_domain %> --port 60000
-

+``` ### Routing requests to a specific app instance Users can route HTTP requests to a specific app instance using the header `X-Cf-App-Instance`. -

-Important -Use of the X-Cf-App-Instance header is available only for users on the Diego architecture. -

- The format of the header is `X-Cf-App-Instance: APP_GUID:APP_INDEX`. `APP_GUID` is an internal identifier for your app. Use the `cf APP-NAME --guid` command to discover the `APP_GUID` for your app. -

+```console
 $ cf app example-app --guid
-

+``` `APP_INDEX`, for example, `0`,`1`, `2`, or `3`, is an identifier for a particular app instance. Use the CLI command `cf app APP-NAME` to get statistics on each instance of a particular app. -

+```console
 $ cf app example-app
-

+``` The following example shows a request made to instance `9` of an app with GUID `5cdc7595-2e9b-4f62-8d5a-a86b92f2df0e` and mapped to route `example-app.<%= vars.private_app_domain %>`. -

+```console
 $ curl example-app.<%= vars.private_app_domain %> -H "X-Cf-App-Instance: 5cdc7595-2e9b-4f62-8d5a-a86b92f2df0e:9"
-

+``` If the `X-Cf-App-Instance` header is set to an invalid value, Gorouter returns a `400` status code and the response from Gorouter contains a `X-Cf-Routererror` header with more information about the error. Before the routing release v0.197.0, Gorouter returned a `404` error. @@ -609,6 +613,72 @@ These are the possible error responses: +### Routing requests to a specific process instance + +Since routing-release version 0.332.0, users can route HTTP requests to a specific +process instance using the header `X-Cf-Process-Instance`. + +The format of the header is `X-Cf-Process-Instance: PROCESS_GUID:PROCESS_INDEX` or `X-Cf-Process-Instance: PROCESS_GUID`. + +`PROCESS_GUID` is an internal identifier for a specific app process. +Use `cf curl /v3/apps/$(cf APP-NAME --guid)/processes` command to discover the `PROCESS_GUID`s related to your app. + +`PROCESS_INDEX`, for example, `0`,`1`, `2`, or `3`, is an identifier for a particular process instance. Use the CLI command `cf app APP-NAME` to get statistics on each +instance of a particular app process. + +```console +$ cf app example-app +``` + +The following example shows a request made to instance `9` of an process with GUID `5cdc7595-2e9b-4f62-8d5a-a86b92f2df0e` and mapped to route +`example-app.<%= vars.private_app_domain %>`. + +```console +$ curl example-app.<%= vars.private_app_domain %> -H "X-Cf-Process-Instance: 5cdc7595-2e9b-4f62-8d5a-a86b92f2df0e:9" +``` + +The following example shows a request made a process with GUID `5cdc7595-2e9b-4f62-8d5a-a86b92f2df0e` and mapped to route +`example-app.<%= vars.private_app_domain %>`. + +```console +$ curl example-app.<%= vars.private_app_domain %> -H "X-Cf-Process-Instance: 5cdc7595-2e9b-4f62-8d5a-a86b92f2df0e" +``` + +If the `X-Cf-Process-Instance` header is set to an invalid value, Gorouter returns a `400` status code and the response from Gorouter contains a +`X-Cf-Routererror` header with more information about the error. + +These are the possible error responses: + + + + + + + + + + + + + + + + + + + + + +

X-Cf-Routererror value	Reason for error +	Response body
`invalid_cf_process_instance_header`	The value provided for `X-Cf-Process-Instance` was an incorrectly formatted GUID.	None
`unknown_route`	The value provided for `X-Cf-Process-Instance` is a correctly formatted GUID, but no backend is found with that GUID and index for the route + requested.	`400 Bad Request: Requested process instance ('1') with guid ('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa') does not exist for route + ('example-route.cf.com')`
`unknown_route`	The value provided for `X-Cf-Process-Instance` is a correctly formatted GUID but no backend is found with that GUID for the route + requested.	`400 Bad Request: Requested process instance with guid ('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa') does not exist for route + ('example-route.cf.com')`

+ + +If the `X-Cf-App-Instance` header and the `X-Cf-Process-Instance` header are +present on the same request, then the `X-Cf-App-Instance` takes presidence. ## Domains @@ -621,14 +691,14 @@ Domains indicate to a developer that requests for any route created from the dom When creating a route, developers select from domains available to them. Use the `cf domains` command to view a list of available domains for the targeted org: -

+```console
 $ cf domains
 Getting domains in org example-org as user@example.com... OK
 name                          status   type
 <%= vars.app_domain %>        shared
 <%= vars.tcp_app_domain %>    shared   tcp
 <%= vars.private_app_domain %>         owned
-

+``` This example displays three available domains: a shared HTTP domain `<%= vars.app_domain %>`, a shared TCP domain `<%= vars.tcp_app_domain %>`, and a private domain `<%= vars.private_app_domain %>`. For more information, see [Shared domains](#shared-domains) and [Private domains](#private-domains). @@ -650,47 +720,46 @@ When using shared domains, you cannot have routes with the same host name and do Shared domains are HTTP by default, but can be configured to be TCP when associated with the TCP router group. -#### Create a shared domain +

Create a shared domain

Admins can create an HTTP shared domain with the `cf create-shared-domain` command: -

+```console
 $ cf create-shared-domain <%= vars.app_domain %>
-

+``` To create a TCP shared domain, first discover the name of the TCP router group. -

-Important -cf CLI v7 does not support TCP routing or creating shared domains with router groups.

+cf CLI v7 does not support TCP routing or creating shared domains with router groups.

+```console
 $ cf router-groups
 Getting router groups as admin ...
 name          type
 default-tcp   tcp
-

+``` Then create the shared domain using the `--router-group` option to associate the domain with the TCP router group. -

+```console
 $ cf create-shared-domain <%= vars.tcp_app_domain %> --router-group default-tcp
-

+``` -#### Delete a shared domain +

Delete a shared domain

Admins can delete a shared domain from <%= vars.app_runtime_abbr %> with the `cf delete-shared-domain` command: -

+```console
 $ cf delete-shared-domain example.com
-

+``` -#### Internal domain +

Internal domain

The internal domain is a special type of shared domain used for app communication internal to the platform. When you activate service discovery, the internal domain `apps.internal` becomes available for route mapping. Admins can configure multiple internal domains. Add a custom internal domain name to the `internal_domains` property on the `bosh-dns-adapter` job. Then create an internal domain using the `--internal` option: -

+```console
 $ cf create-shared-domain <%= vars.app_domain %> --internal
-

+``` The `--router-group` option is not used with internal domains. @@ -704,42 +773,41 @@ When using private domains, you can have routes with the same host name and doma Private domains can be HTTP or HTTPS only. TCP routing is supported for shared domains only. -#### Create a private domain +

Create a private domain

Org managers can create a private domain by running: -

+```console
 $ cf create-private-domain example-org <%= vars.private_app_domain %>
-

+``` Org managers can create a private domain for a subdomain by running: -

+```console
 $ cf create-private-domain example-org foo.<%= vars.private_app_domain %>
-

+``` -#### Sharing a private domain with one or more orgs +

Sharing a private domain with one or more orgs

Org managers can grant or revoke access to a private domain to other orgs if they have permissions for these orgs. As of cf CLI v7, `cf unshare-private-domain` command provides a warning and requires confirmation before it proceeds. -

+```console
 $ cf share-private-domain test-org <%= vars.private_app_domain %>
 
 $ cf unshare-private-domain test-org <%= vars.private_app_domain %>
-

+``` #### Delete a private domain Org managers can delete a domain from <%= vars.app_runtime_abbr %> with the `cf delete-domain` command: -

+```console
 $ cf delete-private-domain <%= vars.private_app_domain %>
-

+``` -

-Important -cf CLI v7 renames the delete-domain command to delete-private-domain.

+cf CLI v7 renames the delete-domain command to delete-private-domain.

### Requirements for parent and child domains @@ -835,9 +903,8 @@ If you use a wildcard as the subdomain name, then your DNS provider can route fr To use your root domain for apps on <%= vars.app_runtime_abbr %>, you can use custom DNS record types like ALIAS and ANAME, if your DNS provider offers them, or you can use subdomain redirection. -

-Note -Root domains are also called zone apex domains.

+Root domains are also called zone apex domains.

If your DNS provider supports using an ALIAS or ANAME record, configure your root domain with your DNS provider to point at a shared domain in <%= vars.app_runtime_abbr %>. @@ -859,11 +926,10 @@ If your DNS provider supports using an ALIAS or ANAME record, configure your roo If your DNS provider does not support ANAME or ALIAS records, you can use subdomain redirection, also known as domain forwarding, to redirect requests for your root domain to a subdomain configured as a CNAME. -

-Important +

If you use domain forwarding, SSL requests to the root domain might fail if the SSL certificate matches only the subdomain. For more information about SSL certificates, see -the Cloud Foundry documentation.

+the Cloud Foundry documentation.

Configure the root domain to point at a subdomain such as `www`, and configure the subdomain as a CNAME record pointing at a shared domain in <%= vars.app_runtime_abbr %>. diff --git a/deploy-apps/ssh-apps.html.md.erb b/deploy-apps/ssh-apps.html.md.erb index 6948aa9c..7738c9b8 100644 --- a/deploy-apps/ssh-apps.html.md.erb +++ b/deploy-apps/ssh-apps.html.md.erb @@ -7,8 +7,8 @@ owner: Diego The Cloud Foundry Command Line Interface (cf CLI) lets you securely log in to remote host virtual machines (VMs) running <%= vars.app_runtime_full %> (<%= vars.app_runtime_abbr %>) app instances. The commands that activate SSH access to apps, and activate, deactivate, and verify permissions for such access are described here.

-Important -The cf ssh command in cf CLI v7+ include the all_proxy environment variable, which allows you to specify a proxy server to activate proxying for all requests. For more information, see ssh in the Cloud Foundry CLI Reference Guide and Use SOCKS5 with cf v3-ssh in Using the cf CLI with a proxy server.

+The cf ssh command in cf CLI v7+ includes the all_proxy environment variable, which allows you to specify a proxy server to activate proxying for all requests. For more information, see Use SOCKS5 with cf v3-ssh in Using the cf CLI with a proxy server. +For command details, enter cf ssh --help

The cf CLI looks up the `app_ssh_oauth_client` identifier in the Cloud Controller `/v2/info` endpoint, and uses this identifier to query the UAA server for an SSH authorization code. On the target VM side, the SSH proxy contacts the Cloud Controller through the `app_ssh_endpoint` listed in `/v2/info` to confirm permission for SSH access. @@ -59,24 +59,24 @@ You must restart your app after enabling SSH access. ### Configuring SSH access at the app level -[cf enable-ssh](http://cli.cloudfoundry.org/en-US/cf/enable-ssh.html) activates SSH access to all instances of an app: +`cf enable-ssh` activates SSH access to all instances of an app:

 $ cf enable-ssh MY-AWESOME-APP

-[cf disable-ssh](http://cli.cloudfoundry.org/en-US/cf/disable-ssh.html) deactivates SSH access to all instances of an app: +`cf disable-ssh` deactivates SSH access to all instances of an app:

 $ cf disable-ssh MY-AWESOME-APP

### Configuring SSH access at the space level -[cf allow-space-ssh](http://cli.cloudfoundry.org/en-US/cf/allow-space-ssh.html) allows SSH access into all apps in a space: +`cf allow-space-ssh` allows SSH access into all apps in a space:

 $ cf allow-space-ssh SPACE-NAME

-[cf disallow-space-ssh](http://cli.cloudfoundry.org/en-US/cf/disallow-space-ssh.html) disallows SSH access into all apps in a space: +`cf disallow-space-ssh` disallows SSH access into all apps in a space:

 $ cf disallow-space-ssh SPACE-NAME

@@ -84,12 +84,12 @@ $ cf disallow-space-ssh SPACE-NAME ## Verify SSH permissions -[cf ssh-enabled](http://cli.cloudfoundry.org/en-US/cf/ssh-enabled.html) verifies whether an app is accessible with SSH: +`cf ssh-enabled` verifies whether an app is accessible with SSH:

$ cf ssh-enabled MY-AWESOME-APP
 ssh support is disabled for 'MY-AWESOME-APP'

-[cf space-ssh-allowed](http://cli.cloudfoundry.org/en-US/cf/space-ssh-allowed.html) verifies whether all apps running within a space are accessible with SSH: +`cf space-ssh-allowed` verifies whether all apps running within a space are accessible with SSH:

 $ cf space-ssh-allowed SPACE-NAME
 ssh support is enabled in space 'SPACE-NAME'
@@ -107,7 +107,7 @@ $ cf ssh MY-AWESOME-APP
 
 ###  Common cf SSH flags
 
-You can tailor [cf ssh](http://cli.cloudfoundry.org/en-US/cf/ssh.html) commands with the following flags, most of which mimic flags for the UNIX or Linux `ssh` command. Run the `cf ssh --help` command for more details.
+You can tailor `cf ssh` commands with the following flags, most of which mimic flags for the UNIX or Linux `ssh` command. Run the `cf ssh --help` command for more details.
 
 * The `-i` flag targets a specific instance of an app. To log in to the VM container hosting the third instance, `index=2`,  of MY-AWESOME-APP, run:
 
@@ -149,17 +149,11 @@ _<%= vars.app_runtime_abbr %> Environment Variables_.
 ##  App SSH access without cf CLI
 
 In addition to `cf ssh`, you can use other SSH clients such as `ssh`, `scp`, or `sftp` to access
-your app, if you have SSH permissions.
+your app via its process GUID, if you have SSH permissions.
 
-Follow one of these procedures to securely connect to an app instance by logging in with a
-specially-formed user name that passes information to the SSH proxy running on the host VM. For the
-password, use a one-time SSH authorization code generated by
-[cf ssh-code](http://cli.cloudfoundry.org/en-US/cf/ssh-code.html).
+> **Note** Previous versions of <%= vars.app_runtime_abbr %> supported SSH access to apps via the app GUID, as archived at Access app SSH using app GUID
 
-* [Access app SSH using process GUID](#process-guid)
-* [Access app sSH using app GUID](#app-guid)
-
-###  Access app SSH using process GUID
+To securely connect to an app instance using its process GUID:
 
 1. Query the `/v2/info` endpoint of the Cloud Controller in your deployment. Record the domain name
 and port number of the `app_ssh_endpoint` field, and the `app_ssh_host_key_fingerprint` field. You
@@ -225,95 +219,6 @@ authorization code returned by `cf ssh-code`. For example:
 
     You have now securely connected to the app instance.
 
-###  Access app SSH using app GUID
-
-1. Display the GUID of your target app by running:
-
-    ```console
-    cf app APP-NAME --guid`
-    ```
-    Where `APP-NAME` is the name of the app.
-
-    For example:
-    -    $ cf app my-app --guid
-    abcdefab-1234-5678-abcd-1234abcd1234
-    
-
-1. Query the `/v2/info` endpoint of the Cloud Controller in your deployment. Record the domain name
-and port number of the `app_ssh_endpoint` field, and the `app_ssh_host_key_fingerprint` field. You can compare the `app_ssh_host_key_fingerprint` with the fingerprint returned by the SSH proxy on your target VM. For example:
-
-    -    $ cf curl /v2/info
-    {
-         ...
-         "app_ssh_endpoint": "ssh.example.com:2222",
-         "app_ssh_host_key_fingerprint": "a6:14:c0:ea:42:07:b2:f7:53:2c:0b:60:e0:00:21:6c",
-         ...
-    }
-    
-
-    In this example:
-    
-      The domain name is ssh.example.com.
-      The port number is 2222.
-      The fingerprint is a6:14:c0:ea:42:07:b2:f7:53:2c:0b:60:e0:00:21:6c.
-    
-
-
-1. Run `cf ssh-code` to obtain a one-time authorization code that substitutes for an SSH password. You can run `cf ssh-code | pbcopy` to copy the code to the clipboard. For example:
-
-    -    $ cf ssh-code
-    E1x89n
-    
-
-1. Run your `ssh` or other command to connect to the app instance.
-    - SSH into the container hosting the first instance of your app by running:
-
-        ```console
-        ssh -p `SSH-PORT` cf:APP-GUID/APP-INSTANCE-INDEX@SSH-ENDPOINT
-        ```
-
-        Where:
-        
-          SSH-PORT is the port number recorded in earlier steps.
-          APP-GUID comes from earlier steps.
-          APP-INSTANCE-INDEX is the index of the instance that you want to access.
-          SSH-ENDPOINT comes from the  earlier steps and is in the form ssh.MY-DOMAIN.com.
-        
-
-        For example:
-        -        $ ssh -p 2222 cf:abcdefab-1234-5678-abcd-1234abcd1234/0@ssh.example.com
-        
-    - Or you can use `scp` to transfer files by running one of the following commands:
-
-        ```console
-        scp -P `SSH-PORT` -o User=cf:APP-GUID/APP-INSTANCE-INDEX ssh.MY-DOMAIN.com:REMOTE-FILE-TO-RETRIEVE LOCAL-FILE-DESTINATION
-        ```
-        ```console
-        scp -P `SSH-PORT` -o User=cf:APP-GUID/APP-INSTANCE-INDEX LOCAL-FILE-TO-COPY ssh.MY-DOMAIN.com:REMOTE-FILE-DESTINATION
-        ```
-    - Or you can use `ssh` piped with `cat` to transfer the file:
-
-        ```console
-        cat local_file_path | cf ssh MY-AWESOME-APP -c "cat > remote_file_path"
-        ```
-
-2. When the SSH proxy reports its RSA fingerprint, confirm that it matches the `app_ssh_host_key_fingerprint` recorded previously. When prompted for a password, paste in the authorization code returned by `cf ssh-code`, for example:
-
-    -    $ ssh -p 2222 cf:abcdefab-1234-5678-abcd-1234abcd1234/0@ssh.MY-DOMAIN.com
-    The authenticity of host '[ssh.MY-DOMAIN.com]:2222 ([203.0.113.5]:2222)' can't be established.
-    RSA key fingerprint is a6:14:c0:ea:42:07:b2:f7:53:2c:0b:60:e0:00:21:6c.
-    Are you sure you want to continue connecting (yes/no)? yes
-    Warning: Permanently added '[ssh.MY-DOMAIN.com]:2222 [203.0.113.5]:2222' (RSA) to the list of known hosts.
-    cf:d0a2e11d-e6ca-4120-b32d-140@ssh.ketchup.cf-app.com's password:
-    vcap@ce4l5164kws:~$
-    
-
-You have now securely connected to the app instance.
 
 ##  SSH proxy security configuration
 
@@ -419,7 +324,6 @@ When present, `host_fingerprint` declares the expected fingerprint of the SSH da
 ```
 
 
-Important
 To avoid security exposure, migrate your apps and custom buildpacks to use the cflinuxfs4 stack based on Ubuntu 22.04 LTS (Jammy Jellyfish). The cflinuxfs3 stack is based on Ubuntu 18.04 (Bionic Beaver), which reaches end of standard support in April 2023.
 
 ### Daemon discovery
diff --git a/deploy-apps/ssh-services.html.md.erb b/deploy-apps/ssh-services.html.md.erb
index 7580d0e8..e38efb1c 100644
--- a/deploy-apps/ssh-services.html.md.erb
+++ b/deploy-apps/ssh-services.html.md.erb
@@ -14,7 +14,6 @@ _This topic requires Cloud Foundry Command Line Interface (cf CLI) v6.15.0 or la
 <%= vars.mutual_tls_ssh %>
 
 
-Important
 The procedure in this topic requires use of a service key, and not all services support service keys. Some services support credentials through app binding only.
 
 
@@ -29,7 +28,7 @@ The procedure in this topic requires use of a service key, and not all services
     <%=vars.ssh_marketplace_output %>

-1. Create your service instance. As part of the [create-service](http://cli.cloudfoundry.org/en-US/cf/create-service.html) command, indicate the service name, the service plan, and the name you choose for your service instance. +1. Create your service instance. As part of the `cf create-service` command, indicate the service name, the service plan, and the name you choose for your service instance.

     $ cf create-service <%=vars.ssh_service %> <%=vars.ssh_service_plan %> MY-DB
@@ -58,13 +57,13 @@ To activate SSH access to your app, SSH access must also be activated for both t
 
 To establish SSH access to your service instance, you must create a service key that contains critical information for configuring your SSH tunnel.
 
-1. Create a service key for your service instance using the [cf create-service-key](http://cli.cloudfoundry.org/en-US/cf/create-service-key.html) command.
+1. Create a service key for your service instance using the `cf create-service-key` command.
 
     ```console
     cf create-service-key MY-DB EXTERNAL-ACCESS-KEY
     ```
 
-1. Retrieve your new service key using the [cf service-key](http://cli.cloudfoundry.org/en-US/cf/service-key.html) command.
+2. Retrieve your new service key using the `cf service-key` command.
 
     ```console
     cf service-key MY-DB EXTERNAL-ACCESS-KEY
@@ -81,7 +80,7 @@ To establish SSH access to your service instance, you must create a service key
 
 ##  Configure your SSH tunnel
 
-Configure an SSH tunnel to your service instance using [cf ssh](http://cli.cloudfoundry.org/en-US/cf/ssh.html). Tailor the following example command with information from your service key.
+Configure an SSH tunnel to your service instance using the `cf ssh` command. Tailor the following example command with information from your service key.
 $ cf ssh -L 63306:<%= vars.ssh_service_host %>:3306 YOUR-HOST-APP
 
    * You can use any available local port for port forwarding; for example, `63306`.
diff --git a/deploy-apps/stacks.html.md.erb b/deploy-apps/stacks.html.md.erb
index ff0082ba..c1afa39c 100644
--- a/deploy-apps/stacks.html.md.erb
+++ b/deploy-apps/stacks.html.md.erb
@@ -22,13 +22,12 @@ You can also use the Stack Auditor plug-in for the Cloud Foundry Command Line In
 A stack is a prebuilt root file system (rootfs) that supports a specific operating system. For example, Linux-based systems need `/usr` and `/bin` directories at their root. The stack works in tandem with a buildpack to support apps running in compartments. Under Diego architecture, cell VMs can support multiple stacks.
 
 
-Note
 Docker apps do not use stacks.
 
 
 ##  Available stacks
 
-<%= vars.product_short %> <%= vars.current_major_version ? "v#{vars.current_major_version}" : "" %> includes support for `cflinuxfs3`. The Linux `cflinuxfs3` stack is derived from Ubuntu Bionic 18.04. For more information about supported libraries, see the [GitHub stacks page](https://github.com/cloudfoundry/cflinuxfs3/blob/main/receipt.cflinuxfs3.x86_64).
+Cloud Foundry includes support for `cflinuxfs3`. The Linux `cflinuxfs3` stack is derived from Ubuntu Bionic 18.04. For more information about supported libraries, see the [GitHub stacks page](https://github.com/cloudfoundry/cflinuxfs3/blob/main/receipt.cflinuxfs3.x86_64).
 
 The latest versions of <%= vars.product_short %> include support for `cflinuxfs4` which is derived from Ubuntu 22.04 LTS (Jammy Jellyfish). For more information, see [GitHub cflinuxfs4 stack receipt](https://github.com/cloudfoundry/cflinuxfs4/blob/main/receipt.cflinuxfs4.x86_64).
 
diff --git a/deploy-apps/stop-delete.html.md.erb b/deploy-apps/stop-delete.html.md.erb
index dde9217e..66af01bb 100644
--- a/deploy-apps/stop-delete.html.md.erb
+++ b/deploy-apps/stop-delete.html.md.erb
@@ -29,7 +29,6 @@ Example:
 ##  Delete an app
 
 
-Caution
 Deleting an app is irreversible. We recommend that you run cf target before you start to confirm you are deleting the app from the correct org and space.
 
 Many apps use services and routes. Deleting an app does not delete the services used by the app, and you must explicitly remove routes between your app and the Internet.
@@ -55,7 +54,6 @@ Example:
 $ cf delete -r my-example-app
 
 
-Important
 In cf CLI v7+, -r no longer deletes routes when the route is mapped to more than one app.
 
 If you delete an app without the `r` option, you can delete the route manually.
diff --git a/deploy-apps/streaming-logs.html.md.erb b/deploy-apps/streaming-logs.html.md.erb
index 75f95173..dcaa465b 100644
--- a/deploy-apps/streaming-logs.html.md.erb
+++ b/deploy-apps/streaming-logs.html.md.erb
@@ -111,6 +111,18 @@ For example:
 2016-06-14T14:10:15.18-0700 [APP/0]      OUT Exit status 0

+The logs allow you to determine the particular revision and process of the application instance logging. + +For example, below shows the log line from two different revisions and web instances. +

+2022-09-15T01:59:33.99+0000 [APP/REV/2/PROC/WEB/0] OUT hello world from new
+2022-09-15T01:59:34.99+0000 [APP/REV/1/PROC/WEB/1] OUT hello world from old
+

+ +

+Logs with revision id are only available if the application uses revisions and it is enabled in the platform

+ + Each app might have a configured log rate limit. If the app logs exceed the configured log rate limit, you see a log entry indicating that the limit was exceeded. For example: @@ -129,7 +141,7 @@ For example: 2016-06-14T14:16:11.49-0700 [SSH/0] OUT Successful remote access by 192.0.2.33:7856

Property	Value
network	`["10.255.0.0/20", "10.255.96.0/21", "10.255.200.0/23", "10.255.220.0/24"]`
subnet_prefix_length	`24`
Invalid reason	`subnet_prefix_length` must be smaller than all CIDRs in the `network`. In this case it is the same size as `10.255.220.0/24`.

Resource	Description	Command	Commands
App	+ `cf app` + `cf apps` `cf create-app`	`cf create-package` + `cf packages`
Build	Staging the app. Creating a build combines a Package with a Buildpack and builds it into an executable resource. +	Staging the app. Creating a build combines a Package with a Buildpack and builds it into an executable resource, called a Droplet. For more information, see Builds in the CAPI documentation.	@@ -66,6 +66,8 @@ The cf CLI v6 commands described in this topic are experimental and unsupported, For more information, see Droplet in the CAPI documentation.	+ `cf download-droplet` + `cf droplets` `cf set-droplet`	- `cf create-app-manifest`, `cf apply-manifest` + `cf apply-manifest` + `cf create-app-manifest`

Property	Value
Overlay subnet mask	Number of cells	Cell prefix length	Containers per cell	network	`["10.255.0.0/20", "10.255.96.0/21", "10.255.200.0/23", "10.255.220.0/32"]`
/16	255	/24	254	subnet_prefix_length	`24`
/16	255	/26	62	Invalid reason	`subnet_prefix_length` must be smaller than all CIDRs in the `network`. In this case it is larger than `10.255.220.0/32`.

Property	Value
network	`["10.255.0.0/20", "10.255.0.0/16"]`
subnet_prefix_length	`24`
/16	255	/28	14	Invalid reason	`network` must not have any overlapping IP ranges. In this case `10.255.0.0/20` is a subset of `10.255.0.0/16`.