github.com/leeclow-ops/gophercloud@v1.2.1/README.md (about)

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