V1.11.0 ovh

README.md

@@ -13,7 +13,7 @@ Gophercloud is an OpenStack Go SDK.
 
 Reference a Gophercloud package in your code:
 
-```Go
+```go
 import "github.com/gophercloud/gophercloud"
 ```
 
@@ -28,43 +28,79 @@ go mod tidy
 ### Credentials
 
 Because you'll be hitting an API, you will need to retrieve your OpenStack
-credentials and either store them as environment variables or in your local Go
-files. The first method is recommended because it decouples credential
-information from source code, allowing you to push the latter to your version
-control system without any security risk.
+credentials and either store them in a `clouds.yaml` file, as environment
+variables, or in your local Go files. The first method is recommended because
+it decouples credential information from source code, allowing you to push the
+latter to your version control system without any security risk.
 
 You will need to retrieve the following:
 
-* username
-* password
-* a valid Keystone identity URL
+* A valid Keystone identity URL
+* Credentials. These can be a username/password combo, a set of Application
+  Credentials, a pre-generated token, or any other supported authentication
+  mechanism.
 
 For users that have the OpenStack dashboard installed, there's a shortcut. If
-you visit the `project/access_and_security` path in Horizon and click on the
-"Download OpenStack RC File" button at the top right hand corner, you will
-download a bash file that exports all of your access details to environment
-variables. To execute the file, run `source admin-openrc.sh` and you will be
-prompted for your password.
+you visit the `project/api_access` path in Horizon and click on the
+"Download OpenStack RC File" button at the top right hand corner, you can
+download either a `clouds.yaml` file or an `openrc` bash file that exports all
+of your access details to environment variables. To use the `clouds.yaml` file,
+place it at `~/.config/openstack/clouds.yaml`. To use the `openrc` file, run
+`source openrc` and you will be prompted for your password.
 
 ### Authentication
 
-> NOTE: It is now recommended to use the `clientconfig` package found at
-> https://github.com/gophercloud/utils/tree/master/openstack/clientconfig
-> for all authentication purposes.
->
-> The below documentation is still relevant. clientconfig simply implements
-> the below and presents it in an easier and more flexible way.
-
 Once you have access to your credentials, you can begin plugging them into
-Gophercloud. The next step is authentication, and this is handled by a base
-"Provider" struct. To get one, you can either pass in your credentials
-explicitly, or tell Gophercloud to use environment variables:
+Gophercloud. The next step is authentication, which is handled by a base
+"Provider" struct. There are number of ways to construct such a struct.
+
+**With `gophercloud/utils`**
+
+The [github.com/gophercloud/utils](https://github.com/gophercloud/utils)
+library provides the `clientconfig` package to simplify authentication. It
+provides additional functionality, such as the ability to read `clouds.yaml`
+files. To generate a "Provider" struct using the `clientconfig` package:
+
+```go
+import (
+	"github.com/gophercloud/utils/openstack/clientconfig"
+)
+
+// You can also skip configuring this and instead set 'OS_CLOUD' in your
+// environment
+opts := new(clientconfig.ClientOpts)
+opts.Cloud = "devstack-admin"
+
+provider, err := clientconfig.AuthenticatedClient(opts)
+```
+
+A provider client is a top-level client that all of your OpenStack service
+clients derive from. The provider contains all of the authentication details
+that allow your Go code to access the API - such as the base URL and token ID.
+
+Once we have a base Provider, we inject it as a dependency into each OpenStack
+service. For example, in order to work with the Compute API, we need a Compute
+service client. This can be created like so:
+
+```go
+client, err := clientconfig.NewServiceClient("compute", opts)
+```
+
+**Without `gophercloud/utils`**
+
+> *Note*
+> gophercloud doesn't provide support for `clouds.yaml` file so you need to
+> implement this functionality yourself if you don't wish to use
+> `gophercloud/utils`.
+
+You can also generate a "Provider" struct without using the `clientconfig`
+package from `gophercloud/utils`. To do this, you can either pass in your
+credentials explicitly or tell Gophercloud to use environment variables:
 
 ```go
 import (
-  "github.com/gophercloud/gophercloud"
-  "github.com/gophercloud/gophercloud/openstack"
-  "github.com/gophercloud/gophercloud/openstack/utils"
+	"github.com/gophercloud/gophercloud"
+	"github.com/gophercloud/gophercloud/openstack"
 )
 
 // Option 1: Pass in the values yourself
@@ -85,34 +121,29 @@ Once you have the `opts` variable, you can pass it in and get back a
 provider, err := openstack.AuthenticatedClient(opts)
 ```
 
-The `ProviderClient` is the top-level client that all of your OpenStack services
-derive from. The provider contains all of the authentication details that allow
-your Go code to access the API - such as the base URL and token ID.
-
-### Provision a server
-
-Once we have a base Provider, we inject it as a dependency into each OpenStack
-service. In order to work with the Compute API, we need a Compute service
-client; which can be created like so:
+As above, you can then use this provider client to generate a service client
+for a particular OpenStack service:
 
 ```go
 client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{
-  Region: os.Getenv("OS_REGION_NAME"),
+	Region: os.Getenv("OS_REGION_NAME"),
 })
 ```
 
-We then use this `client` for any Compute API operation we want. In our case,
-we want to provision a new server - so we invoke the `Create` method and pass
-in the flavor ID (hardware specification) and image ID (operating system) we're
-interested in:
+### Provision a server
+
+We can use the Compute service client generated above for any Compute API
+operation we want. In our case, we want to provision a new server. To do this,
+we invoke the `Create` method and pass in the flavor ID (hardware
+specification) and image ID (operating system) we're interested in:
 
 ```go
 import "github.com/gophercloud/gophercloud/openstack/compute/v2/servers"
 
 server, err := servers.Create(client, servers.CreateOpts{
-  Name:      "My new server!",
-  FlavorRef: "flavor_id",
-  ImageRef:  "image_id",
+	Name:      "My new server!",
+	FlavorRef: "flavor_id",
+	ImageRef:  "image_id",
 }).Extract()
 ```