Docs reflect primacy of CPI v2

content/agent-cpi-interactions.md

@@ -275,13 +275,12 @@ using one of the following ways:
   settings from the registry.
 
 !!! tip
-    See [CPI API V2](cpi-api-v2.md) and [CPI V2 Migration Guide](v2-migration-guide.md) for more information on how the CPI, Agent, and Director behave in a registry-less environment.
+    See [CPI API V2](cpi-api-v2.md) and [CPI V2 Migration Guide](cpi-api-v2-migration-guide.md) for more information on how the CPI, Agent, and Director behave in a registry-less environment.
 
 ---
 ### CPI API V1 {: #cpi-api-v1}
 
-This section describes the agent interactions prior to
-CPI API V2
+This section describes the agent interactions prior to CPI API V2
 
 ----
 ##### Metadata Server {: #metadata }

content/bosh-components.md

@@ -76,7 +76,7 @@ The Director and the Agents communicate through a lightweight publish-subscribe
 ### Registry {: #registry }
 
 !!! note
-    As of CPI V2, the registry may be avoided if the stemcell API version is sufficient. See [CPI API V2](cpi-api-v2.md) and [CPI V2 Migration Guide](v2-migration-guide.md) for more information on how the CPI, Agent, and Director behave in a registry-less environment.
+    As of CPI V2, the registry may be avoided if the stemcell API version is sufficient. See [CPI API V2](cpi-api-v2.md) and [CPI V2 Migration Guide](cpi-api-v2-migration-guide.md) for more information on how the CPI, Agent, and Director behave in a registry-less environment.
 
 When the Director creates or updates a VM, it stores configuration information for the VM in the Registry so that it can be used during bootstrapping stage of the VM.
 

content/build-cpi.md

@@ -9,7 +9,7 @@ Both `bosh create-env` command and the Director expect to be configured with a C
 
 ## Implementation
 
-When building a CPI release, the primary requirement is that it provides a `bin/cpi` executable which implements a simple RPC API through `STDIN`/`STDOUT`. The [RPC API](cpi-api-v1-rpc.md) page provides an in-depth look at the protocol and required methods.
+When building a CPI release, the primary requirement is that it provides a `bin/cpi` executable which implements a simple RPC API through `STDIN`/`STDOUT`. The [RPC API](cpi-api-rpc.md) page provides an in-depth look at the protocol and required methods.
 
 If you are getting started with a new CPI, you may be interested in using one of the following languages. These releases take advantage of some existing libraries that you may find useful in your own implementation.
 
@@ -64,4 +64,4 @@ When working with the Director you can find similar debug logs via `bosh task X
 
 ## Migrating from V1 to V2 of the CPI API contract {: #migrating }
 
-The CPI library can be safely upgraded to V2, as all the method calls in V1 are maintained. To take advantage of the new features, please refer to the [V1 to V2 migration guide](v2-migration-guide.md)
+The CPI library can be safely upgraded to V2, as all the method calls in V1 are maintained. To take advantage of the new features, please refer to the [V1 to V2 migration guide](cpi-api-v2-migration-guide.md)

content/build-stemcell.md

@@ -47,7 +47,7 @@ Should result in:
 * **version** [String, required]: Version of the stemcell. Example: `621.74`.
 * **sha1** [String, required]: The SHA1 of the image file included in the stemcell tarball.
 * **bosh_protocol** [String, optional]: Deprecated.
-* **cloud_properties** [Hash, required]: Describes any IaaS-specific properties needed to import OS image. These properties will be passed in to the [`create_stemcell` CPI call](cpi-api-v1.md#create-stemcell).
+* **cloud_properties** [Hash, required]: Describes any IaaS-specific properties needed to import OS image. These properties will be passed in to the [`create_stemcell` CPI call](cpi-api-v2.md#create-stemcell).
 * **api_version** [Integer, optional]: Highest supported API version of the Agent in the stemcell. Defaults to `1`.
 * **stemcell_formats** [Array of Strings, optional]: The list of stemcell formats that a [CPI must support](cpi-api-v2-method/info.md#result). The director will attempt to upload the stemcell to all CPIs that support any specified formats.
 
@@ -94,7 +94,7 @@ A "light" stemcell represents a reference to an IaaS resource where the stemcell
 
 In these cases, a light stemcell tarball contains only metadata about the stemcell, but does not contain the actual `image` file with the OS disk image. In addition to the regular stemcell metadata, the `stemcell.MF` file should include a `cloud_properties` section with details about how the CPI may find the already-imported stemcell within the IaaS.
 
-On AWS, for example, stemcells are imported into a specific region as an [EC2 Amazon Machine Image](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) which is referenced by an `ami-*` identifier. If you look at the `stemcell.MF` file of the *light* stemcell tarball, you'll see a list of regions and their corresponding AMI. When a stemcell is uploaded, the [`create_stemcell` call](cpi-api-v1.md#create-stemcell) will return matching AMI ID without doing any IaaS API calls.
+On AWS, for example, stemcells are imported into a specific region as an [EC2 Amazon Machine Image](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) which is referenced by an `ami-*` identifier. If you look at the `stemcell.MF` file of the *light* stemcell tarball, you'll see a list of regions and their corresponding AMI. When a stemcell is uploaded, the [`create_stemcell` call](cpi-api-v2.md#create-stemcell) will return matching AMI ID without doing any IaaS API calls.
 
 ```shell
 tar -Oxzf light-bosh-stemcell-621.74-aws-xen-hvm-ubuntu-xenial-go_agent.tgz stemcell.MF

