v3 docs: Split upgrade guide into multiple files

The upgrade guide was previously all a single file, and it was getting
quite large. This change splits each section into its own file, just
like the rest of the docs.

Authored-by: Reid Mitchell <rmitchell@pivotal.io>

Author: reidmit

docs/v3/source/includes/upgrade_guide/_header.md

@@ -0,0 +1,9 @@
+# Upgrade Guide
+
+This document is intended to help client authors upgrade from Cloud Foundry's V2 API to the V3 API.
+
+When moving to the V3 API, it is important to understand that the V3 API is backed by the same data as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF will be the same across both APIs.
+
+If you have questions, need help, or want to chat about the upgrade process, please reach out to us in [Cloud Foundry Slack](https://cloudfoundry.slack.com/messages/C07C04W4Q).
+
+

docs/v3/source/includes/upgrade_guide/changed_resources/_audit_events_in_v3.md

@@ -0,0 +1,36 @@
+### Audit Events in V3
+
+In V2, these were called "events" (e.g. `/v2/events`). In V3, we adopt the term
+"audit events" to better distinguish them from usage events.
+
+V2 audit events contained information about the "actee" (the resource that the
+event affected). V3 audit events refer to the affected resource as the "target".
+
+V2 audit events had a `timestamp` field. In V3, this field has been renamed to
+`created_at` for consistency with other resources. The value is the same.
+
+In general, V3 audit events contain all of the same information that they
+contained in V2, but the JSON is structured a little differently. In particular:
+
+- The `metadata` field has been renamed to `data`.
+- Actor-related fields have been grouped into an object under the `actor` key
+  (e.g. `actor.type` instead of `actor_type`).
+- Actee-related fields have been grouped under the `target` key (e.g.
+  `target.type` instead of `actee_type`).
+
+At the time of this writing, V3 does not support greater-than or less-than
+filtering for the `created_at` field. In V2, this was supported via
+`/v2/events?q=timestamp>some_timestamp`. There are plans support this in the
+future.
+
+V3 endpoints attempt to report audit events in the same way as V2 endpoints did.
+A notable case where this was not possible is for the `audit.app.restage` event.
+In V2, there was a restage-app endpoint, and this event was reported when that
+endpoint was used. In V3, the concept of "staging" has been broken down into
+composable pieces (creating packages, creating builds to produce droplets,
+assigning droplets, etc.). There is no longer a clear concept of "restaging" on
+the V3 API. Instead, it is suggested to rely on events corresponding to these
+individual steps (e.g. `audit.app.package.create`, `audit.app.build.create`,
+`audit.app.droplet.create`).
+
+Read more about the [audit event resource](#audit-events).

docs/v3/source/includes/upgrade_guide/changed_resources/_domains_in_v3.md

@@ -0,0 +1,7 @@
+### Domains in V3
+
+In V2, there were two types of domains exposed via different endpoints: private domains and shared domains.
+
+In V3, there is only one domain resource. A domain is "shared" if it has an "owning organization", which is the organization in which the domain is accessible. This is represented as a relationship to this organization. A domain is "private" if it doesn't have this relationship.
+
+Read more about the [domain resource](#domains).

docs/v3/source/includes/upgrade_guide/changed_resources/_header.md

@@ -0,0 +1,29 @@
+## Changed Resources
+
+This table shows how V2 resources map to their respective V3 counterparts. Note that some V2 resources have split into multiple V3 resources, and some V2 resources have been combined into a single resource on V3. As these resources are currently under active development, these mappings may change.
+
+|**V2 Resource(s)**|**V3 Resource(s)**|**Details**|
+|---|---|---|
+|Apps|Apps, Builds, Droplets, Packages, Processes|
+|Buildpacks|Buildpacks|
+|Domains, Shared Domains, Private Domains|Domains|[Domains in V3](#domains-in-v3)|
+|Environment Variable Groups|Environment Variable Groups|
+|Events|Audit Events|[Audit Events in V3](#audit-events-in-v3)|
+|Feature Flags|Feature Flags|
+|Jobs|Jobs|
+|Organizations|Organizations|
+|Quota Definitions|Organization Quotas|[Organization Quotas in V3](#organization-quotas-in-v3)
+|Resource Matches|Resource Matches|
+|Routes, Route Mappings|Routes|[Routes in V3](#routes-in-v3)|
+|Security Groups|Security Groups|[Security Groups in V3](#security-groups-in-v3)|
+|Services|Service Offerings|[Service Offerings in V3](#service-offerings-in-v3)
+|Service Bindings, Service Keys|Service Keys|
+|Service Brokers|Service Brokers|[Service Brokers in V3](#service-brokers-in-v3)
+|Service Instances, User-Provided Service Instances|Service Instances|
+|Service Plans|Service Plans|[Service Plans in V3](#service-plans-in-v3)
+|Service Plan Visibilities|Service Plan Visibility|[Service Plan Visibility in V3](#service-plan-visibility-in-v3)
+|Spaces|Spaces|
+|Space Quota Definitions|Space Quotas|[Space Quotas in V3](#space-quotas-in-v3)
+|Stacks|Stacks|
+|Usage Events|Usage Events|
+|Users|Roles, Users|[Users and Roles in V3](#users-and-roles-in-v3)|

docs/v3/source/includes/upgrade_guide/changed_resources/_organization_quotas_in_v3.md

@@ -0,0 +1,22 @@
+### Organization Quotas in V3
+
+In V2, `-1` represented an unlimited value for a quota limit.
+
+In V3, `null` is used to represent an unlimited value.
+
+The names of the limit fields have changed from V2 to V3.
+
+|**V2**|**V3**|
+|---|---|
+non_basic_services_allowed | services.paid_services_allowed
+total_services | services.total_service_instances
+total_service_keys | services.total_service_keys
+total_routes | routes.total_routes
+total_reserved_route_ports | routes.total_reserved_ports
+total_private_domains | domains.total_domains
+memory_limit | apps.total_memory_in_mb
+instance_memory_limit | apps.per_process_memory_in_mb
+app_instance_limit | apps.total_instances
+app_task_limit | apps.per_app_tasks
+
+Read more about the [organization quota resource](#organization-quotas).

docs/v3/source/includes/upgrade_guide/changed_resources/_routes_in_v3.md

@@ -0,0 +1,7 @@
+### Routes in V3
+
+In V2, the route resource represented a URL that could be mapped to an app, and the route mapping resource represented a mapping between a route and an app.
+
+In V3, these concepts have been collapsed into a single route resource. Now, a route can have one or more "destinations" listed on it. These represent a mapping from the route to a resource that can serve traffic (e.g. a process of an app).
+
+Read more about [routes and destinations](#routes).

docs/v3/source/includes/upgrade_guide/changed_resources/_security_groups_in_v3.md

@@ -0,0 +1,15 @@
+### Security Groups in V3
+
+In V2, security groups which apply to _all_ spaces in a Cloud Foundry deployment are termed "default", as in "default for running apps" and "default for staging apps". For example, to apply a default security group to all apps in the running lifecycle, one would `PUT /v2/config/running_security_groups/:guid`
+
+In V3, security groups which apply to _all_ spaces in a Cloud Foundry deployment are termed "global", as in "globally-enabled running apps" and "globally-enabled staging apps." For example, to apply a security group globally to all apps in the running lifecycle, one would `PATCH /v3/security_groups/:guid` with a body specifying the `globally_enabled` key. See [here](#update-a-security-group) for an example.
+
+In V2, on creation, one can specify the spaces to which the security group applies, but not whether it applies globally (by default). To set the group globally to all spaces in the foundation one would `PUT /v2/config/running_security_groups/43e0441d-c9c1-4250-b8d5-7fb624379e02`.
+
+In V3, on creation, one can both specify the spaces to which it applies and also whether it applies globally (to staging and/or running) by specifying the `globally_enabled` key. See [here](#create-a-security-group) for more information.
+
+In V2, the endpoint to apply a security group to a space only includes the lifecycle ("running" or "staging") explicitly when applying to "staging" ("running" is the default lifecycle). For example, to unbind a security group from the running lifecycle, one would `DELETE /v2/security_groups/:guid/spaces/:space_guid`, from the staging lifecycle, `DELETE /v2/security_groups/:guid/staging_spaces/:space_guid`.
+
+In V3, the endpoint to apply a security group to a space includes the lifecycle. For example to unbind a security group from the running lifecycle, one would `DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid`.
+
+

docs/v3/source/includes/upgrade_guide/changed_resources/_service_brokers_in_v3.md

@@ -0,0 +1,8 @@
+### Service Brokers in V3
+
+#### Create, Update and Delete
+
+
+In V3 these endpoints are now asynchronous. See [asynchronous operations](#asynchronous-operations) and [service broker jobs](#service-broker-jobs) for more information.
+
+Read more about the [service broker resource](#service-brokers).

docs/v3/source/includes/upgrade_guide/changed_resources/_service_offerings_in_v3.md

@@ -0,0 +1,31 @@
+### Service Offerings in V3
+
+Services resource is now replaced by [service offerings resource](#service-offerings) at `/v3/service_offerings`
+
+Some services related endpoints nested in other resources have been translated to filters on `service_offerings`, with the advantage that filters accept multiple values and can be combined.
+
+`GET /v2/organizations/:guid/services` is now `GET /v3/service_offerings?organization_ids=guid`.
+
+`GET /v2/spaces/:guid/services` is now `GET /v3/service_offerings?space_ids=guid`
+
+`GET /v2/services/:guid/service_plans` is now a filter on the service plan resource: `GET /v3/service_plans?service_offering_guids=guid`. This link can also be found in the object's `links` section.
+
+
+In V2, `service_broker_name` was returned in the response. V3 returns this value only if requested using the [`fields` syntax](#fields). Refer to [service offerings resource](#service-offerings) for further information. A link to the `Service Broker` resource is included in the object's `links` section.  
+
+The structure of the service offering object as well as some attribute names have changed from V2 to V3:
+
+|**V2**|**V3**|
+|---|---|
+label | name
+active | available
+bindable | broker_catalog.features.bindable
+extra | shareable, broker_catalog.metadata
+unique_id | broker_catalog.id
+plan_updateable | broker_catalog.features.plan_updateable
+instances_retrievable | broker_catalog.features.instances_retrievable
+bindings_retrievable | broker_catalog.features.bindings_retrievable
+service_broker_guid | relationships.service_broker.data.guid
+
+
+Read more about the [service offering resource](#service-offerings).

docs/v3/source/includes/upgrade_guide/changed_resources/_service_plan_visibility_in_v3.md

@@ -0,0 +1,7 @@
+### Service Plan Visibility in V3
+
+`v2/service_plan_visibilities` has been replaced in v3 with a nested resource `v3/service_plans/:guid/visibility`
+
+This new resource has a `type`, and can have a list of `organizations` a `space` or be of type `public`
+
+Read more about the [service plan visibility resource](#service-plan-visibility).