api

Documentation

Overview

Package api provides types and methods for interfacing with a Cisco UCS API endpoint.

Example (AaaKeepAlive)

package main

import (
	"context"
	"crypto/tls"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/dnaeon/go-ucs/api"
)

func main() {
	// The following example shows how to keep a session alive.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	// Authenticate to the remote API endpoint and obtain authentication cookie
	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to authenticate: %s", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	// Channel on which the shutdown signal is sent
	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

	// Send a KeepAlive request every minute
	ticker := time.NewTicker(1 * time.Minute)

L:
	for {
		select {
		case <-quit:
			log.Println("Keyboard interrupt detected, terminating.")
			break L
		case <-ticker.C:
			log.Println("Sending KeepAlive request ...")
			resp, err := client.AaaKeepAlive(ctx)
			if err != nil {
				log.Printf("Unable to keep session alive: %s\n", err)
				break L
			}

			log.Printf("Got response with cookie: %s\n", resp.Cookie)
		}
	}
}

Example (AaaLogin)

package main

import (
	"context"
	"crypto/tls"
	"log"
	"net/http"

	"github.com/dnaeon/go-ucs/api"
)

func main() {
	// The following example shows how to login and logout from a Cisco UCS API endpoint

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s\n", err)
	}

	// Authenticate to the remote API endpoint and obtain authentication cookie
	log.Printf("Logging in to %s\n", config.Endpoint)

	ctx := context.Background()
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to authenticate: %s", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)
}

Example (AaaRefresh)

package main

import (
	"context"
	"crypto/tls"
	"log"
	"net/http"

	"github.com/dnaeon/go-ucs/api"
)

func main() {
	// The following example shows how to refresh an existing session.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	// Authenticate to the remote API endpoint and obtain authentication cookie
	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to authenticate: %s", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	log.Println("Refreshing session")
	if _, err := client.AaaRefresh(ctx); err != nil {
		log.Fatalf("Unable to refresh session: %s\n", err)
	}

	log.Printf("New authentication cookie is: %s\n", client.Cookie)
}

Example (CompositeFilter)

package main

import (
	"context"
	"crypto/tls"
	"encoding/xml"
	"log"
	"net/http"

	"github.com/dnaeon/go-ucs/api"
	"github.com/dnaeon/go-ucs/mo"
)

func main() {
	// The following example shows how to use a composite AND property filter.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to login: %s\n", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	// The type into which we unmarshal the result data
	type blades struct {
		XMLName xml.Name
		Blades  []mo.ComputeBlade `xml:"computeBlade"`
	}

	// Create a composite AND property filter, which will find all blades,
	// which have total memory greater than or equal to 2048 MB and are in chassis 3.
	filter := api.FilterAnd{
		Filters: []api.FilterAny{
			api.FilterGe{
				FilterProperty: api.FilterProperty{
					Class:    "computeBlade",
					Property: "totalMemory",
					Value:    "2048",
				},
			},
			api.FilterEq{
				FilterProperty: api.FilterProperty{
					Class:    "computeBlade",
					Property: "chassisId",
					Value:    "3",
				},
			},
		},
	}

	req := api.ConfigResolveClassRequest{
		Cookie:         client.Cookie,
		InHierarchical: "false",
		ClassId:        "computeBlade",
		InFilter:       filter,
	}

	var out blades
	log.Println("Retrieving managed objects with class `computeBlade`")
	if err := client.ConfigResolveClass(ctx, req, &out); err != nil {
		log.Fatalf("Unable to retrieve `computeBlade` managed object: %s", err)
	}

	log.Printf("Retrieved %d compute blades\n", len(out.Blades))

	for _, blade := range out.Blades {
		log.Printf("%s:\n", blade.Dn)
		log.Printf("\tNumber of CPUs: %d\n", blade.NumOfCpus)
		log.Printf("\tTotal Memory: %d\n", blade.TotalMemory)
		log.Printf("\tModel: %s\n", blade.Model)
		log.Printf("\tChassis ID: %d\n", blade.ChassisId)
		log.Printf("\tVendor: %s\n", blade.Vendor)
	}
}

