55[ ![ Report card] ( https://goreportcard.com/badge/github.com/cloudfoundry/go-cfclient/v3 )] ( https://goreportcard.com/report/github.com/cloudfoundry/go-cfclient/v3 )
66
77## Overview
8+
89` go-cfclient ` is a go module library to assist you in writing apps that need to interact the [ Cloud Foundry] ( http://cloudfoundry.org )
9- Cloud Controller [ v3 API] ( https://v3-apidocs.cloudfoundry.org ) . The v2 API is no longer supported, however if you _ really _
10+ Cloud Controller [ v3 API] ( https://v3-apidocs.cloudfoundry.org ) . The v2 API is no longer supported, however if you ** really **
1011need to use the older API you may use the go-cfclient v2 branch and releases.
1112
12- __ NOTE __ - The v3 version in the main branch is currently under development and may have ** breaking changes** until a v3.0.0 release is
13- cut. Until then, you may want to pin to a specific v3.0.0-alpha.x release.
13+ ** NOTE ** - The v3 version in the main branch is currently under development and may have ** breaking changes** until a v3.0.0 release is
14+ cut. Until then, you may want to pin to a specific v3.0.0-alpha.x release.
1415
1516## Installation
17+
1618go-cfclient is compatible with modern Go releases in module mode, with Go installed:
17- ```
19+
20+ ``` shell
1821go get github.com/cloudfoundry/go-cfclient/v3
1922```
23+
2024Will resolve and add the package to the current development module, along with its dependencies. Eventually this
2125library will cut releases that will be tagged with v3.0.0, v3.0.1 etc, see the Versioning section below.
2226
2327## Usage
28+
2429- [ Authentication] ( ./README.md#authentication )
2530- [ Resources] ( ./README.md#resources )
2631- [ Filtering] ( ./README.md#filtering )
@@ -30,6 +35,7 @@ library will cut releases that will be tagged with v3.0.0, v3.0.1 etc, see the V
3035- [ Migrating v2 to v3] ( ./README.md#migrating-v2-to-v3 )
3136
3237Using go modules import the client, config and resource packages:
38+
3339``` go
3440import (
3541 " github.com/cloudfoundry/go-cfclient/v3/client"
@@ -39,61 +45,78 @@ import (
3945```
4046
4147### Authentication
48+
4249Construct a new CF client configuration object. The configuration object configures how the client will authenticate to the
4350CF API. There are various supported auth mechanisms.
4451
4552The simplest being - use the existing CF CLI configuration and auth token:
53+
4654``` go
4755cfg , _ := config.NewFromCFHome ()
4856cf , _ := client.New (cfg)
4957```
58+
5059Username and password:
60+
5161``` go
5262cfg , _ := config.New (" https://api.example.org" , config.UserPassword (" user" , " pass" ))
5363cf , _ := client.New (cfg)
5464```
65+
5566Client and client secret:
67+
5668``` go
5769cfg , _ := config.New (" https://api.example.org" , config.ClientCredentials (" cf" , " secret" ))
5870cf , _ := client.New (cfg)
5971```
72+
6073Client and client assertion:
74+
6175``` go
6276cfg , _ := config.New (" https://api.example.org" , config.ClientCredentials (" cf" ," " ),config.ClientAssertion (" client-assertion-token" ))
6377cf , _ := client.New (cfg)
6478```
79+
6580Static OAuth token, which requires both an access and refresh token:
81+
6682``` go
6783cfg , _ := config.New (" https://api.example.org" , config.Token (accessToken, refreshToken))
6884cf , _ := client.New (cfg)
6985```
86+
7087Using JWT Bearer Assertion Grant
88+
7189``` go
7290cfg , _ := config.New (" https://api.example.org" ,config.JWTBearerAssertion (" jwt-assertion-token" ))
7391cf , _ := client.New (cfg)
7492```
93+
7594For more detailed examples of using the various authentication and configuration options, see the
7695[ auth example] ( ./examples/auth/main.go ) .
7796
7897### Resources
98+
7999The services of a client divide the API into logical chunks and correspond to the structure of the CF API documentation
80- at https://v3-apidocs.cloudfoundry.org . In other words each major resource type has its own service client that
100+ at [ https://v3-apidocs.cloudfoundry.org ] ( https://v3-apidocs.cloudfoundry.org ) . In other words each major resource type has its own service client that
81101is accessible via the main client instance.
102+
82103``` go
83104apps , _ := cf.Applications .ListAll (context.Background (), nil )
84105for _ , app := range apps {
85106 fmt.Printf (" Application %s is %s \n " , app.Name , app.State )
86107}
87108```
109+
88110All clients and their functions that interact with the CF API live in the ` client ` package. The client package
89111is responsible for making HTTP requests using the resources defined in the ` resource ` package. All generic serializable
90112resource definitions live in the ` resource ` package and could be reused with other client's outside this library.
91113
92- __ NOTE __ - Using the context package you can easily pass cancellation signals and deadlines to various client calls
114+ ** NOTE ** - Using the context package you can easily pass cancellation signals and deadlines to various client calls
93115for handling a request. In case there is no context available, then ` context.Background() ` can be used as a starting
94116point.
95117
96118### Filtering
119+
97120This library should support all possible
98121[ filtering combinations that the CF API supports] ( https://v3-apidocs.cloudfoundry.org/version/3.188.0/index.html#filters ) ,
99122including those that may not be valid. While the library tries to steer you in a direction that won't allow for invalid
@@ -105,6 +128,7 @@ combinations it's still possible to create filters that are nonsensical. The sup
105128| String | x | x | | x |
106129
107130Full filtering example, find all apps with the name of spring-music:
131+
108132``` go
109133opts := client.NewAppListOptions ()
110134opts.Names .EqualTo (" spring-music" )
@@ -113,28 +137,33 @@ fmt.Printf("Found %d apps named spring-music\n", len(apps))
113137```
114138
115139Find multiple applications with specific names:
140+
116141``` go
117142opts.Names .EqualTo (" credit-processor-service" , " credit-processor-ui" )
118143```
119144
120145Find all apps not named spring-music:
146+
121147``` go
122148opts.Names .NotEqualTo (" spring-music" )
123149```
124150
125151Find all spring-music apps created within a date range:
152+
126153``` go
127154opts.Names .EqualTo (" spring-music" )
128155opts.CreateAts .After (date1)
129156opts.CreateAts .Before (date2)
130157```
131158
132159### Pagination
160+
133161All requests for resource collections (apps, orgs, spaces etc) support pagination. Pagination options are described
134162in the client.ListOptions struct and passed to the list methods directly or as an embedded type of a more specific
135163list options struct (for example client.AppListOptions).
136164
137165Example iterating through all apps one page at a time:
166+
138167``` go
139168opts := client.NewAppListOptions ()
140169for {
@@ -148,9 +177,11 @@ for {
148177 pager.NextPage (opts)
149178}
150179```
180+
151181If you'd rather get _ all_ of the resources in one go and not worry about paging, every collection
152182has a corresponding ` All ` method that gathers all the resources from every page before returning. While this may be
153183convenient, this could have negative performance consequences on larger foundations/collections.
184+
154185``` go
155186opts := client.NewAppListOptions ()
156187apps , _ := cf.Applications .ListAll (context.Background (), opts)
@@ -160,9 +191,11 @@ for _, app := range apps {
160191```
161192
162193### Asynchronous Jobs
194+
163195Some API calls are long-running so immediately return a JobID (GUID) instead of waiting and returning a resource. In
164196those cases you only know if the job was accepted. You will need to poll the Job API to find out when the job
165197finishes. There's a ` PollComplete ` utility function that you can use to block until the job finishes:
198+
166199``` go
167200jobGUID , err := cf.Manifests .ApplyManifest (context.Background (), spaceGUID, manifest))
168201if err != nil {
@@ -174,6 +207,7 @@ if err != nil {
174207 return err
175208}
176209```
210+
177211The timeout and polling interval can be configured using the PollingOptions struct.
178212
179213The PollComplete function will return a nil error if the job completes successfully. If PollComplete
@@ -182,10 +216,12 @@ failed then the job API is queried for the job error which is then returned as a
182216which can be inspected to find the failure cause.
183217
184218### Error Handling
219+
185220All client methods will return a ` resource.CloudFoundryError ` or sub-type for any response that isn't a 200 level
186221status code. All CF errors have a corresponding error code and the client uses those codes to construct a specific
187222client side error type. This allows you to easily branch your logic based off specific API error codes using one of
188223the many ` resource.IsSomeTypeOfError(err error) ` functions, for example:
224+
189225``` go
190226params , err := cf.ServiceCredentialBindings .GetParameters (guid)
191227if resource.IsServiceFetchBindingParametersNotSupportedError (err) {
@@ -198,7 +234,9 @@ if resource.IsServiceFetchBindingParametersNotSupportedError(err) {
198234```
199235
200236### Migrating v2 to v3
237+
201238A very basic example using the v2 client:
239+
202240``` go
203241c := &cfclient.Config {
204242 ApiAddress : " https://api.sys.example.com" ,
@@ -208,10 +246,12 @@ c := &cfclient.Config{
208246client , _ := cfclient.NewClient (c)
209247apps , _ := client.ListApps ()
210248for _ , a := range apps {
211- fmt.Println (a.Name )
249+ fmt.Println (a.Name )
212250}
213251```
252+
214253Converted to do the same in the v3 client:
254+
215255``` go
216256cfg , _ := config.New (" https://api.sys.example.org" , config.UserPassword (" user" , " pass" ))
217257client , _ := client.New (cfg)
@@ -220,10 +260,12 @@ for _, app := range apps {
220260 fmt.Println (app.Name )
221261}
222262```
263+
223264If you need to migrate over to the new client iteratively you can do that by referencing both the old and new modules
224265simultaneously and creating two separate client instances - one for each module version.
225266
226267Some of the main differences between the old client and the new v3 client include:
268+
227269- The old v2 client supported most v2 resources and few a v3 resources. The new v3 client supports all v3 resources and
228270no v2 resources. While most v2 resources are similar to their v3 counterparts, some code changes will need to be made.
229271- The v2 client had a single type that contained resource functions disambiguated by function name. The v3
@@ -235,6 +277,7 @@ client has a separate client nested under the main client for each resource. For
235277- The v3 client supports shared access across goroutines.
236278
237279## Versioning
280+
238281In general, go-cfclient follows [ semver] ( https://go.dev/doc/modules/version-number ) as closely as we can for [ tagging
239282releases] ( https://go.dev/doc/modules/publishing ) of the package. We've adopted the following versioning policy:
240283
@@ -256,7 +299,7 @@ functions should have at least once basic unit test.
256299
257300### Errors
258301
259- If the Cloud Foundry error definitions change at < https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml >
302+ If the Cloud Foundry error definitions change at [ https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml ] ( https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml )
260303then the error predicate functions in this package need to be regenerated.
261304
262305To do this, simply use Go to regenerate the code:
0 commit comments