README
¶
Controller Go SDK
This is the Go SDK for interacting with the Deis Controller.
Usage
import deis "github.com/deis/controller-sdk-go"
import "github.com/deis/controller-sdk-go/apps"
Construct a deis client to interact with the controller API. Then, get the first 100 apps the user has access to.
// Verify SSL, Controller URL, API Token
client, err := deis.New(true, "deis.test.io", "abc123")
if err != nil {
log.Fatal(err)
}
apps, _, err := apps.List(client, 100)
if err != nil {
log.Fatal(err)
}
Authentication
import deis "github.com/deis/controller-sdk-go"
import "github.com/deis/controller-sdk-go/auth"
If you don't already have a token for a user, you can retrieve one with a username and password.
// Create a client with a blank token to pass to login.
client, err := deis.New(true, "deis.test.io", "")
if err != nil {
log.Fatal(err)
}
token, err := auth.Login(client, "user", "password")
if err != nil {
log.Fatal(err)
}
// Set the client to use the retrieved token
client.Token = token
For a complete usage guide to the SDK, see full package documentation.
Documentation
¶
Overview ¶
Package deis offers a SDK for interacting with the Deis controller API.
This package works by creating a client, which contains session information, such as the controller url and user token. The client is then passed to api methods, which use it to make requests.
Basic Example ¶
This example creates a client and then lists the apps that the user has access to:
import (
deis "github.com/deis/controller-sdk-go"
"github.com/deis/controller-sdk-go/apps"
)
// Verify SSL, Controller URL, API Token
client, err := deis.New(true, "deis.test.io", "abc123")
if err != nil {
log.Fatal(err)
}
apps, _, err := apps.List(client, 100)
if err != nil {
log.Fatal(err)
}
Authentication ¶
If you don't already have a token for a user, you can retrieve one with a username and password.
import (
deis "github.com/deis/controller-sdk-go"
"github.com/deis/controller-sdk-go/apps"
)
// Create a client with a blank token to pass to login.
client, err := deis.New(true, "deis.test.io", "")
if err != nil {
log.Fatal(err)
}
token, err := auth.Login(client, "user", "password")
if err != nil {
log.Fatal(err)
}
// Set the client to use the retrieved token
client.Token = token
Learning More ¶
See the godoc for the SDK's subpackages to learn more about specific SDK actions.
Index ¶
Constants ¶
const APIVersion = "2.1"
APIVersion is the api version compatible with the SDK.
In general, using an SDK that is a minor version out of date with the target controller is probably safe, as the deis controller api follows semantic versioning and is backward compatible. However, using a SDK that is newer or a major version different than the controller is unsafe.
If the SDK detects an API version mismatch, it will return ErrAPIMismatch.
Variables ¶
var ( // ErrAPIMismatch occurs when the sdk is using a different api version than the deis. ErrAPIMismatch = errors.New("API Version Mismatch between server and deis") // DefaultUserAgent is used as the default user agent when making requests. DefaultUserAgent = fmt.Sprintf("Deis Go SDK V%s", APIVersion) )
var ( // ErrNotFound is returned when the server returns a 404. ErrNotFound = errors.New("Not Found") // ErrServerError is returned when the server returns a 500. ErrServerError = errors.New("Internal Server Error") // ErrMethodNotAllowed is thrown when using a unsupposrted method. // This should not come up unless there in an bug in the SDK. ErrMethodNotAllowed = errors.New("Method Not Allowed") // ErrInvalidUsername is returned when the user specifies an invalid or missing username. ErrInvalidUsername = errors.New(invalidUserMsg) // ErrDuplicateUsername is returned when trying to register a user that already exists. ErrDuplicateUsername = errors.New(duplicateUserMsg) // ErrMissingPassword is returned when a password is not sent with the request. ErrMissingPassword = errors.New("A Password is required") // ErrLogin is returned when the api cannot login fails with provided username and password ErrLogin = errors.New(failedLoginMsg) ErrUnauthorized = errors.New("Unauthorized: Missing or Invalid Token") // ErrInvalidAppName is returned when the user specifies an invalid app name. ErrInvalidAppName = errors.New(invalidAppNameMsg) // ErrConflict is returned when the API returns a 409. ErrConflict = errors.New("This action could not be completed due to a conflict.") // ErrForbidden is returned when the API returns a 403. ErrForbidden = errors.New("You do not have permission to perform this action.") // ErrMissingKey is returned when a key is not sent with the request. ErrMissingKey = errors.New("A key is required") // ErrInvalidName is returned when a name is invalid or missing. ErrInvalidName = errors.New(invalidNameMsg) // ErrInvalidCertificate is returned when a certififate is missing or invalid ErrInvalidCertificate = errors.New(invalidCertMsg) // ErrPodNotFound is returned when a pod type is not Found ErrPodNotFound = errors.New("Pod not found in application") // ErrInvalidDomain is returned when a domain is missing or invalid ErrInvalidDomain = errors.New(invalidDomainMsg) // ErrInvalidImage is returned when a image is missing or invalid ErrInvalidImage = errors.New("The given image is invalid") // ErrInvalidVersion is returned when a version is invalid ErrInvalidVersion = errors.New("The given version is invalid") // ErrMissingID is returned when a ID is missing ErrMissingID = errors.New("An id is required") // ErrInvalidEmail is returned when a user gives an invalid email. ErrInvalidEmail = errors.New(invalidEmailMsg) // ErrTagNotFound is returned when no node can be found that matches the tag ErrTagNotFound = errors.New(invalidTagMsg) // ErrDuplicateApp is returned when create an app with an ID that already exists ErrDuplicateApp = errors.New(duplicateIDMsg) // ErrUnprocessable is returned when the controller throws a 422. ErrUnprocessable = errors.New("Unable to process your request.") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// HTTPClient is the transport that is used to communicate with the API.
HTTPClient *http.Client
// VerifySSL determines whether or not to verify SSL connections.
// This should be true unless you know the controller is using untrusted SSL keys.
VerifySSL bool
// ControllerURL is the URL used to communicate with the controller.
ControllerURL *url.URL
// UserAgent is the user agent used when making requests.
UserAgent string
// API Version used by the controller, set after a http request.
ControllerAPIVersion string
// Token is used to authenticate the request against the API.
Token string
}
Client oversees the interaction between the deis and controller
func New ¶
New creates a new client to communicate with the api. The controllerURL is the url of the controller component, by default deis.<cluster url>.com verifySSL determines whether or not to verify SSL connections. This should be true unless you know the controller is using untrusted SSL keys.
func (*Client) CheckConnection ¶
CheckConnection checks that the user is connected to a network and the URL points to a valid controller.
func (*Client) LimitedRequest ¶
LimitedRequest allows limiting the number of responses in a request.
func (*Client) Request ¶
Request makes a HTTP request with the given method, relative URL, and body on the controller. It also sets the Authorization and Content-Type headers to properly authenticate and communicate API. This is primarily intended to use be used by the SDK itself, but could potentially be used elsewhere.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apps provides methods for managing deis apps.
|
Package apps provides methods for managing deis apps. |
|
Package auth handles user management: creation, deletion, and authentication.
|
Package auth handles user management: creation, deletion, and authentication. |
|
Package builds provides methods for managing app builds.
|
Package builds provides methods for managing app builds. |
|
Package config provides methods for managing configuration of apps.
|
Package config provides methods for managing configuration of apps. |
|
Package domains provides methods for managing an app's domains.
|
Package domains provides methods for managing an app's domains. |
|
Package keys provides methods for managing a user's ssh keys.
|
Package keys provides methods for managing a user's ssh keys. |
|
Package perms provides methods for managing user app and administrative permissions.
|
Package perms provides methods for managing user app and administrative permissions. |
|
pkg
|
|
|
Package ps provides methods for managing app processes.
|
Package ps provides methods for managing app processes. |