ccv3

package
v6.32.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 26, 2017 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package ccv3 represents a Cloud Controller V3 client.

These sets of packages are still under development/pre-pre-pre...alpha. Use at your own risk! Functionality and design may change without warning.

It is currently designed to support Cloud Controller API 3.0.0. However, it may include features and endpoints of later API versions.

For more information on the Cloud Controller API see https://apidocs.cloudfoundry.org/

Method Naming Conventions

The client takes a '<Action Name><Top Level Endpoint><Return Value>' approach to method names. If the <Top Level Endpoint> and <Return Value> are similar, they do not need to be repeated. If a GUID is required for the <Top Level Endpoint>, the pluralization is removed from said endpoint in the method name.

For Example:

Method Name: GetApplication
Endpoint: /v3/applications/:guid
Action Name: Get
Top Level Endpoint: applications
Return Value: Application

Method Name: GetServiceInstances
Endpoint: /v3/service_instances
Action Name: Get
Top Level Endpoint: service_instances
Return Value: []ServiceInstance

Method Name: GetSpaceServiceInstances
Endpoint: /v3/spaces/:guid/service_instances
Action Name: Get
Top Level Endpoint: spaces
Return Value: []ServiceInstance

Method Name: CreateApplicationTask
Endpoint: /v3/apps/:application_guid/task
Action Name: Post
Top Level Endpoint: apps
Return Value: []Task

Use the following table to determine which HTTP Command equates to which Action Name:

HTTP Command -> Action Name
POST -> Create
GET -> Get
PUT -> Update
DELETE -> Delete
PATCH -> Patch

Method Locations

Methods exist in the same file as their return type, regardless of which endpoint they use.

Error Handling

All error handling that requires parsing the error_code/code returned back from the Cloud Controller should be placed in the errorWrapper. Everything else can be handled in the individual operations. All parsed cloud controller errors should exist in errors.go, all generic HTTP errors should exist in the cloudcontroller's errors.go. Errors related to the individaul operation should exist at the top of that operation's file.

Index

Constants