Example (ConfigResolveClass)

package main

import (
	"context"
	"crypto/tls"
	"encoding/xml"
	"log"
	"net/http"

	"github.com/dnaeon/go-ucs/api"
	"github.com/dnaeon/go-ucs/mo"
)

func main() {
	// The following example shows how to retrieve all compute blades.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to login: %s\n", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	// The type into which we unmarshal the result data
	type blades struct {
		XMLName xml.Name
		Blades  []mo.ComputeBlade `xml:"computeBlade"`
	}

	req := api.ConfigResolveClassRequest{
		Cookie:         client.Cookie,
		ClassId:        "computeBlade",
		InHierarchical: "false",
	}

	var out blades

	log.Println("Retrieving managed objects with class `computeBlade`")
	if err := client.ConfigResolveClass(ctx, req, &out); err != nil {
		log.Fatalf("Unable to retrieve `computeBlade` managed object: %s", err)
	}

	log.Printf("Retrieved %d compute blades\n", len(out.Blades))
	for _, blade := range out.Blades {
		log.Printf("%s:\n", blade.Dn)
		log.Printf("\tNumber of CPUs: %d\n", blade.NumOfCpus)
		log.Printf("\tTotal Memory: %d\n", blade.TotalMemory)
		log.Printf("\tModel: %s\n", blade.Model)
		log.Printf("\tVendor: %s\n", blade.Vendor)
	}
}

Example (ConfigResolveClasses)

package main

import (
	"context"
	"crypto/tls"
	"log"
	"net/http"

	"github.com/dnaeon/go-ucs/api"
	"github.com/dnaeon/go-ucs/mo"
)

func main() {
	// The following example shows how to retrieve managed objects from different classes.
	// In the example below we will retrieve the managed objects of `computeBlade` and `computeRackUnit` classes.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to login: %s\n", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	req := api.ConfigResolveClassesRequest{
		Cookie:         client.Cookie,
		InHierarchical: "false",
		InIds: []api.Id{
			api.NewId("computeBlade"),
			api.NewId("computeRackUnit"),
		},
	}

	// ComputeItem is a container for all physical compute items.
	var out mo.ComputeItem

	log.Println("Retrieving managed objects with classes `computeBlade` and `computeRackUnit`")
	if err := client.ConfigResolveClasses(ctx, req, &out); err != nil {
		log.Fatalf("Unable to retrieve `computeBlade` and `computeRackUnit` managed object: %s", err)
	}

	log.Printf("Retrieved %d compute blades\n", len(out.Blades))
	log.Printf("Retrieved %d compute rack units\n", len(out.RackUnits))

	for _, blade := range out.Blades {
		log.Printf("%s:\n", blade.Dn)
		log.Printf("\tNumber of CPUs: %d\n", blade.NumOfCpus)
		log.Printf("\tTotal Memory: %d\n", blade.TotalMemory)
		log.Printf("\tModel: %s\n", blade.Model)
		log.Printf("\tVendor: %s\n", blade.Vendor)
	}

	for _, blade := range out.RackUnits {
		log.Printf("%s:\n", blade.Dn)
		log.Printf("\tNumber of CPUs: %d\n", blade.NumOfCpus)
		log.Printf("\tTotal Memory: %d\n", blade.TotalMemory)
		log.Printf("\tModel: %s\n", blade.Model)
		log.Printf("\tVendor: %s\n", blade.Vendor)
	}
}

Example (ConfigResolveDn)

package main

import (
	"context"
	"crypto/tls"
	"log"
	"net/http"

	"github.com/dnaeon/go-ucs/api"
	"github.com/dnaeon/go-ucs/mo"
)