content/cli-v2.md

@@ -1546,7 +1546,7 @@ See [CPI config](cpi-config.md).
 
 - `bosh [GLOBAL-CLI-OPTIONS] delete-network NAME`
 
-    Deletes a network created during deployment. Check [CPI methods](https://bosh.io/docs/cpi-api-v1-method/create-network/#create_network) for more details
+    Deletes a network created during deployment. Check [CPI methods](https://bosh.io/docs/cpi-api-v2-method/create-network/#create_network) for more details
 
     ```shell
     bosh -e vbox delete-network network-name

content/cpi-api-v1-rpc.md → content/cpi-api-rpc.md

@@ -28,7 +28,7 @@ For reference, there are two primary implementations of the "caller" which invok
 * `arguments` [Array]: Array of arguments that are specific to the CPI method.
 * `context` [Hash]: Additional information provided as a context of this execution.
 
-An example request for [`delete_disk`](cpi-api-v1-method/delete-disk.md) might look like:
+An example request for [`delete_disk`](cpi-api-v2-method/delete-disk.md) might look like:
 
 ```json
 {
@@ -57,7 +57,7 @@ the following context is sent for each CPI call:
 ```
 The CPI request ID is useful to trace a single invocation through the debug logs.
 The stemcell API version is sent if it is defined in the stemcell's manifest, for the stemcell this operation is relevant for (e.g. `create_vm`). Sometimes there is no stemcell involved in the operation, so this is undefined (e.g. `info`).
-The API version is used to determine eligibility for [registry-based property storage](v2-migration-guide.md#stemcell-changes-in-v2-of-the-api-contract).
+The API version is used to determine eligibility for [registry-based property storage](cpi-api-v2-migration-guide.md#stemcell-changes-in-v2-of-the-api-contract).
 
 
 ### Response {: #response }
@@ -69,7 +69,7 @@ The API version is used to determine eligibility for [registry-based property st
     * `ok_to_retry` [Boolean]: Indicates whether callee should try calling the method again without changing any of the arguments.
 * `log` [String]: Additional information that may be useful for auditing, debugging and understanding what actions CPI took while executing a method. Typically includes info and debug logs, error backtraces.
 
-An example response to [`create_vm`](cpi-api-v1-method/create-vm.md) might look like:
+An example response to [`create_vm`](cpi-api-v2-method/create-vm.md) might look like:
 
 ```json
 {
@@ -79,7 +79,7 @@ An example response to [`create_vm`](cpi-api-v1-method/create-vm.md) might look
 }
 ```
 
-An example error response to [`create_vm`](cpi-api-v1-method/create-vm.md) might look like:
+An example error response to [`create_vm`](cpi-api-v2-method/create-vm.md) might look like:
 
 ```json
 {
@@ -96,29 +96,29 @@ An example error response to [`create_vm`](cpi-api-v1-method/create-vm.md) might
 
 ## Methods
 
- * [info](cpi-api-v1-method/info.md)
+ * [info](cpi-api-v2-method/info.md)
  * Stemcells
-    * [create_stemcell](cpi-api-v1-method/create-stemcell.md)
-    * [delete_stemcell](cpi-api-v1-method/delete-stemcell.md)
+    * [create_stemcell](cpi-api-v2-method/create-stemcell.md)
+    * [delete_stemcell](cpi-api-v2-method/delete-stemcell.md)
  * VM Management
-    * [create_vm](cpi-api-v1-method/create-vm.md)
-    * [delete_vm](cpi-api-v1-method/delete-vm.md)
-    * [has_vm](cpi-api-v1-method/has-vm.md)
-    * [reboot_vm](cpi-api-v1-method/reboot-vm.md)
-    * [set_vm_metadata](cpi-api-v1-method/set-vm-metadata.md)
-    * [calculate_vm_cloud_properties](cpi-api-v1-method/calculate-vm-cloud-properties.md)
+    * [create_vm](cpi-api-v2-method/create-vm.md)
+    * [delete_vm](cpi-api-v2-method/delete-vm.md)
+    * [has_vm](cpi-api-v2-method/has-vm.md)
+    * [reboot_vm](cpi-api-v2-method/reboot-vm.md)
+    * [set_vm_metadata](cpi-api-v2-method/set-vm-metadata.md)
+    * [calculate_vm_cloud_properties](cpi-api-v2-method/calculate-vm-cloud-properties.md)
  * Disk Management
-    * [create_disk](cpi-api-v1-method/create-disk.md)
-    * [delete_disk](cpi-api-v1-method/delete-disk.md)
-    * [resize_disk](cpi-api-v1-method/resize-disk.md)
-    * [has_disk](cpi-api-v1-method/has-disk.md)
-    * [attach_disk](cpi-api-v1-method/attach-disk.md)
-    * [detach_disk](cpi-api-v1-method/detach-disk.md)
-    * [set_disk_metadata](cpi-api-v1-method/set-disk-metadata.md)
-    * [get_disks](cpi-api-v1-method/get-disks.md)
+    * [create_disk](cpi-api-v2-method/create-disk.md)
+    * [delete_disk](cpi-api-v2-method/delete-disk.md)
+    * [resize_disk](cpi-api-v2-method/resize-disk.md)
+    * [has_disk](cpi-api-v2-method/has-disk.md)
+    * [attach_disk](cpi-api-v2-method/attach-disk.md)
+    * [detach_disk](cpi-api-v2-method/detach-disk.md)
+    * [set_disk_metadata](cpi-api-v2-method/set-disk-metadata.md)
+    * [get_disks](cpi-api-v2-method/get-disks.md)
     * Snapshot Management
-        * [snapshot_disk](cpi-api-v1-method/snapshot-disk.md)
-        * [delete_snapshot](cpi-api-v1-method/delete-snapshot.md)
- * Deprecated
+        * [snapshot_disk](cpi-api-v2-method/snapshot-disk.md)
+        * [delete_snapshot](cpi-api-v2-method/delete-snapshot.md)
+ * Deprecated v1 methods
     * [configure_networks](cpi-api-v1-method/configure-networks.md)
     * [current_vm_id](cpi-api-v1-method/current-vm-id.md)

content/cpi-api-v1-method/attach-disk.md

@@ -60,5 +60,5 @@ For the Agent to eventually format, partition and mount attached disk, it needs
 
 ## Related
 
- * [create_disk](create-disk.md)
+ * [create_disk](../cpi-api-v2-method/create-disk.md)
  * [detach_disk](detach-disk.md)

content/cpi-api-v1-method/detach-disk.md

@@ -29,4 +29,4 @@ No return value
 ## Related
 
  * [attach_disk](attach-disk.md)
- * [delete_disk](delete-disk.md)
+ * [delete_disk](../cpi-api-v2-method/delete-disk.md)

content/cpi-api-v1.md

@@ -1,21 +1,9 @@
 # Cloud Provider Interface (Version 1)
 
-For a big picture overview of the sequence of CPI calls, the following resources are helpful:
+!!! note
+    Version 1 of the Cloud Provider Interface is deprecated, use [Version 2](cpi-api-v2.md).
 
-- [BOSH components](bosh-components.md) and its example component interaction diagram
-- [CLI v2 architecture doc](https://github.com/cloudfoundry/bosh-cli/blob/master/docs/architecture.md#deploy-command-flow) and [`bosh create-env` flow](https://github.com/cloudfoundry/bosh-init/blob/master/docs/init-cli-flow.png) where calls to the CPI are marked as `cloud`.
+See [Migration guide](cpi-api-v2-migration-guide.md).
 
-If you're looking to get started on building a CPI, this [short guide](build-cpi.md) may be helpful. To learn more about the technical implementation, continue reading or refer to the [RPC Interface](cpi-api-v1-rpc.md) for more details.
-
-
-## Glossary {: #glossary }
-
-- **cloud ID** is an ID (string) that the Director uses to reference any created infrastructure resource; typically CPI methods return cloud IDs and later receive them. For example AWS CPI's `create_vm` method would return `i-f789df` and `attach_disk` would take it.
-
-- **cloud_properties** is a hash that can be specified for several objects (resource pool, disk pool, stemcell, network) to provide infrastructure specific settings to the CPI for that object. Only CPIs know the meaning of its contents. For example resource pool's `cloud_properties` for AWS can specify `instance_type`:
-
-```yaml
-resource_pools:
-- name: large_machines
-  cloud_properties: {instance_type: r3.8xlarge}
-```
+Methods in the Version 1 section of this reference include only those methods which 
+differ from, or are not included in, Version 2.  

content/cpi-api-v2-method/attach-disk.md

@@ -77,7 +77,7 @@ For the Agent to eventually format, partition and mount the newly attached disk,
 }
 ```
 
-See [CPI API V2](../cpi-api-v2.md) and [CPI V2 Migration Guide](../v2-migration-guide.md) for more details about `api_version` for stemcell and CPI within the `context` portion of the request.
+See [CPI API V2](../cpi-api-v2.md) and [CPI V2 Migration Guide](../cpi-api-v2-migration-guide.md) for more details about `api_version` for stemcell and CPI within the `context` portion of the request.
 
 
 ### Implementations
@@ -87,5 +87,5 @@ See [CPI API V2](../cpi-api-v2.md) and [CPI V2 Migration Guide](../v2-migration-
 
 ## Related
 
- * [create_disk V1](../cpi-api-v1-method/create-disk.md)
- * [detach_disk V1](../cpi-api-v1-method/detach-disk.md)
+ * [create_disk V1](create-disk.md)
+ * [detach_disk V1](detach-disk.md)

content/cpi-api-v2-method/create-vm.md

@@ -33,7 +33,7 @@ As of V2 of the CPI API contract, `create_vm` returns an array of the resultant
 
 For the Agent to successfully start on the created VM, several bootstrapping settings must be exposed which include network configuration, message bus location (NATS/HTTPS), agent id, etc. Each infrastructure might have a different way of providing such settings to the Agent. For example AWS CPI uses instance user metadata and potentially the BOSH Registry. vSphere CPI uses CDROM drive.
 
-As of CPI V2, the registry may be avoided if the stemcell API version is sufficient. See [CPI API V2](../cpi-api-v2.md) and [CPI V2 Migration Guide](../v2-migration-guide.md) for more information on how the CPI, Agent, and Director behave in a registry-less environment.
+As of CPI V2, the registry may be avoided if the stemcell API version is sufficient. See [CPI API V2](../cpi-api-v2.md) and [CPI V2 Migration Guide](../cpi-api-v2-migration-guide.md) for more information on how the CPI, Agent, and Director behave in a registry-less environment.
 
 Most CPIs choose to communicate with the default Agent. Hence, the communication settings follow a certain format:
 

content/cpi-api-v2-method/delete-vm.md

@@ -41,7 +41,7 @@ No return value
 
 #### Changes for V2 of the API contract
 
-The signature for `delete_vm` is the same as in V1 pf the API contract. For CPIs that previously used the registry to track mount points, V2 does not necessarily use the registry. The registry is used if the stemcell API version is not sufficient. The Agent receives an `unmount_disk` from the Director and deletes the persistent disk settings when not using the registry. See [CPI V2 Migration Guide](../v2-migration-guide.md) for more information.
+The signature for `delete_vm` is the same as in V1 pf the API contract. For CPIs that previously used the registry to track mount points, V2 does not necessarily use the registry. The registry is used if the stemcell API version is not sufficient. The Agent receives an `unmount_disk` from the Director and deletes the persistent disk settings when not using the registry. See [CPI V2 Migration Guide](../cpi-api-v2-migration-guide.md) for more information.
 
 
 ## Related

content/cpi-api-v2-method/detach-disk.md

@@ -60,9 +60,9 @@ No return value
 
  #### Changes for V2 of the API contract
 
-The signature for `detach_disk` is the same as in V1 of the API contract. For CPIs that previously used the registry to track mount points, V2 does not necessarily use the registry. The registry should be used if the stemcell API version is not sufficient. Without the registry, the Agent receives a message from the Director to remove the persistent disk from its settings. See [CPI V2 Migration Guide](../v2-migration-guide.md) for more information.
+The signature for `detach_disk` is the same as in V1 of the API contract. For CPIs that previously used the registry to track mount points, V2 does not necessarily use the registry. The registry should be used if the stemcell API version is not sufficient. Without the registry, the Agent receives a message from the Director to remove the persistent disk from its settings. See [CPI V2 Migration Guide](../cpi-api-v2-migration-guide.md) for more information.
 
 ## Related
 
  * [attach_disk](attach-disk.md)
- * [delete_disk V1](../cpi-api-v1-method/delete-disk.md)
+ * [delete_disk V1](delete-disk.md)

content/cpi-api-v2.md

@@ -11,14 +11,17 @@ Examples of API request and response:
 - [Building a CPI: RPC - Response](https://bosh.io/docs/build-cpi.html#response)
 
 
+If you're looking to get started on building a CPI, this [short guide](build-cpi.md) may be helpful. To learn more about the technical implementation, continue reading or refer to the [RPC Interface](cpi-api-rpc.md) for more details.
+
+
 Libraries:
 
 - Ruby: `bosh-cpi-ruby` gem [v2.5.0](https://github.com/cloudfoundry/bosh-cpi-ruby/releases/tag/v2.5.0)
 - GoLang: `bosh-cpi-go` [library](https://github.com/cppforlife/bosh-cpi-go)
 
 #### Migration from V1 of the CPI API contract
 
-Detailed instructions on how to migrate an existing CPI from V1 to V2 of the contract can be found [here](v2-migration-guide.md).
+Detailed instructions on how to migrate an existing CPI from V1 to V2 of the contract can be found [here](cpi-api-v2-migration-guide.md).
 
 ---
 
@@ -38,8 +41,9 @@ resource_pools:
 
 ## Methods
 
-- V1 of the CPI API contract must still be implemented. See [CPI API V1](cpi-api-v1.md).
-- To differentiate calls using V2 of the contract, the caller needs to pass in `"api_version": 2` in the header of the request.
+- To differentiate calls using V2 of the contract, the caller passes `"api_version": 2` in the header of the request.
+- V1 of the CPI API contract is deprecated, and need not be implemented.
+    - Reference [CPI API V1](cpi-api-v1.md).
 
 ### Reference Table (Based on each component version)
 
@@ -94,21 +98,22 @@ The remainder of the required settings are then fetched from the registry. The C
 ```
 **Note** that the `persistent` disks will not be available when the CPI writes these settings. When the Director instructs the CPI to attach a disk, the `attach_disk` method is expected to return information on the attach point. The Director then informs the Agent about the disk, and the Agent updates its disk settings accordingly.
 
-
-### Implementation
+### API contract changes since V1
 
 CPI contract version 2 differs from version 1 by the following:
+
 - CPI [info call](cpi-api-v2-method/info.md) will return `api_version`.
 - CPI accepts `api_version` to determine which version of the API contract to use.
-  - Director will send CPI `api_version` based on the CPI's info response for all CPI calls.
+    - Director will send CPI `api_version` based on the CPI's info response for all CPI calls.
 - Director will send stemcell `api_version` for all CPI calls.
 
-### Changes in the V2 API contract
+#### API method changes
 
- * [info](cpi-api-v2-method/info.md)
- * VM Management
+* General
+    * [info](cpi-api-v2-method/info.md)
+* VM Management
     * [create_vm](cpi-api-v2-method/create-vm.md)
     * [delete_vm](cpi-api-v2-method/delete-vm.md)
- * Disk Management
+* Disk Management
     * [attach_disk](cpi-api-v2-method/attach-disk.md)
     * [detach_disk](cpi-api-v2-method/detach-disk.md)