github.com/gophercloud/gophercloud@v1.11.0/README.md (about)

     1  # Gophercloud: an OpenStack SDK for Go
     2  [![Coverage Status](https://coveralls.io/repos/github/gophercloud/gophercloud/badge.svg?branch=v1)](https://coveralls.io/github/gophercloud/gophercloud?branch=v1)
     3  
     4  Gophercloud is an OpenStack Go SDK.
     5  
     6  ## Useful links
     7  
     8  * [Reference documentation](http://godoc.org/github.com/gophercloud/gophercloud)
     9  * [Effective Go](https://golang.org/doc/effective_go.html)
    10  
    11  ## How to install
    12  
    13  Reference a Gophercloud package in your code:
    14  
    15  ```go
    16  import "github.com/gophercloud/gophercloud"
    17  ```
    18  
    19  Then update your `go.mod`:
    20  
    21  ```shell
    22  go mod tidy
    23  ```
    24  
    25  ## Getting started
    26  
    27  ### Credentials
    28  
    29  Because you'll be hitting an API, you will need to retrieve your OpenStack
    30  credentials and either store them in a `clouds.yaml` file, as environment
    31  variables, or in your local Go files. The first method is recommended because
    32  it decouples credential information from source code, allowing you to push the
    33  latter to your version control system without any security risk.
    34  
    35  You will need to retrieve the following:
    36  
    37  * A valid Keystone identity URL
    38  * Credentials. These can be a username/password combo, a set of Application
    39    Credentials, a pre-generated token, or any other supported authentication
    40    mechanism.
    41  
    42  For users who have the OpenStack dashboard installed, there's a shortcut. If
    43  you visit the `project/api_access` path in Horizon and click on the
    44  "Download OpenStack RC File" button at the top right hand corner, you can
    45  download either a `clouds.yaml` file or an `openrc` bash file that exports all
    46  of your access details to environment variables. To use the `clouds.yaml` file,
    47  place it at `~/.config/openstack/clouds.yaml`. To use the `openrc` file, run
    48  `source openrc` and you will be prompted for your password.
    49  
    50  ### Authentication
    51  
    52  Once you have access to your credentials, you can begin plugging them into
    53  Gophercloud. The next step is authentication, which is handled by a base
    54  "Provider" struct. There are number of ways to construct such a struct.
    55  
    56  **With `gophercloud/utils`**
    57  
    58  The [github.com/gophercloud/utils](https://github.com/gophercloud/utils)
    59  library provides the `clientconfig` package to simplify authentication. It
    60  provides additional functionality, such as the ability to read `clouds.yaml`
    61  files. To generate a "Provider" struct using the `clientconfig` package:
    62  
    63  ```go
    64  import (
    65  	"github.com/gophercloud/utils/openstack/clientconfig"
    66  )
    67  
    68  // You can also skip configuring this and instead set 'OS_CLOUD' in your
    69  // environment
    70  opts := new(clientconfig.ClientOpts)
    71  opts.Cloud = "devstack-admin"
    72  
    73  provider, err := clientconfig.AuthenticatedClient(opts)
    74  ```
    75  
    76  A provider client is a top-level client that all of your OpenStack service
    77  clients derive from. The provider contains all of the authentication details
    78  that allow your Go code to access the API - such as the base URL and token ID.
    79  
    80  Once we have a base Provider, we inject it as a dependency into each OpenStack
    81  service. For example, in order to work with the Compute API, we need a Compute
    82  service client. This can be created like so:
    83  
    84  ```go
    85  client, err := clientconfig.NewServiceClient("compute", opts)
    86  ```
    87  
    88  **Without `gophercloud/utils`**
    89  
    90  > *Note*
    91  > gophercloud doesn't provide support for `clouds.yaml` file so you need to
    92  > implement this functionality yourself if you don't wish to use
    93  > `gophercloud/utils`.
    94  
    95  You can also generate a "Provider" struct without using the `clientconfig`
    96  package from `gophercloud/utils`. To do this, you can either pass in your
    97  credentials explicitly or tell Gophercloud to use environment variables:
    98  
    99  ```go
   100  import (
   101  	"github.com/gophercloud/gophercloud"
   102  	"github.com/gophercloud/gophercloud/openstack"
   103  )
   104  
   105  // Option 1: Pass in the values yourself
   106  opts := gophercloud.AuthOptions{
   107    IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
   108    Username: "{username}",
   109    Password: "{password}",
   110  }
   111  
   112  // Option 2: Use a utility function to retrieve all your environment variables
   113  opts, err := openstack.AuthOptionsFromEnv()
   114  ```
   115  
   116  Once you have the `opts` variable, you can pass it in and get back a
   117  `ProviderClient` struct:
   118  
   119  ```go
   120  provider, err := openstack.AuthenticatedClient(opts)
   121  ```
   122  
   123  As above, you can then use this provider client to generate a service client
   124  for a particular OpenStack service:
   125  
   126  ```go
   127  client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{
   128  	Region: os.Getenv("OS_REGION_NAME"),
   129  })
   130  ```
   131  
   132  ### Provision a server
   133  
   134  We can use the Compute service client generated above for any Compute API
   135  operation we want. In our case, we want to provision a new server. To do this,
   136  we invoke the `Create` method and pass in the flavor ID (hardware
   137  specification) and image ID (operating system) we're interested in:
   138  
   139  ```go
   140  import "github.com/gophercloud/gophercloud/openstack/compute/v2/servers"
   141  
   142  server, err := servers.Create(client, servers.CreateOpts{
   143  	Name:      "My new server!",
   144  	FlavorRef: "flavor_id",
   145  	ImageRef:  "image_id",
   146  }).Extract()
   147  ```
   148  
   149  The above code sample creates a new server with the parameters, and embodies the
   150  new resource in the `server` variable (a
   151  [`servers.Server`](http://godoc.org/github.com/gophercloud/gophercloud) struct).
   152  
   153  ## Advanced Usage
   154  
   155  Have a look at the [FAQ](./docs/FAQ.md) for some tips on customizing the way Gophercloud works.
   156  
   157  ## Backwards-Compatibility Guarantees
   158  
   159  Gophercloud versioning follows [semver](https://semver.org/spec/v2.0.0.html).
   160  
   161  Before `v1.0.0`, there were no guarantees. Starting with v1, there will be no breaking changes within a major release.
   162  
   163  See the [Release instructions](./RELEASE.md).
   164  
   165  ## Contributing
   166  
   167  See the [contributing guide](./.github/CONTRIBUTING.md).
   168  
   169  ## Help and feedback
   170  
   171  If you're struggling with something or have spotted a potential bug, feel free
   172  to submit an issue to our [bug tracker](https://github.com/gophercloud/gophercloud/issues).