func main() {
	// The following example shows how to retrieve a single managed object for a specified DN.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to login: %s\n", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	// Retrieve the `sys` DN, which is of type mo.TopSystem
	log.Println("Retrieving `sys` managed object")
	req := api.ConfigResolveDnRequest{
		Cookie:         client.Cookie,
		Dn:             "sys",
		InHierarchical: "false",
	}

	var sys mo.TopSystem
	if err := client.ConfigResolveDn(ctx, req, &sys); err != nil {
		log.Fatalf("Unable to retrieve DN: %s", err)
	}

	log.Printf("Address: %s\n", sys.Address)
	log.Printf("Current time: %s\n", sys.CurrentTime)
	log.Printf("Dn: %s\n", sys.Dn)
	log.Printf("Mode: %s\n", sys.Mode)
	log.Printf("Uptime: %s\n", sys.SystemUptime)
}

Example (ConfigResolveDns)

package main

import (
	"context"
	"crypto/tls"
	"encoding/xml"
	"log"
	"net/http"
	"strings"

	"github.com/dnaeon/go-ucs/api"
	"github.com/dnaeon/go-ucs/mo"
)

func main() {
	// The following example shows how to retrieve a list of managed objects by specifying their DNs.

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to login: %s\n", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	// A type to contain the instances of the retrieved DNs.
	type outConfigs struct {
		XMLName xml.Name
		Sys     mo.TopSystem          `xml:"topSystem"`
		Version mo.VersionApplication `xml:"versionApplication"`
	}

	var out outConfigs

	// Retrieve the list of DNs
	log.Println("Retrieving managed objects using configResolveDns query method")
	req := api.ConfigResolveDnsRequest{
		Cookie:         client.Cookie,
		InHierarchical: "false",
		InDns: []api.Dn{
			api.NewDn("sys"),
			api.NewDn("sys/version/application"),
			api.NewDn("no/such/dn"),
		},
	}

	resp, err := client.ConfigResolveDns(ctx, req, &out)
	if err != nil {
		log.Fatalf("Unable to retrieve DNs: %s", err)
	}

	log.Printf("%s is at version %s\n", out.Sys.Name, out.Version.Version)

	unresolved := make([]string, 0)
	for _, dn := range resp.OutUnresolved {
		unresolved = append(unresolved, dn.Value)
	}
	log.Printf("Unresolved DNs: %s", strings.Join(unresolved, ", "))
}

Example (RateLimiter)

package main

import (
	"context"
	"crypto/tls"
	"log"
	"net/http"
	"sync"
	"time"

	"github.com/dnaeon/go-ucs/api"
	"github.com/dnaeon/go-ucs/mo"
)

func main() {
	// The following example shows how to rate limit requests again the remote
	// Cisco UCS API endpoint using a token bucket rate limiter.
	// https://en.wikipedia.org/wiki/Token_bucket

	// Skip SSL certificate verification of remote endpoint.
	tr := &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	}
	httpClient := &http.Client{Transport: tr}

	// Create a new Cisco UCS API client.
	// Set maximum allowed requests per second to 1 with a burst size of 1.
	// A request will wait up to 1 minute for a token.
	config := api.Config{
		Endpoint:   "https://ucs01.example.org/",
		Username:   "admin",
		Password:   "password",
		HttpClient: httpClient,
		RateLimit: &api.RateLimit{
			RequestsPerSecond: 1.0,
			Burst:             1,
			Wait:              time.Duration(1 * time.Minute),
		},
	}

	client, err := api.NewClient(config)
	if err != nil {
		log.Fatalf("Unable to create API client: %s", err)
	}

	ctx := context.Background()

	log.Printf("Logging in to %s\n", config.Endpoint)
	if _, err := client.AaaLogin(ctx); err != nil {
		log.Fatalf("Unable to login: %s\n", err)
	}
	defer client.AaaLogout(ctx)

	log.Printf("Got authentication cookie: %s\n", client.Cookie)

	// Start a few concurrent requests to the remote API endpoint.
	// Requests will be executed one at a time, because of how the limiter is configured.
	var wg sync.WaitGroup
	for i := 1; i < 10; i++ {
		wg.Add(1)

		// Our worker function will retrieve the `sys` DN from the remote Cisco UCS API.
		// We will start a few of these in separate goroutines.
		worker := func(id int) {
			defer wg.Done()

			// Retrieve the `sys` DN, which is of type mo.TopSystem
			log.Printf("Worker #%d: Retrieving `sys` managed object\n", id)
			req := api.ConfigResolveDnRequest{
				Cookie:         client.Cookie,
				Dn:             "sys",
				InHierarchical: "false",
			}

			var sys mo.TopSystem
			if err := client.ConfigResolveDn(ctx, req, &sys); err != nil {
				log.Printf("Worker #%d: Unable to retrieve DN: %s\n", id, err)
				return
			}

			log.Printf("Worker #%d: successfully retrieved `sys` managed object\n", id)
		}

		go worker(i)
	}

	wg.Wait()
}