View Source
const (
	// GUIDFilter is a query paramater for listing objects by GUID.
	GUIDFilter = "guids"
	// NameFilter is a query paramater for listing objects by name.
	NameFilter = "names"
	// AppGUIDFilter is a query paramater for listing objects by app GUID.
	AppGUIDFilter = "app_guids"
	// OrganizationGUIDFilter is a query paramater for listing objects by Organization GUID.
	OrganizationGUIDFilter = "organization_guids"
	// SpaceGUIDFilter is a query paramater for listing objects by Space GUID.
	SpaceGUIDFilter = "space_guids"

	// OrderBy is a query paramater to specify how to order objects.
	OrderBy = "order_by"
	// NameOrder is value for a query paramater when ordering by name.
	NameOrder = "name"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIInfo

type APIInfo struct {
	// Links is a list of top level Cloud Controller APIs.
	Links struct {
		// CCV3 is the link to the Cloud Controller V3 API
		CCV3 APILink `json:"cloud_controller_v3"`

		// Logging is the link to the Logging API
		Logging APILink `json:"logging"`

		NetworkPolicyV1 APILink `json:"network_policy_v1"`

		// UAA is the link to the UAA API
		UAA APILink `json:"uaa"`
	} `json:"links"`
}

APIInfo represents a GET response from the '/' endpoint of the cloud controller API.

func (APIInfo) CloudControllerAPIVersion

func (info APIInfo) CloudControllerAPIVersion() string

CloudControllerAPIVersion returns the version for the CloudController.

func (APIInfo) Logging

func (info APIInfo) Logging() string

Logging returns the HREF for Logging.

func (APIInfo) NetworkPolicyV1

func (info APIInfo) NetworkPolicyV1() string

func (APIInfo) UAA

func (info APIInfo) UAA() string

UAA returns the HREF for the UAA.

type APILink struct {
	// HREF is the fully qualified URL for the link.
	HREF   string `json:"href"`
	Method string `json:"method"`

	// Meta contains additional metadata about the API.
	Meta struct {
		// Version of the API
		Version string `json:"version"`
	} `json:"meta"`
}

APILink represents a generic link from a response object.

type APILinks map[string]APILink

APILinks is a directory of follow-up urls for the resource.

type AppLifecycle

type AppLifecycle struct {
	Type AppLifecycleType `json:"type,omitempty"`
	Data AppLifecycleData `json:"data,omitempty"`
}

type AppLifecycleData

type AppLifecycleData struct {
	Buildpacks []string `json:"buildpacks,omitempty"`
}

type AppLifecycleType

type AppLifecycleType string
const (
	BuildpackAppLifecycleType AppLifecycleType = "buildpack"
	DockerAppLifecycleType    AppLifecycleType = "docker"
)

type Application

type Application struct {
	Name          string        `json:"name,omitempty"`
	Relationships Relationships `json:"relationships,omitempty"`
	GUID          string        `json:"guid,omitempty"`
	State         string        `json:"state,omitempty"`
	Lifecycle     AppLifecycle  `json:"lifecycle,omitempty"`
}

Application represents a Cloud Controller V3 Application.

func (Application) MarshalJSON

func (a Application) MarshalJSON() ([]byte, error)

type Build

type Build struct {
	CreatedAt   string
	GUID        string
	Error       string
	PackageGUID string
	State       BuildState
	DropletGUID string
}

func (Build) MarshalJSON

func (b Build) MarshalJSON() ([]byte, error)

func (*Build) UnmarshalJSON

func (b *Build) UnmarshalJSON(data []byte) error

type BuildState

type BuildState string
const (
	BuildStateFailed  BuildState = "FAILED"
	BuildStateStaged  BuildState = "STAGED"
	BuildStateStaging BuildState = "STAGING"
)

type Client

type Client struct {
	APIInfo
	// contains filtered or unexported fields
}

Client can be used to talk to a Cloud Controller's V3 Endpoints.

func NewClient

func NewClient(config Config) *Client

NewClient returns a new Client.

func (*Client) AssignSpaceToIsolationSegment

func (client *Client) AssignSpaceToIsolationSegment(spaceGUID string, isolationSegmentGUID string) (Relationship, Warnings, error)

AssignSpaceToIsolationSegment assigns an isolation segment to a space and returns the relationship.

func (*Client) CreateApplication

func (client *Client) CreateApplication(app Application) (Application, Warnings, error)

CreateApplication creates an application with the given settings

func (*Client) CreateApplicationProcessScale

func (client *Client) CreateApplicationProcessScale(appGUID string, process Process) (Warnings, error)

CreateApplicationProcessScale updates process instances count, memory or disk

func (*Client) CreateApplicationTask

func (client *Client) CreateApplicationTask(appGUID string, task Task) (Task, Warnings, error)

CreateApplicationTask runs a command in the Application environment associated with the provided Application GUID.

func (*Client) CreateBuild

func (client *Client) CreateBuild(build Build) (Build, Warnings, error)

CreateBuild creates the given build, requires Package GUID to be set on the build.

func (*Client) CreateIsolationSegment

func (client *Client) CreateIsolationSegment(isolationSegment IsolationSegment) (IsolationSegment, Warnings, error)

CreateIsolationSegment will create an Isolation Segment on the Cloud Controller. Note: This will not validate that the placement tag exists in the diego cluster.

func (*Client) CreatePackage

func (client *Client) CreatePackage(pkg Package) (Package, Warnings, error)

CreatePackage creates a package with the given settings, Type and the ApplicationRelationship must be set.

func (*Client) DeleteApplication

func (client *Client) DeleteApplication(appGUID string) (string, Warnings, error)

func (*Client) DeleteApplicationProcessInstance

func (client *Client) DeleteApplicationProcessInstance(appGUID string, processType string, instanceIndex int) (Warnings, error)

func (*Client) DeleteIsolationSegment

func (client *Client) DeleteIsolationSegment(guid string) (Warnings, error)

DeleteIsolationSegment removes an isolation segment from the cloud controller. Note: This will only remove it from the cloud controller database. It will not remove it from diego.

func (*Client) EntitleIsolationSegmentToOrganizations

func (client *Client) EntitleIsolationSegmentToOrganizations(isolationSegmentGUID string, organizationGUIDs []string) (RelationshipList, Warnings, error)

EntitleIsolationSegmentToOrganizations will create a link between the isolation segment and the list of organizations provided.

func (*Client) GetApplicationDroplets

func (client *Client) GetApplicationDroplets(appGUID string, query url.Values) ([]Droplet, Warnings, error)

GetApplicationDroplets returns the Droplets for a given app

func (*Client) GetApplicationEnvironmentVariables

func (client *Client) GetApplicationEnvironmentVariables(appGUID string) (EnvironmentVariableGroups, Warnings, error)

GetApplicationEnvironmentVariables fetches all the environment variables on an application by groups.

func (*Client) GetApplicationProcessByType

func (client *Client) GetApplicationProcessByType(appGUID string, processType string) (Process, Warnings, error)

GetApplicationProcessByType returns application process of specified type

func (*Client) GetApplicationProcesses

func (client *Client) GetApplicationProcesses(appGUID string) ([]Process, Warnings, error)

GetApplicationProcesses lists processes for a given app

func (*Client) GetApplicationTasks

func (client *Client) GetApplicationTasks(appGUID string, query url.Values) ([]Task, Warnings, error)

GetApplicationTasks returns a list of tasks associated with the provided application GUID. Results can be filtered by providing URL queries.

func (*Client) GetApplications

func (client *Client) GetApplications(query url.Values) ([]Application, Warnings, error)

GetApplications lists applications with optional filters.

func (*Client) GetBuild

func (client *Client) GetBuild(guid string) (Build, Warnings, error)

GetBuild gets the build with the given GUID.

func (*Client) GetDroplet

func (client *Client) GetDroplet(dropletGUID string) (Droplet, Warnings, error)

func (*Client) GetIsolationSegment

func (client *Client) GetIsolationSegment(guid string) (IsolationSegment, Warnings, error)

GetIsolationSegment returns back the requested isolation segment that matches the GUID.

func (*Client) GetIsolationSegmentOrganizationsByIsolationSegment

func (client *Client) GetIsolationSegmentOrganizationsByIsolationSegment(isolationSegmentGUID string) ([]Organization, Warnings, error)

GetIsolationSegmentOrganizationsByIsolationSegment lists organizations entitled to an isolation segment

func (*Client) GetIsolationSegments

func (client *Client) GetIsolationSegments(query url.Values) ([]IsolationSegment, Warnings, error)

GetIsolationSegments lists isolation segments with optional filters.

func (*Client) GetJob

func (client *Client) GetJob(jobURL string) (Job, Warnings, error)

GetJob returns a job for the provided GUID.

func (*Client) GetOrganizationDefaultIsolationSegment

func (client *Client) GetOrganizationDefaultIsolationSegment(orgGUID string) (Relationship, Warnings, error)

GetOrganizationDefaultIsolationSegment returns the relationship between an organization and it's default isolation segment.

func (*Client) GetOrganizations

func (client *Client) GetOrganizations(query url.Values) ([]Organization, Warnings, error)

GetOrganizations lists organizations with optional filters.

func (*Client) GetPackage

func (client *Client) GetPackage(packageGUID string) (Package, Warnings, error)

GetPackage returns the package with the given GUID.

func (*Client) GetPackages

func (client *Client) GetPackages(query url.Values) ([]Package, Warnings, error)

GetPackages returns the list of packages.

func (*Client) GetProcessInstances

func (client *Client) GetProcessInstances(processGUID string) ([]Instance, Warnings, error)

GetProcessInstances lists instance stats for a given process.

func (*Client) GetSpaceIsolationSegment

func (client *Client) GetSpaceIsolationSegment(spaceGUID string) (Relationship, Warnings, error)

GetSpaceIsolationSegment returns the relationship between a space and it's isolation segment.

func (*Client) GetSpaces

func (client *Client) GetSpaces(query url.Values) ([]Space, Warnings, error)

GetSpaces lists spaces with optional filters.

func (*Client) Info

func (client *Client) Info() (APIInfo, ResourceLinks, Warnings, error)

Info returns endpoint and API information from /v3.

func (*Client) PatchApplicationProcessHealthCheck

func (client *Client) PatchApplicationProcessHealthCheck(processGUID string, processHealthCheckType string, processHealthCheckEndpoint string) (Warnings, error)

PatchApplicationProcessHealthCheck updates application health check type

func (*Client) PatchApplicationUserProvidedEnvironmentVariables

func (client *Client) PatchApplicationUserProvidedEnvironmentVariables(appGUID string, envVars EnvironmentVariables) (EnvironmentVariables, Warnings, error)

PatchApplicationUserProvidedEnvironmentVariables updates the user provided environment variables on an applicaiton. A restart is required for changes to take effect.

func (*Client) PatchOrganizationDefaultIsolationSegment

func (client *Client) PatchOrganizationDefaultIsolationSegment(orgGUID string, isoSegGUID string) (Warnings, error)

PatchOrganizationDefaultIsolationSegment sets the default isolation segment for an organization on the controller. If isoSegGuid is empty it will reset the default isolation segment.

func (*Client) PollJob

func (client *Client) PollJob(jobURL string) (Warnings, error)

PollJob will keep polling the given job until the job has terminated, an error is encountered, or config.OverallPollingTimeout is reached. In the last case, a JobTimeoutError is returned.

func (*Client) RevokeIsolationSegmentFromOrganization

func (client *Client) RevokeIsolationSegmentFromOrganization(isolationSegmentGUID string, orgGUID string) (Warnings, error)

RevokeIsolationSegmentFromOrganization will delete the relationship between the isolation segment and the organization provided.

func (*Client) SetApplicationDroplet

func (client *Client) SetApplicationDroplet(appGUID string, dropletGUID string) (Relationship, Warnings, error)

func (*Client) StartApplication

func (client *Client) StartApplication(appGUID string) (Application, Warnings, error)

func (*Client) StopApplication

func (client *Client) StopApplication(appGUID string) (Warnings, error)

func (*Client) TargetCF

func (client *Client) TargetCF(settings TargetSettings) (Warnings, error)

TargetCF sets the client to use the Cloud Controller specified in the configuration. Any other configuration is also applied to the client.

func (*Client) UpdateApplication

func (client *Client) UpdateApplication(app Application) (Application, Warnings, error)

UpdateApplication updates an application with the given settings

func (*Client) UpdateTask

func (client *Client) UpdateTask(taskGUID string) (Task, Warnings, error)

UpdateTask cancels a task.

func (*Client) UploadPackage

func (client *Client) UploadPackage(pkg Package, fileToUpload string) (Package, Warnings, error)

UploadPackage uploads a file to a given package's Upload resource. Note: fileToUpload is read entirely into memory prior to sending data to CC.

func (*Client) WrapConnection

func (client *Client) WrapConnection(wrapper ConnectionWrapper)

WrapConnection wraps the current Client connection in the wrapper.

type Config

type Config struct {
	// AppName is the name of the application/process using the client.
	AppName string

	// AppVersion is the version of the application/process using the client.
	AppVersion string

	// JobPollingTimeout is the maximum amount of time a job polls for.
	JobPollingTimeout time.Duration

	// JobPollingInterval is the wait time between job polls.
	JobPollingInterval time.Duration

	// Wrappers that apply to the client connection.
	Wrappers []ConnectionWrapper
}

Config allows the Client to be configured

type ConnectionWrapper

type ConnectionWrapper interface {
	cloudcontroller.Connection
	Wrap(innerconnection cloudcontroller.Connection) cloudcontroller.Connection
}

ConnectionWrapper can wrap a given connection allowing the wrapper to modify all requests going in and out of the given connection.

type Droplet

type Droplet struct {
	GUID       string             `json:"guid"`
	State      DropletState       `json:"state"`
	CreatedAt  string             `json:"created_at"`
	Stack      string             `json:"stack,omitempty"`
	Buildpacks []DropletBuildpack `json:"buildpacks,omitempty"`
	Image      string             `json:"image"`
}

type DropletBuildpack

type DropletBuildpack struct {
	Name         string `json:"name"`
	DetectOutput string `json:"detect_output"`
}

type DropletRelationship

type DropletRelationship struct {
	Relationship Relationship `json:"data"`
	Links        APILinks     `json:"links"`
}

DropletRelationship represents the relationship between a V3 Droplet and its V3 Application

type DropletState

type DropletState string
const (
	DropletStateStaged  DropletState = "STAGED"
	DropletStateFailed  DropletState = "FAILED"
	DropletStateCopying DropletState = "COPYING"
	DropletStateExpired DropletState = "EXPIRED"
)

type EnvironmentVariableGroups

type EnvironmentVariableGroups struct {
	SystemProvided      map[string]interface{} `json:"system_env_json"`
	ApplicationProvided map[string]interface{} `json:"application_env_json"`
	UserProvided        map[string]interface{} `json:"environment_variables"`
	RunningGroup        map[string]interface{} `json:"running_env_json"`
	StagingGroup        map[string]interface{} `json:"staging_env_json"`
}

EnvironmentVariableGroups represents all environment variables on an application

type EnvironmentVariables

type EnvironmentVariables struct {
	Variables map[string]types.FilteredString `json:"var"`
}

EnvironmentVariables represents the environment variables that can be set on application by user

type ErrorDetails

type ErrorDetails struct {
	Detail string `json:"detail"`
	Title  string `json:"title"`
	Code   int    `json:"code"`
}

type Instance

type Instance struct {
	Index       int
	State       string
	Uptime      int
	CPU         float64
	MemoryUsage uint64
	MemoryQuota uint64
	DiskUsage   uint64
	DiskQuota   uint64
}

func (*Instance) UnmarshalJSON

func (instance *Instance) UnmarshalJSON(data []byte) error

UnmarshalJSON helps unmarshal a V3 Cloud Controller Instance response.

type IsolationSegment

type IsolationSegment struct {
	Name string `json:"name"`
	GUID string `json:"guid,omitempty"`
}

IsolationSegment represents a Cloud Controller Isolation Segment.

type Job

type Job struct {
	Errors []ErrorDetails `json:"errors"`
	GUID   string         `json:"guid"`
	State  JobState       `json:"state"`
}

Job represents a Cloud Controller Job.

func (Job) Complete

func (job Job) Complete() bool

Complete returns true when the job has completed successfully.

func (Job) Failed

func (job Job) Failed() bool

Failed returns true when the job has completed with an error/failure.

type JobState

type JobState string

JobState is the current state of a job.

const (
	// JobStateFailed is when the job is no longer running due to a failure.
	JobStateFailed JobState = "FAILED"

	// JobStateFinished is when the job is no longer and it was successful.
	JobStateComplete JobState = "COMPLETE"

	// JobStateQueued is when the job is waiting to be run.
	JobStateProcessing JobState = "PROCESSING"
)

type Organization

type Organization struct {
	Name string `json:"name"`
	GUID string `json:"guid"`
}

Organization represents a Cloud Controller V3 Organization.

type Package

type Package struct {
	GUID           string
	CreatedAt      string
	Links          APILinks
	Relationships  Relationships
	State          PackageState
	Type           PackageType
	DockerImage    string
	DockerUsername string
	DockerPassword string
}

func (Package) MarshalJSON

func (p Package) MarshalJSON() ([]byte, error)

func (*Package) UnmarshalJSON

func (p *Package) UnmarshalJSON(data []byte) error

type PackageState

type PackageState string
const (
	PackageStateProcessingUpload PackageState = "PROCESSING_UPLOAD"
	PackageStateReady            PackageState = "READY"
	PackageStateFailed           PackageState = "FAILED"
	PackageStateAwaitingUpload   PackageState = "AWAITING_UPLOAD"
	PackageStateCopying          PackageState = "COPYING"
	PackageStateExpired          PackageState = "EXPIRED"
)

type PackageType

type PackageType string
const (
	PackageTypeBits   PackageType = "bits"
	PackageTypeDocker PackageType = "docker"
)

type PaginatedResources

type PaginatedResources struct {
	Pagination struct {
		Next struct {
			HREF string `json:"href"`
		} `json:"next"`
	} `json:"pagination"`
	ResourcesBytes json.RawMessage `json:"resources"`
	// contains filtered or unexported fields
}

PaginatedResources represents a page of resources returned by the Cloud Controller.

func NewPaginatedResources

func NewPaginatedResources(exampleResource interface{}) *PaginatedResources

NewPaginatedResources returns a new PaginatedResources struct with the given resource type.

func (PaginatedResources) NextPage

func (pr PaginatedResources) NextPage() string

NextPage returns the HREF of the next page of results.

func (PaginatedResources) Resources

func (pr PaginatedResources) Resources() ([]interface{}, error)

Resources unmarshals JSON representing a page of resources and returns a slice of the given resource type.

type Process

type Process struct {
	GUID        string             `json:"guid"`
	Type        string             `json:"type"`
	HealthCheck ProcessHealthCheck `json:"health_check"`
	Instances   types.NullInt      `json:"instances"`
	MemoryInMB  types.NullUint64   `json:"memory_in_mb"`
	DiskInMB    types.NullUint64   `json:"disk_in_mb"`
}

func (Process) MarshalJSON

func (p Process) MarshalJSON() ([]byte, error)

type ProcessHealthCheck

type ProcessHealthCheck struct {
	Type string                 `json:"type"`
	Data ProcessHealthCheckData `json:"data"`
}

type ProcessHealthCheckData

type ProcessHealthCheckData struct {
	Endpoint string `json:"endpoint"`
}

type Relationship

type Relationship struct {
	GUID string
}

Relationship represents a one to one relationship. An empty GUID will be marshaled as `null`.

func (Relationship) MarshalJSON

func (r Relationship) MarshalJSON() ([]byte, error)

func (*Relationship) UnmarshalJSON

func (r *Relationship) UnmarshalJSON(data []byte) error

type RelationshipList

type RelationshipList struct {
	GUIDs []string
}

RelationshipList represents a one to many relationship.

func (RelationshipList) MarshalJSON

func (r RelationshipList) MarshalJSON() ([]byte, error)

func (*RelationshipList) UnmarshalJSON

func (r *RelationshipList) UnmarshalJSON(data []byte) error

type RelationshipType

type RelationshipType string
const (
	ApplicationRelationship RelationshipType = "app"
	SpaceRelationship       RelationshipType = "space"
)

type Relationships

type Relationships map[RelationshipType]Relationship

Relationships is a map of RelationshipTypes to Relationship.

type ResourceLinks map[string]APILink

ResourceLinks represents the information returned back from /v3.

func (ResourceLinks) UnmarshalJSON

func (resources ResourceLinks) UnmarshalJSON(data []byte) error

UnmarshalJSON helps unmarshal a Cloud Controller /v3 response.

type Space

type Space struct {
	Name string `json:"name"`
	GUID string `json:"guid"`
}

Space represents a Cloud Controller V3 Space.

type TargetSettings

type TargetSettings struct {
	// DialTimeout is the DNS timeout used to make all requests to the Cloud
	// Controller.
	DialTimeout time.Duration

	// SkipSSLValidation controls whether a client verifies the server's
	// certificate chain and host name. If SkipSSLValidation is true, TLS accepts
	// any certificate presented by the server and any host name in that
	// certificate for *all* client requests going forward.
	//
	// In this mode, TLS is susceptible to man-in-the-middle attacks. This should
	// be used only for testing.
	SkipSSLValidation bool

	// URL is a fully qualified URL to the Cloud Controller API.
	URL string
}

TargetSettings represents configuration for establishing a connection to the Cloud Controller server.

type Task

type Task struct {
	GUID       string `json:"guid,omitempty"`
	SequenceID int    `json:"sequence_id,omitempty"`
	Name       string `json:"name,omitempty"`
	Command    string `json:"command"`
	State      string `json:"state,omitempty"`
	CreatedAt  string `json:"created_at,omitempty"`
	MemoryInMB uint64 `json:"memory_in_mb,omitempty"`
	DiskInMB   uint64 `json:"disk_in_mb,omitempty"`
}

Task represents a Cloud Controller V3 Task.

type Warnings

type Warnings []string

Warnings are a collection of warnings that the Cloud Controller can return back from an API request.

Directories

Path Synopsis
Code generated by counterfeiter.
Code generated by counterfeiter.
Package constant contains types and constants used by the ccv3 package.
Package constant contains types and constants used by the ccv3 package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL