deis

README

	Deis Workflow is no longer maintained. Please read the announcement for more detail.
09/07/2017	Deis Workflow v2.18 final release before entering maintenance mode
03/01/2018	End of Workflow maintenance: critical patches no longer merged
	Hephy is a fork of Workflow that is actively developed and accepts code contributions.

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
• Variables
• func IsErrAPIMismatch(err error) bool
• type Client
  • func New(verifySSL bool, controllerURL string, token string) (*Client, error)
  • func (c *Client) CheckConnection() error
  • func (c *Client) Healthcheck() error
  • func (c *Client) LimitedRequest(path string, results int) (string, int, error)
  • func (c *Client) Request(method string, path string, body []byte) (*http.Response, error)
• type ErrNotFound
  • func (e ErrNotFound) Error() string
• type ErrUnprocessable
  • func (e ErrUnprocessable) Error() string

Constants

const APIVersion = "2.3"

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 (
	// 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 is given when the API returns a 401.
	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")
	// ErrDuplicateKey is returned when adding a key that already exists.
	ErrDuplicateKey = errors.New(duplicateKeyMsg)
	// ErrInvalidName is returned when a name is invalid or missing.
	ErrInvalidName = errors.New(fmt.Sprintf("Name %s", strings.ToLower(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)
	// ErrDuplicateDomain is returned adding domain that is already in use
	ErrDuplicateDomain = errors.New(duplicateDomainMsg)
	// 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)
	// ErrCancellationFailed is returned when cancelling a user fails.
	ErrCancellationFailed = errors.New("Failed to delete user because the user still has applications assigned. Delete or transfer ownership.")
)

Functions

func IsErrAPIMismatch

func IsErrAPIMismatch(err error) bool

IsErrAPIMismatch returns true if err is an ErrAPIMismatch, false otherwise

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

	// Version of the deis controller in use, set after a http request.
	ControllerVersion string

	// Token is used to authenticate the request against the API.
	Token string

	// HooksToken is the controller token used with the hooks resource.
	// The hooks resource isn't intended to be used by users, so it requires
	// a service token rather than a user token.
	HooksToken string
}

Client oversees the interaction between the deis and controller

func New

func New(verifySSL bool, controllerURL string, token string) (*Client, error)

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

func (c *Client) CheckConnection() error

CheckConnection checks that the user is connected to a network and the URL points to a valid controller.

func (*Client) Healthcheck

func (c *Client) Healthcheck() error

Healthcheck can be called to see if the controller is healthy

func (*Client) LimitedRequest

func (c *Client) LimitedRequest(path string, results int) (string, int, error)

LimitedRequest allows limiting the number of responses in a request.

func (*Client) Request

func (c *Client) Request(method string, path string, body []byte) (*http.Response, error)

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.

type ErrNotFound

type ErrNotFound struct {
	// contains filtered or unexported fields
}

ErrNotFound is returned when the controller throws a 404.

func (ErrNotFound) Error

func (e ErrNotFound) Error() string

type ErrUnprocessable

type ErrUnprocessable struct {
	// contains filtered or unexported fields
}

ErrUnprocessable is returned when the controller throws a 422.

func (ErrUnprocessable) Error

func (e ErrUnprocessable) Error() string