Index

• type AaaKeepAliveRequest
• type AaaKeepAliveResponse
• type AaaLoginRequest
• type AaaLoginResponse
• type AaaLogoutRequest
• type AaaLogoutResponse
• type AaaRefreshRequest
• type AaaRefreshResponse
• type BaseResponse
  • func (b *BaseResponse) Error() string
  • func (b *BaseResponse) IsError() bool
  • func (b *BaseResponse) ToError() error
• type Client
  • func NewClient(config Config) (*Client, error)
  • func (c *Client) AaaKeepAlive(ctx context.Context) (*AaaKeepAliveResponse, error)
  • func (c *Client) AaaLogin(ctx context.Context) (*AaaLoginResponse, error)
  • func (c *Client) AaaLogout(ctx context.Context) (*AaaLogoutResponse, error)
  • func (c *Client) AaaRefresh(ctx context.Context) (*AaaRefreshResponse, error)
  • func (c *Client) ConfigResolveChildren(ctx context.Context, in ConfigResolveChildrenRequest, out mo.Any) error
  • func (c *Client) ConfigResolveClass(ctx context.Context, in ConfigResolveClassRequest, out mo.Any) error
  • func (c *Client) ConfigResolveClasses(ctx context.Context, in ConfigResolveClassesRequest, out mo.Any) error
  • func (c *Client) ConfigResolveDn(ctx context.Context, in ConfigResolveDnRequest, out mo.Any) error
  • func (c *Client) ConfigResolveDns(ctx context.Context, in ConfigResolveDnsRequest, out mo.Any) (*ConfigResolveDnsResponse, error)
  • func (c *Client) Hostname() string
  • func (c *Client) Request(ctx context.Context, in, out interface{}) error
  • func (c *Client) RequestNow(ctx context.Context, in, out interface{}) error
• type Config
• type ConfigResolveChildrenRequest
• type ConfigResolveChildrenResponse
• type ConfigResolveClassRequest
• type ConfigResolveClassResponse
• type ConfigResolveClassesRequest
• type ConfigResolveClassesResponse
• type ConfigResolveDnRequest
• type ConfigResolveDnResponse
• type ConfigResolveDnsRequest
• type ConfigResolveDnsResponse
• type Dn
  • func NewDn(value string) Dn
• type FilterAllBits
• type FilterAnd
• type FilterAny
• type FilterAnyBits
• type FilterBetween
• type FilterEq
• type FilterGe
• type FilterGt
• type FilterLe
• type FilterLt
• type FilterNe
• type FilterNot
• type FilterOr
• type FilterProperty
• type FilterWildcard
• type Id
  • func NewId(value string) Id
• type InnerXml
• type RateLimit

Examples

• Package (AaaKeepAlive)
• Package (AaaLogin)
• Package (AaaRefresh)
• Package (CompositeFilter)
• Package (ConfigResolveClass)
• Package (ConfigResolveClasses)
• Package (ConfigResolveDn)
• Package (ConfigResolveDns)
• Package (RateLimiter)

Types

type AaaKeepAliveRequest

