Adding docs and adding event list opts
diff --git a/rackspace/lb/v1/nodes/doc.go b/rackspace/lb/v1/nodes/doc.go
index 970f7f0..49c4318 100644
--- a/rackspace/lb/v1/nodes/doc.go
+++ b/rackspace/lb/v1/nodes/doc.go
@@ -1 +1,35 @@
+/*
+Package nodes provides information and interaction with the Node API resource
+for the Rackspace Cloud Load Balancer service.
+
+Nodes are responsible for servicing the requests received through the load
+balancer's virtual IP. A node is usually a virtual machine. By default, the
+load balancer employs a basic health check that ensures the node is listening
+on its defined port. The node is checked at the time of addition and at regular
+intervals as defined by the load balancer's health check configuration. If a
+back-end node is not listening on its port, or does not meet the conditions of
+the defined check, then connections will not be forwarded to the node, and its
+status is changed to OFFLINE. Only nodes that are in an ONLINE status receive
+and can service traffic from the load balancer.
+
+All nodes have an associated status that indicates whether the node is
+ONLINE, OFFLINE, or DRAINING. Only nodes that are in ONLINE status can receive
+and service traffic from the load balancer. The OFFLINE status represents a
+node that cannot accept or service traffic. A node in DRAINING status
+represents a node that stops the traffic manager from sending any additional
+new connections to the node, but honors established sessions. If the traffic
+manager receives a request and session persistence requires that the node is
+used, the traffic manager uses it. The status is determined by the passive or
+active health monitors.
+
+If the WEIGHTED_ROUND_ROBIN load balancer algorithm mode is selected, then the
+caller should assign the relevant weights to the node as part of the weight
+attribute of the node element. When the algorithm of the load balancer is
+changed to WEIGHTED_ROUND_ROBIN and the nodes do not already have an assigned
+weight, the service automatically sets the weight to 1 for all nodes.
+
+One or more secondary nodes can be added to a specified load balancer so that
+if all the primary nodes fail, traffic can be redirected to secondary nodes.
+The type attribute allows configuring the node as either PRIMARY or SECONDARY.
+*/
package nodes
diff --git a/rackspace/lb/v1/nodes/requests.go b/rackspace/lb/v1/nodes/requests.go
index f3f2850..28c6bf2 100644
--- a/rackspace/lb/v1/nodes/requests.go
+++ b/rackspace/lb/v1/nodes/requests.go
@@ -10,6 +10,9 @@
"github.com/rackspace/gophercloud/rackspace/lb/v1"
)
+// List is the operation responsible for returning a paginated collection of
+// load balancer nodes. It requires the node ID, its parent load balancer ID,
+// and optional limit integer (passed in either as a pointer or a nil poitner).
func List(client *gophercloud.ServiceClient, loadBalancerID int, limit *int) pagination.Pager {
url := rootURL(client, loadBalancerID)
if limit != nil {
@@ -21,19 +24,33 @@
})
}
+// CreateOptsBuilder is the interface responsible for generating the JSON
+// for a Create operation.
type CreateOptsBuilder interface {
ToNodeCreateMap() (map[string]interface{}, error)
}
+// CreateOpts is a slice of CreateOpt structs, that allow the user to create
+// multiple nodes in a single operation (one node per CreateOpt).
type CreateOpts []CreateOpt
+// CreateOpt represents the options to create a single node.
type CreateOpt struct {
- // Required
- Address string
- Port int
+ // Required - the IP address or CIDR for this back-end node. It can either be
+ // a private IP (ServiceNet) or a public IP.
+ Address string
+
+ // Optional - the port on which traffic is sent and received.
+ Port int
+
+ // Optional - the condition of the node. See the consts in Results.go.
Condition Condition
- Type Type
- Weight *int
+
+ // Optional - the type of the node. See the consts in Results.go.
+ Type Type
+
+ // Optional - a pointer to an integer between 0 and 100.
+ Weight *int
}
func validateWeight(weight *int) error {
@@ -43,6 +60,8 @@
return nil
}
+// ToNodeCreateMap converts a slice of options into a map that can be used for
+// the JSON.
func (opts CreateOpts) ToNodeCreateMap() (map[string]interface{}, error) {
type nodeMap map[string]interface{}
nodes := []nodeMap{}
@@ -77,6 +96,15 @@
return nodeMap{"nodes": nodes}, nil
}
+// Create is the operation responsible for creating a new node on a load
+// balancer. Since every load balancer exists in both ServiceNet and the public
+// Internet, both private and public IP addresses can be used for nodes.
+//
+// If nodes need time to boot up services before they become operational, you
+// can temporarily prevent traffic from being sent to that node by setting the
+// Condition field to DRAINING. Health checks will still be performed; but once
+// your node is ready, you can update its condition to ENABLED and have it
+// handle traffic.
func Create(client *gophercloud.ServiceClient, loadBalancerID int, opts CreateOptsBuilder) CreateResult {
var res CreateResult
@@ -106,6 +134,9 @@
return CreateResult{pagination.SinglePageBase(pr)}
}
+// BulkDelete is the operation responsible for batch deleting multiple nodes in
+// a single operation. It accepts a slice of integer IDs and will remove them
+// from the load balancer. The maximum limit is 10 node removals at once.
func BulkDelete(c *gophercloud.ServiceClient, loadBalancerID int, nodeIDs []int) DeleteResult {
var res DeleteResult
@@ -125,6 +156,7 @@
return res
}
+// Get is the operation responsible for showing details for a single node.
func Get(c *gophercloud.ServiceClient, lbID, nodeID int) GetResult {
var res GetResult
@@ -137,21 +169,35 @@
return res
}
+// IntToPointer is a function for converting integers into integer pointers.
+// This is useful when updating the weight of a node.
func IntToPointer(i int) *int {
return &i
}
+// UpdateOptsBuilder represents a type that can be converted into a JSON-like
+// map structure.
type UpdateOptsBuilder interface {
ToNodeUpdateMap() (map[string]interface{}, error)
}
+// UpdateOpts represent the options for updating an existing node.
type UpdateOpts struct {
- Address string
+ // Optional - the IP address or CIDR for this back-end node. It can either be
+ // a private IP (ServiceNet) or a public IP.
+ Address string
+
+ // Optional - the condition of the node. See the consts in Results.go.
Condition Condition
- Weight *int
- Type Type
+
+ // Optional - the type of the node. See the consts in Results.go.
+ Type Type
+
+ // Optional - a pointer to an integer between 0 and 100.
+ Weight *int
}
+// ToNodeUpdateMap converts an options struct into a JSON-like map.
func (opts UpdateOpts) ToNodeUpdateMap() (map[string]interface{}, error) {
node := make(map[string]interface{})
@@ -174,6 +220,8 @@
return map[string]interface{}{"node": node}, nil
}
+// Update is the operation responsible for updating an existing node. A node's
+// IP, port, and status are immutable attributes and cannot be modified.
func Update(c *gophercloud.ServiceClient, lbID, nodeID int, opts UpdateOptsBuilder) UpdateResult {
var res UpdateResult
@@ -192,6 +240,7 @@
return res
}
+// Delete is the operation responsible for permanently deleting a node.
func Delete(c *gophercloud.ServiceClient, lbID, nodeID int) DeleteResult {
var res DeleteResult
_, res.Err = perigee.Request("DELETE", resourceURL(c, lbID, nodeID), perigee.Options{
@@ -201,8 +250,43 @@
return res
}
-func ListEvents(client *gophercloud.ServiceClient, loadBalancerID, nodeID int) pagination.Pager {
+// ListEventsOptsBuilder allows extensions to add additional parameters to the
+// List request.
+type ListEventsOptsBuilder interface {
+ ToEventsListQuery() (string, error)
+}
+
+// ListEventsOpts allows the filtering and sorting of paginated collections through
+// the API.
+type ListEventsOpts struct {
+ Marker string `q:"marker"`
+ Limit int `q:"limit"`
+}
+
+// ToEventsListQuery formats a ListOpts into a query string.
+func (opts ListEventsOpts) ToEventsListQuery() (string, error) {
+ q, err := gophercloud.BuildQueryString(opts)
+ if err != nil {
+ return "", err
+ }
+ return q.String(), nil
+}
+
+// ListEvents is the operation responsible for listing all the events
+// associated with the activity between the node and the load balancer. The
+// events report errors found with the node. The detailedMessage provides the
+// detailed reason for the error.
+func ListEvents(client *gophercloud.ServiceClient, loadBalancerID, nodeID int, opts ListEventsOptsBuilder) pagination.Pager {
url := eventsURL(client, loadBalancerID, nodeID)
+
+ if opts != nil {
+ query, err := opts.ToEventsListQuery()
+ if err != nil {
+ return pagination.Pager{Err: err}
+ }
+ url += query
+ }
+
return pagination.NewPager(client, url, func(r pagination.PageResult) pagination.Page {
return NodeEventPage{pagination.SinglePageBase(r)}
})