github.com/opentelekomcloud/gophertelekomcloud@v0.9.3/README.md (about)

     1  # GopherTelekomCloud: a OpenTelekomCloud SDK for Golang
     2  
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/opentelekomcloud/gophertelekomcloud?branch=devel)](https://goreportcard.com/report/github.com/opentelekomcloud/gophertelekomcloud)
     4  [![Zuul Gated](https://zuul-ci.org/gated.svg)](https://zuul.eco.tsi-dev.otc-service.com/t/eco/buildsets?project=opentelekomcloud%2Fgophertelekomcloud&pipeline=gate)
     5  [![LICENSE](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://github.com/opentelekomcloud/gophertelekomcloud/blob/master/LICENSE)
     6  
     7  GopherTelekomCloud is a OpenTelekomCloud clouds Go SDK. GopherTelekomCloud is based
     8  on [Gophercloud](https://github.com/gophercloud/gophercloud)
     9  which is an OpenStack Go SDK and has a great design. GopherTelekomCloud has added and removed some features to support
    10  OpenTelekomCloud.
    11  
    12  ## Useful links
    13  
    14  * [Reference documentation](http://godoc.org/github.com/opentelekomcloud/gophertelekomcloud)
    15  * [Effective Go](https://golang.org/doc/effective_go.html)
    16  
    17  ## How to install
    18  
    19  Installation with modern Go and `go mod` is really simple:
    20  
    21  Just run `go mod download` to install all dependencies.
    22  
    23  ## Getting started
    24  
    25  ### Credentials
    26  
    27  Because you'll be hitting an API, you will need to retrieve your OpenTelekomCloud credentials and store them using
    28  standard Openstack approaches:
    29  either [`clouds.yaml`](https://docs.openstack.org/python-openstackclient/latest/configuration/index.html)
    30  file (recommended) or environment variables.
    31  
    32  You will need to retrieve the following:
    33  
    34  * domain name
    35  * username
    36  * password
    37  * project name/id (for most of the services)
    38  * a valid IAM identity URL
    39  
    40  ### Authentication
    41  
    42  Once you have access to your credentials, you can begin plugging them into Golangsdk. The next step is authentication,
    43  and this is handled by a base
    44  "Provider" struct. To get one, you can either pass in your credentials explicitly, or tell Golangsdk to use environment
    45  variables:
    46  
    47  #### Option 1: Pass in the values yourself
    48  
    49  ```go
    50  opts := golangsdk.AuthOptions{
    51  IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
    52  Username:         "{username}",
    53  Password:         "{password}",
    54  }
    55  client, err := openstack.AuthenticatedClient(opts)
    56  ```
    57  
    58  #### Option 2: Use a utility function to retrieve cloud configuration from env variables and configuration files
    59  
    60  ```go
    61  env := openstack.NewEnv("OS_") // use OS_ prefixed env variables
    62  client, err := env.AuthenticatedClient()
    63  ```
    64  
    65  The `ProviderClient` is the top-level client that all of your OpenTelekomCloud services derive from. The provider
    66  contains all of the authentication details that allow your Go code to access the API - such as the base URL and token
    67  ID.
    68  
    69  ### Provision a rds instance
    70  
    71  Once we have a base Provider, we inject it as a dependency into each OpenTelekomCloud service. In order to work with the
    72  rds API, we need a rds service client; which can be created like so:
    73  
    74  ```go
    75  client, err := openstack.NewRdsServiceV1(provider, golangsdk.EndpointOpts{
    76  	Region: utils.GetRegion(ao),
    77  })
    78  ```
    79  
    80  We then use this `client` for any rds API operation we want. In our case, we want to provision a rds instance - so we
    81  invoke the `Create` method and pass in the name and the flavor ID (database specification) we're interested in:
    82  
    83  ```go
    84  import "github.com/opentelekomcloud/gophertelekomcloud/openstack/rds/v1/instances"
    85  
    86  instance, err := instances.Create(client, instances.CreateOpts{
    87  	Name:      "My new rds instance!",
    88  	FlavorRef: "flavor_id",
    89  }).Extract()
    90  ```
    91  
    92  The above code sample creates a new rds instance with the parameters, and embodies the new resource in the `instance`
    93  variable (a[`instances.Instance`](http://godoc.org/github.com/opentelekomcloud/gophertelekomcloud) struct).
    94  
    95  ## Advanced Usage
    96  
    97  Have a look at the [FAQ](./FAQ.md) for some tips on customizing the way Golangsdk works.
    98  
    99  ## Backwards-Compatibility Guarantees
   100  
   101  None. Vendor it and write tests covering the parts you use.
   102  
   103  ## Contributing
   104  
   105  See the [contributing guide](./.github/CONTRIBUTING.md).
   106  
   107  ## Help and feedback
   108  
   109  If you're struggling with something or have spotted a potential bug, feel free to submit an issue to
   110  our [bug tracker](https://github.com/opentelekomcloud/gophertelekomcloud/issues).