type AaaKeepAliveRequest struct {
	XMLName xml.Name `xml:"aaaKeepAlive"`
	Cookie  string   `xml:"cookie,attr"`
}

AaaKeepAliveRequest type is used for sending a request for keeping a session active until the default session time expires.

type AaaKeepAliveResponse

type AaaKeepAliveResponse struct {
	BaseResponse
	XMLName xml.Name `xml:"aaaKeepAlive"`
	Cookie  string   `xml:"cookie,attr"`
}

AaaKeepAliveResponse is the response type associated with a AaaKeepAliveRequest.

type AaaLoginRequest

type AaaLoginRequest struct {
	XMLName    xml.Name `xml:"aaaLogin"`
	InName     string   `xml:"inName,attr"`
	InPassword string   `xml:"inPassword,attr"`
}

AaaLoginRequest is the type which is sent during initial login in order to obtain authentication cookie.

type AaaLoginResponse

type AaaLoginResponse struct {
	BaseResponse
	XMLName          xml.Name `xml:"aaaLogin"`
	OutCookie        string   `xml:"outCookie,attr,omitempty"`
	OutRefreshPeriod int      `xml:"outRefreshPeriod,attr,omitempty"`
	OutPriv          string   `xml:"outPriv,attr,omitempty"`
	OutDomains       string   `xml:"outDomains,attr,omitempty"`
	OutChannel       string   `xml:"outChannel,attr,omitempty"`
	OutEvtChannel    string   `xml:"outEvtChannel,attr,omitempty"`
	OutName          string   `xml:"outName,attr,omitempty"`
	OutVersion       string   `xml:"outVersion,attr,omitempty"`
	OutSessionId     string   `xml:"outSessionId,attr,omitempty"`
}

AaaLoginResponse represents the response after a successful login to UCS manager.

type AaaLogoutRequest

type AaaLogoutRequest struct {
	XMLName  xml.Name `xml:"aaaLogout"`
	InCookie string   `xml:"inCookie,attr"`
}

AaaLogoutRequest type is used for sending a request to invalidate an existing authentication cookie.

type AaaLogoutResponse

type AaaLogoutResponse struct {
	BaseResponse
	XMLName   xml.Name `xml:"aaaLogout"`
	OutStatus string   `xml:"outStatus,attr,omitempty"`
}

AaaLogoutResponse represents the type that is returned after a call to aaaLogout method.

type AaaRefreshRequest

type AaaRefreshRequest struct {
	XMLName    xml.Name `xml:"aaaRefresh"`
	InName     string   `xml:"inName,attr"`
	InPassword string   `xml:"inPassword,attr"`
	InCookie   string   `xml:"inCookie,attr"`
}

AaaRefreshRequest type is used for sending a request to the remote API endpoint for refreshing a session using the 47-character cookie obtained from a previous refresh or during the initial authentication as returned in a AaaLoginResponse.

type AaaRefreshResponse

type AaaRefreshResponse struct {
	XMLName xml.Name `xml:"aaaRefresh"`
	AaaLoginResponse
}

AaaRefreshResponse is the response associated to a AaaRefreshRequest.

type BaseResponse

type BaseResponse struct {
	Cookie           string `xml:"cookie,attr"`
	Response         string `xml:"response,attr"`
	ErrorCode        string `xml:"errorCode,attr,omitempty"`
	InvocationResult string `xml:"invocationResult,attr,omitempty"`
	ErrorDescription string `xml:"errorDescr,attr,omitempty"`
}

BaseResponse contains the base attributes as returned in a response from a Cisco UCS API endpoint.

func (*BaseResponse) Error

func (b *BaseResponse) Error() string

Error implements the error interface.

func (*BaseResponse) IsError

func (b *BaseResponse) IsError() bool

IsError returns a boolean indicating whether the response contains errors.

func (*BaseResponse) ToError

func (b *BaseResponse) ToError() error

ToError creates a new error.Error from the error response fields.

type Client

type Client struct {

	// Cookie is the authentication cookie currently in use.
	// It's value is set by the AaaLogin and AaaRefresh methods.
	Cookie string
	// contains filtered or unexported fields
}

Client is used for interfacing with the remote Cisco UCS API endpoint.

func NewClient

func NewClient(config Config) (*Client, error)

NewClient creates a new API client from the given config.

func (*Client) AaaKeepAlive

func (c *Client) AaaKeepAlive(ctx context.Context) (*AaaKeepAliveResponse, error)

AaaKeepAlive sends a request to keep the current session active using the same cookie.

func (*Client) AaaLogin

func (c *Client) AaaLogin(ctx context.Context) (*AaaLoginResponse, error)

AaaLogin performs the initial authentication to the remote Cisco UCS API endpoint.

func (*Client) AaaLogout

func (c *Client) AaaLogout(ctx context.Context) (*AaaLogoutResponse, error)

AaaLogout invalidates the current client session.

func (*Client) AaaRefresh

func (c *Client) AaaRefresh(ctx context.Context) (*AaaRefreshResponse, error)

AaaRefresh refreshes the current session by requesting a new authentication cookie.

func (*Client) ConfigResolveChildren

func (c *Client) ConfigResolveChildren(ctx context.Context, in ConfigResolveChildrenRequest, out mo.Any) error

ConfigResolveChildren retrieves children of managed objects under a specified DN.

func (*Client) ConfigResolveClass

func (c *Client) ConfigResolveClass(ctx context.Context, in ConfigResolveClassRequest, out mo.Any) error

ConfigResolveClass retrieves managed objects of the specified class.

func (*Client) ConfigResolveClasses

func (c *Client) ConfigResolveClasses(ctx context.Context, in ConfigResolveClassesRequest, out mo.Any) error

ConfigResolveClasses retrieves managed objects from the specified list of classes.

func (*Client) ConfigResolveDn

func (c *Client) ConfigResolveDn(ctx context.Context, in ConfigResolveDnRequest, out mo.Any) error

ConfigResolveDn retrieves a single managed object for a specified DN.

func (*Client) ConfigResolveDns

func (c *Client) ConfigResolveDns(ctx context.Context, in ConfigResolveDnsRequest, out mo.Any) (*ConfigResolveDnsResponse, error)

ConfigResolveDns retrieves managed objects for a specified list of DNs.

func (*Client) Hostname

func (c *Client) Hostname() string

Hostname returns the host portion of the remote UCS API endpoint without any port number.

func (*Client) Request

func (c *Client) Request(ctx context.Context, in, out interface{}) error

Request sends a POST request to the remote Cisco UCS API endpoint.

func (*Client) RequestNow

func (c *Client) RequestNow(ctx context.Context, in, out interface{}) error

RequestNow sends a POST request to the remote Cisco UCS API endpoint immediately. This bypasses any rate limiter configuration that may be used and is meant to be used for priority requests, e.g. refreshing a token, logging out, etc.

type Config

type Config struct {
	// HttpClient is the HTTP client to use for sending requests.
	// If nil then we use http.DefaultClient for all requests.
	HttpClient *http.Client

	// Endpoint is the base URL to the remote Cisco UCS Manager endpoint.
	Endpoint string

	// Username to use when authenticating to the remote endpoint.
	Username string

	// Password to use when authenticating to the remote endpoint.
	Password string

	// RateLimit is used for limiting the number of requests per second
	// against the remote Cisco UCS API endpoint using a token bucket.
	RateLimit *RateLimit
}

Config type contains the setting used by the Client.

type ConfigResolveChildrenRequest

type ConfigResolveChildrenRequest struct {
	XMLName        xml.Name  `xml:"configResolveChildren"`
	Cookie         string    `xml:"cookie,attr"`
	ClassId        string    `xml:"classId,attr"`
	InDn           string    `xml:"inDn,attr"`
	InHierarchical string    `xml:"inHierarchical,attr"`
	InFilter       FilterAny `xml:"inFilter>any,omitempty"`
}

ConfigResolveChildren type is used for constructing requests that retrieve children of managed objects under a specified DN. A filter can be used to reduce the number of children being returned.

type ConfigResolveChildrenResponse

type ConfigResolveChildrenResponse struct {
	BaseResponse
	XMLName    xml.Name `xml:"configResolveChildren"`
	OutConfigs InnerXml `xml:"outConfigs"`
}

ConfigResolveChildrenResponse is the response type associated with a ConfigResolveChildrenRequest.

type ConfigResolveClassRequest

type ConfigResolveClassRequest struct {
	XMLName        xml.Name  `xml:"configResolveClass"`
	Cookie         string    `xml:"cookie,attr"`
	ClassId        string    `xml:"classId,attr"`
	InHierarchical string    `xml:"inHierarchical,attr,omitempty"`
	InFilter       FilterAny `xml:"inFilter>any,omitempty"`
}

ConfigResolveClassRequest type is used for constructing requests that retrieve managed objects of a given class.

type ConfigResolveClassResponse

type ConfigResolveClassResponse struct {
	BaseResponse
	XMLName    xml.Name `xml:"configResolveClass"`
	OutConfigs InnerXml `xml:"outConfigs"`
}

ConfigResolveClassResponse is the type associated with a ConfigResolveClassRequest. Specific classes contained within OutConfigs should be xml.Unmarshal'ed first.

type ConfigResolveClassesRequest

type ConfigResolveClassesRequest struct {
	XMLName        xml.Name `xml:"configResolveClasses"`
	Cookie         string   `xml:"cookie,attr"`
	InHierarchical string   `xml:"inHierarchical,attr,omitempty"`
	InIds          []Id     `xml:"inIds>Id"`
}

ConfigResolveClassesRequest type is used for constructing requests that retrieve managed objects in several classes.

type ConfigResolveClassesResponse

type ConfigResolveClassesResponse struct {
	BaseResponse
	XMLName    xml.Name `xml:"configResolveClasses"`
	OutConfigs InnerXml `xml:"outConfigs"`
}

ConfigResolveClassesResponse is the response type associated with a ConfigResolveClassesRequest.

type ConfigResolveDnRequest

type ConfigResolveDnRequest struct {
	XMLName        xml.Name `xml:"configResolveDn"`
	Cookie         string   `xml:"cookie,attr"`
	Dn             string   `xml:"dn,attr"`
	InHierarchical string   `xml:"inHierarchical,attr,omitempty"`
}

ConfigResolveDnRequest type is used for constructing requests that retrieve a single managed object with the given DN.

type ConfigResolveDnResponse

type ConfigResolveDnResponse struct {
	BaseResponse
	XMLName   xml.Name `xml:"configResolveDn"`
	Dn        string   `xml:"dn,attr"`
	OutConfig InnerXml `xml:"outConfig"`
}

ConfigResolveDnResponse is the type associated with a ConfigResolveDnRequest type. Specific classes contained within OutConfig should be xml.Unmarshal'ed first.

type ConfigResolveDnsRequest

type ConfigResolveDnsRequest struct {
	XMLName        xml.Name `xml:"configResolveDns"`
	Cookie         string   `xml:"cookie,attr"`
	InHierarchical string   `xml:"inHierarchical,attr,omitempty"`
	InDns          []Dn     `xml:"inDns>dn"`
}

ConfigResolveDnsRequest type is used for constructing requests that retrieve managed objects for a list of given DNs.

type ConfigResolveDnsResponse

type ConfigResolveDnsResponse struct {
	BaseResponse
	XMLName       xml.Name `xml:"configResolveDns"`
	OutUnresolved []Dn     `xml:"outUnresolved>dn"`
	OutConfigs    InnerXml `xml:"outConfigs"`
}

ConfigResolveDnsResponse is the response type associated with a ConfigResolveDnsRequest. The managed objects within OutConfigs field should be xml.Unmarshal'ed.

type Dn

type Dn struct {
	XMLName xml.Name `xml:"dn"`
	Value   string   `xml:"value,attr"`
}

Dn represents a single managed object DN.

func NewDn

func NewDn(value string) Dn

NewDn creates a new DN value.

type FilterAllBits

type FilterAllBits struct {
	XMLName xml.Name `xml:"allbits"`
	FilterProperty
}

FilterAllBits represents an All Bits Filter.

type FilterAnd

type FilterAnd struct {
	XMLName xml.Name `xml:"and"`
	Filters []FilterAny
}

FilterAnd represents a composite AND Filter.

type FilterAny

type FilterAny interface{}

FilterAny represents any valid filter.

type FilterAnyBits

type FilterAnyBits struct {
	XMLName xml.Name `xml:"anybit"`
	FilterProperty
}

FilterAnyBits represents an Any Bits Filter.

type FilterBetween

type FilterBetween struct {
	XMLName     xml.Name `xml:"bw"`
	Class       string   `xml:"class,attr"`
	Property    string   `xml:"property,attr"`
	FirstVault  string   `xml:"firstValue,attr"`
	SecondValue string   `xml:"secondValue,attr"`
}

FilterBetween represents a Between Filter.

type FilterEq

type FilterEq struct {
	XMLName xml.Name `xml:"eq"`
	FilterProperty
}

FilterEq represents an Equality Filter.

type FilterGe

type FilterGe struct {
	XMLName xml.Name `xml:"ge"`
	FilterProperty
}

FilterGe represents a Greater Than Or Equal To Filter.

type FilterGt

type FilterGt struct {
	XMLName xml.Name `xml:"gt"`
	FilterProperty
}

FilterGt represents a Greater Than Filter.

type FilterLe

type FilterLe struct {
	XMLName xml.Name `xml:"le"`
	FilterProperty
}

FilterLe represents a Less Than Or Equal To Filter.

type FilterLt

type FilterLt struct {
	XMLName xml.Name `xml:"lt"`
	FilterProperty
}

FilterLt represents a Less Than Filter.

type FilterNe

type FilterNe struct {
	XMLName xml.Name `xml:"ne"`
	FilterProperty
}

FilterNe represents a Not Equal Filter.

type FilterNot

type FilterNot struct {
	XMLName xml.Name `xml:"not"`
	Filters []FilterAny
}

FilterNot represents a NOT Modifier Filter.

type FilterOr

type FilterOr struct {
	XMLName xml.Name `xml:"or"`
	Filters []FilterAny
}

FilterOr represents a composite OR Filter.

type FilterProperty

type FilterProperty struct {
	Class    string `xml:"class,attr"`
	Property string `xml:"property,attr"`
	Value    string `xml:"value,attr"`
}

FilterProperty represents a Property Filter.

type FilterWildcard

type FilterWildcard struct {
	XMLName xml.Name `xml:"wcard"`
	FilterProperty
}

FilterWildcard represents a Wildcard Filter. The wildcard filter uses standard regular expression syntax.

type Id

type Id struct {
	XMLName xml.Name `xml:"Id"`
	Value   string   `xml:"value,attr"`
}

Id represents an ID of a class.

func NewId

func NewId(value string) Id

NewId creates a new class id.

type InnerXml

type InnerXml struct {
	XMLName xml.Name
	Inner   []byte `xml:",innerxml"`
}

InnerXml represents a generic configuration retrieved by the various query methods. After a successful result from a query method a client should unmarshal the data contained within an InnerXml to the specific managed object.

type RateLimit

type RateLimit struct {
	// RequestsPerSecond defines the allowed number of requests per second.
	RequestsPerSecond float64

	// Burst is the maximum burst size.
	Burst int

	// Wait defines the maximum time a request will wait for a token to be consumed.
	Wait time.Duration
}

RateLimit limits the number of requests per second that a Client can send to a remote Cisco UCS API endpoint using a rate.Limiter token bucket configured with the provided requests per seconds and burst. A request will wait for up to the given wait time.