api

package
v0.0.0-...-b0bff92 Latest Latest
Warning

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

 Go to latest Published: Dec 7, 2021 License: AGPL-3.0 Imports: 66 Imported by: 0

Documentation

Index

Constants

View Source 
const AnonymousUsername = "jujuanonymous"

AnonymousUsername is the special username to use for anonymous logins.

View Source 
const PingPeriod = 1 * time.Minute

PingPeriod defines how often the internal connection health check will run.

Variables

This section is empty.

Functions

func AuthHTTPRequest 

func AuthHTTPRequest(req *http.Request, info *Info) error

AuthHTTPRequest adds Juju auth info (username, password, nonce, macaroons) to the given HTTP request, suitable for sending to a Juju API server.

func ControllerAPIURL 

func ControllerAPIURL(addr string, port int) string

ControllerAPIURL returns the URL to use to connect to the controller API.

func CreateCertPool 

func CreateCertPool(caCert string) (*x509.CertPool, error)

CreateCertPool creates a new x509.CertPool and adds in the caCert passed in. All certs from the cert directory (/etc/juju/cert.d on ubuntu) are also added.

func NewCharmDownloader 

func NewCharmDownloader(apiCaller base.APICaller) *downloader.Downloader

NewCharmDownloader returns a new charm downloader that wraps the provided API caller.

func NewTLSConfig 

func NewTLSConfig(certPool *x509.CertPool) *tls.Config

NewTLSConfig returns a new *tls.Config suitable for connecting to a Juju API server. If certPool is non-nil, we use it as the config's RootCAs, and the server name is set to "acpoc-apiserver".

func OpenCharm 

func OpenCharm(apiCaller base.APICaller, curl *charm.URL) (io.ReadCloser, error)

OpenCharm streams out the identified charm from the controller via the API.

Types

type AllWatch 

type AllWatch interface {
	Next() ([]params.Delta, error)
	Stop() error
}

AllWatch represents methods used on the AllWatcher Primarily to facilitate mock tests.

type AllWatcher 

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

AllWatcher holds information allowing us to get Deltas describing changes to the entire model or all models (depending on the watcher type).

func NewAllModelWatcher 

func NewAllModelWatcher(caller base.APICaller, id *string) *AllWatcher

NewAllModelWatcher returns an AllWatcher instance which interacts with a watcher created by the WatchAllModels API call.

There should be no need to call this from outside of the api package. It is only used by Client.WatchAllModels in api/controller.

func NewAllWatcher 

func NewAllWatcher(caller base.APICaller, id *string) *AllWatcher

NewAllWatcher returns an AllWatcher instance which interacts with a watcher created by the WatchAll API call.

There should be no need to call this from outside of the api package. It is only used by Client.WatchAll in this package.

func (*AllWatcher) Next 

func (watcher *AllWatcher) Next() ([]params.Delta, error)

Next returns a new set of deltas from a watcher previously created by the WatchAll or WatchAllModels API calls. It will block until there are deltas to return.

func (*AllWatcher) Stop 

func (watcher *AllWatcher) Stop() error

Stop shutdowns down a watcher previously created by the WatchAll or WatchAllModels API calls

type Client 

type Client struct {
	base.ClientFacade
	// contains filtered or unexported fields
}

Client represents the client-accessible part of the state.

func (*Client) APIHostPorts 

func (c *Client) APIHostPorts() ([]network.MachineHostPorts, error)

APIHostPorts returns a slice of network.MachineHostPort for each API server.

func (*Client) AbortCurrentUpgrade 

func (c *Client) AbortCurrentUpgrade() error

AbortCurrentUpgrade aborts and archives the current upgrade synchronisation record, if any.

func (*Client) AddCharm 

func (c *Client) AddCharm(curl *charm.URL, channel csparams.Channel, force bool) error

AddCharm adds the given charm URL (which must include revision) to the model, if it does not exist yet. Local charms are not supported, only charm store URLs. See also AddLocalCharm() in the client-side API.

If the AddCharm API call fails because of an authorization error when retrieving the charm from the charm store, an error satisfying params.IsCodeUnauthorized will be returned.

func (*Client) AddCharmWithAuthorization 

func (c *Client) AddCharmWithAuthorization(curl *charm.URL, channel csparams.Channel, csMac *macaroon.Macaroon, force bool) error

AddCharmWithAuthorization is like AddCharm except it also provides the given charmstore macaroon for the juju server to use when obtaining the charm from the charm store. The macaroon is conventionally obtained from the /delegatable-macaroon endpoint in the charm store.

If the AddCharmWithAuthorization API call fails because of an authorization error when retrieving the charm from the charm store, an error satisfying params.IsCodeUnauthorized will be returned. Force is used to overload any validation errors that could occur during a deploy

func (*Client) AddLocalCharm 

func (c *Client) AddLocalCharm(curl *charm.URL, ch charm.Charm, force bool) (*charm.URL, error)

AddLocalCharm prepares the given charm with a local: schema in its URL, and uploads it via the API server, returning the assigned charm URL.

func (*Client) AddMachines 

func (c *Client) AddMachines(machineParams []params.AddMachineParams) ([]params.AddMachinesResult, error)

AddMachines adds new machines with the supplied parameters.

func (*Client) AgentVersion 

func (c *Client) AgentVersion() (version.Number, error)

AgentVersion reports the version number of the api server.

func (*Client) Close 

func (c *Client) Close() error

Close closes the Client's underlying State connection Client is unique among the api.State facades in closing its own State connection, but it is conventional to use a Client object without any access to its underlying state connection.

func (*Client) DestroyMachines 

func (c *Client) DestroyMachines(machines ...string) error

DestroyMachines removes a given set of machines.

NOTE(axw) this exists only for backwards compatibility, when MachineManager facade v3 is not available. The MachineManager.DestroyMachines method should be preferred.

TODO(axw) 2017-03-16 #1673323 Drop this in Juju 3.0.

func (*Client) DestroyMachinesWithParams 

func (c *Client) DestroyMachinesWithParams(force, keep bool, machines ...string) error

DestroyMachinesWithParams removes a given set of machines and all associated units.

NOTE(wallyworld) this exists only for backwards compatibility, when MachineManager facade v4 is not available. The MachineManager.DestroyMachinesWithParams method should be preferred.

TODO(wallyworld) 2017-03-16 #1673323 Drop this in Juju 3.0.

func (*Client) FindTools 

func (c *Client) FindTools(majorVersion, minorVersion int, osType, arch, agentStream string) (result params.FindToolsResult, err error)

FindTools returns a List containing all tools matching the specified parameters.

func (*Client) ForceDestroyMachines 

func (c *Client) ForceDestroyMachines(machines ...string) error

ForceDestroyMachines removes a given set of machines and all associated units.

NOTE(axw) this exists only for backwards compatibility, when MachineManager facade v3 is not available. The MachineManager.ForceDestroyMachines method should be preferred.

TODO(axw) 2017-03-16 #1673323 Drop this in Juju 3.0.

func (*Client) GetModelConstraints 

func (c *Client) GetModelConstraints() (constraints.Value, error)

GetModelConstraints returns the constraints for the model.

func (*Client) ModelUUID 

func (c *Client) ModelUUID() (string, bool)

ModelUUID returns the model UUID from the client connection and reports whether it is valued.

func (*Client) ModelUserInfo 

func (c *Client) ModelUserInfo() ([]params.ModelUserInfo, error)

ModelUserInfo returns information on all users in the model.

func (*Client) OpenCharm 

func (c *Client) OpenCharm(curl *charm.URL) (io.ReadCloser, error)

OpenCharm streams out the identified charm from the controller via the API.

func (*Client) OpenURI 

func (c *Client) OpenURI(uri string, query url.Values) (io.ReadCloser, error)

OpenURI performs a GET on a Juju HTTP endpoint returning the

func (*Client) PrivateAddress 

func (c *Client) PrivateAddress(target string) (string, error)

PrivateAddress returns the private address of the specified machine or unit.

func (*Client) ProvisioningScript 

func (c *Client) ProvisioningScript(args params.ProvisioningScriptParams) (script string, err error)

ProvisioningScript returns a shell script that, when run, provisions a machine agent on the machine executing the script.

TODO (manadart 2020-01-29): This method, along with its server facade should be moved to the machinemanager client/facade. Then the machinemanager client can be used as an implementation of environs.manual.ProvisioningClientAPI. Then AddMachines above can be removed along with client API facade methods that add machines (AddMachines, AddMachinesV2 and InjectMachines).

func (*Client) PublicAddress 

func (c *Client) PublicAddress(target string) (string, error)

PublicAddress returns the public address of the specified machine or unit. For a machine, target is an id not a tag.

func (*Client) ResolveCharm 

func (c *Client) ResolveCharm(ref *charm.URL) (*charm.URL, error)

ResolveCharm resolves the best available charm URLs with series, for charm locations without a series specified.

func (*Client) Resolved 

func (c *Client) Resolved(unit string, retry bool) error

Resolved clears errors on a unit.

func (*Client) RetryProvisioning 

func (c *Client) RetryProvisioning(machines ...names.MachineTag) ([]params.ErrorResult, error)

RetryProvisioning updates the provisioning status of a machine allowing the provisioner to retry.

func (*Client) SetModelAgentVersion 

func (c *Client) SetModelAgentVersion(version version.Number, ignoreAgentVersions bool) error

SetModelAgentVersion sets the model agent-version setting to the given value.

func (*Client) SetModelConstraints 

func (c *Client) SetModelConstraints(constraints constraints.Value) error

SetModelConstraints specifies the constraints for the model.

func (*Client) Status 

func (c *Client) Status(patterns []string) (*params.FullStatus, error)

Status returns the status of the juju model.

func (*Client) StatusHistory 

func (c *Client) StatusHistory(kind status.HistoryKind, tag names.Tag, filter status.StatusHistoryFilter) (status.History, error)

StatusHistory retrieves the last <size> results of <kind:combined|agent|workload|machine|machineinstance|container|containerinstance> status for <name> unit

func (*Client) UploadCharm 

func (c *Client) UploadCharm(curl *charm.URL, content io.ReadSeeker) (*charm.URL, error)

UploadCharm sends the content to the API server using an HTTP post.

func (*Client) UploadTools 

func (c *Client) UploadTools(r io.ReadSeeker, vers version.Binary, additionalSeries ...string) (tools.List, error)

UploadTools uploads tools at the specified location to the API server over HTTPS.

func (*Client) WatchAll 

func (c *Client) WatchAll() (*AllWatcher, error)

WatchAll returns an AllWatcher, from which you can request the Next collection of Deltas.

func (*Client) WatchDebugLog 

func (c *Client) WatchDebugLog(args common.DebugLogParams) (<-chan common.LogMessage, error)

WatchDebugLog returns a channel of structured Log Messages. Only log entries that match the filtering specified in the DebugLogParams are returned.

type Connection 

type Connection interface {

	// Close closes the connection.
	Close() error

	// Addr returns the address used to connect to the API server.
	Addr() string

	// IPAddr returns the IP address used to connect to the API server.
	IPAddr() string

	// APIHostPorts returns addresses that may be used to connect
	// to the API server, including the address used to connect.
	//
	// The addresses are scoped (public, cloud-internal, etc.), so
	// the client may choose which addresses to attempt. For the
	// Juju CLI, all addresses must be attempted, as the CLI may
	// be invoked both within and outside the model (think
	// private clouds).
	APIHostPorts() []network.MachineHostPorts

	// Broken returns a channel which will be closed if the connection
	// is detected to be broken, either because the underlying
	// connection has closed or because API pings have failed.
	Broken() <-chan struct{}

	// IsBroken returns whether the connection is broken. It checks
	// the Broken channel and if that is open, attempts a connection
	// ping.
	IsBroken() bool

	// IsProxied returns weather the connection is proxied.
	IsProxied() bool

	// Proxy returns the Proxier used to establish the connection if one was
	// used at all. If no Proxier was used then it's expected that returned
	// Proxier will be nil. Use IsProxied() to test for the presence of a proxy.
	Proxy() proxy.Proxier

	// PublicDNSName returns the host name for which an officially
	// signed certificate will be used for TLS connection to the server.
	// If empty, the private Juju CA certificate must be used to verify
	// the connection.
	PublicDNSName() string

	// These are a bit off -- ServerVersion is apparently not known until after
	// Login()? Maybe evidence of need for a separate AuthenticatedConnection..?
	Login(name names.Tag, password, nonce string, ms []macaroon.Slice) error
	ServerVersion() (version.Number, bool)

	// APICaller provides the facility to make API calls directly.
	// This should not be used outside the api/* packages or tests.
	base.APICaller

	// ControllerTag returns the tag of the controller.
	// This could be defined on base.APICaller.
	ControllerTag() names.ControllerTag

	// Ping makes an API request which checks if the connection is
	// still functioning.
	// NOTE: This method is deprecated. Please use IsBroken or Broken instead.
	Ping() error

	// I think this is actually dead code. It's tested, at least, so I'm
	// keeping it for now, but it's not apparently used anywhere else.
	AllFacadeVersions() map[string][]int

	// AuthTag returns the tag of the authorized user of the state API
	// connection.
	AuthTag() names.Tag

	// ModelAccess returns the access level of authorized user to the model.
	ModelAccess() string

	// ControllerAccess returns the access level of authorized user to the controller.
	ControllerAccess() string

	// CookieURL returns the URL that HTTP cookies for the API will be
	// associated with.
	CookieURL() *url.URL

	// These methods expose a bunch of worker-specific facades, and basically
	// just should not exist; but removing them is too noisy for a single CL.
	// Client in particular is intimately coupled with State -- and the others
	// will be easy to remove, but until we're using them via manifolds it's
	// prohibitively ugly to do so.
	Client() *Client
	Uniter() (*uniter.State, error)
	Upgrader() *upgrader.State
	Reboot() (reboot.State, error)
	InstancePoller() *instancepoller.API
	UnitAssigner() unitassigner.API
}

Connection represents a connection to a Juju API server.

func Open 

func Open(info *Info, opts DialOpts) (Connection, error)

Open establishes a connection to the API server using the Info given, returning a State instance which can be used to make API requests.

If the model is hosted on a different server, Open will return an error with a *RedirectError cause holding the details of another server to connect to.

See Connect for details of the connection mechanics.

type DNSCache 

type DNSCache interface {
	// Lookup returns the IP addresses associated
	// with the given host.
	Lookup(host string) []string
	// Add sets the IP addresses associated with
	// the given host name.
	Add(host string, ips []string)
}

DNSCache implements a cache of DNS lookup results.

type DeadlineStream 

type DeadlineStream struct {
	*websocket.Conn

	Timeout time.Duration
}

DeadlineStream wraps a websocket connection and applies a write deadline to each WriteJSON call.

func (*DeadlineStream) WriteJSON 

func (s *DeadlineStream) WriteJSON(v interface{}) error

WriteJSON is part of base.Stream.

type DialOpts 

type DialOpts struct {
	// DialAddressInterval is the amount of time to wait
	// before starting to dial another address.
	DialAddressInterval time.Duration

	// DialTimeout is the amount of time to wait for the dial
	// portion only of the api.Open to succeed. If this is zero,
	// there is no dial timeout.
	DialTimeout time.Duration

	// Timeout is the amount of time to wait for the entire
	// api.Open to succeed (including dial and login). If this is
	// zero, there is no timeout.
	Timeout time.Duration

	// RetryDelay is the amount of time to wait between
	// unsuccessful connection attempts. If this is
	// zero, only one attempt will be made.
	RetryDelay time.Duration

	// BakeryClient is the httpbakery Client, which
	// is used to do the macaroon-based authorization.
	// This and the *http.Client inside it are copied
	// by Open, and any RoundTripper field
	// the HTTP client is ignored.
	BakeryClient *httpbakery.Client

	// InsecureSkipVerify skips TLS certificate verification
	// when connecting to the controller. This should only
	// be used in tests, or when verification cannot be
	// performed and the communication need not be secure.
	InsecureSkipVerify bool

	// DialWebsocket is used to make connections to API servers.
	// It will be called with a websocket URL to connect to,
	// and the TLS configuration to use to secure the connection.
	// If ipAddr is non-empty, the actual net.Dial should use
	// that IP address, regardless of the URL host.
	//
	// If DialWebsocket is nil, a default implementation using
	// gorilla websockets will be used.
	DialWebsocket func(ctx context.Context, urlStr string, tlsConfig *tls.Config, ipAddr string) (jsoncodec.JSONConn, error)

	// IPAddrResolver is used to resolve host names to IP addresses.
	// If it is nil, net.DefaultResolver will be used.
	IPAddrResolver IPAddrResolver

	// DNSCache is consulted to find and store cached DNS lookups.
	// If it is nil, no cache will be used or updated.
	DNSCache DNSCache

	// Clock is used as a time source for retries.
	// If it is nil, clock.WallClock will be used.
	Clock clock.Clock

	// VerifyCA is an optional callback that is invoked by the dialer when
	// the remote server presents a CA certificate that cannot be
	// automatically verified. If the callback returns a non-nil error then
	// the connection attempt will be aborted.
	VerifyCA func(host, endpoint string, caCert *x509.Certificate) error
}

DialOpts holds configuration parameters that control the Dialing behavior when connecting to a controller.

func DefaultDialOpts 

func DefaultDialOpts() DialOpts

DefaultDialOpts returns a DialOpts representing the default parameters for contacting a controller.

type HTTPDoer 

type HTTPDoer interface {
	// Do sends the given request.
	Do(context context.Context, req *http.Request, resp interface{}) error
}

HTTPDoer exposes the functionality of httprequest.Client needed here.

type IPAddrResolver 

type IPAddrResolver interface {
	LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
}

IPAddrResolver implements a resolved from host name to the set of IP addresses associated with it. It is notably implemented by net.Resolver.

type Info 

type Info struct {

	// Addrs holds the addresses of the controllers.
	Addrs []string

	// ControllerUUID is the UUID of the controller.
	ControllerUUID string

	// SNIHostName optionally holds the host name to use for
	// server name indication (SNI) when connecting
	// to the addresses in Addrs above. If CACert is non-empty,
	// this field is ignored.
	SNIHostName string

	// CACert holds the CA certificate that will be used
	// to validate the controller's certificate, in PEM format.
	// If this is empty, the standard system root certificates
	// will be used.
	CACert string

	// ModelTag holds the model tag for the model we are
	// trying to connect to. If this is empty, a controller-only
	// login will be made.
	ModelTag names.ModelTag

	// SkipLogin, if true, skips the Login call on connection. It is an
	// error to set Tag, Password, or Macaroons if SkipLogin is true.
	SkipLogin bool `yaml:"-"`

	// Tag holds the name of the entity that is connecting.
	// If this is nil, and the password is empty, macaroon authentication
	// will be used to log in unless SkipLogin is true.
	Tag names.Tag

	// Password holds the password for the administrator or connecting entity.
	Password string

	// Macaroons holds a slice of macaroon.Slice that may be used to
	// authenticate with the API server.
	Macaroons []macaroon.Slice `yaml:",omitempty"`

	// Nonce holds the nonce used when provisioning the machine. Used
	// only by the machine agent.
	Nonce string `yaml:",omitempty"`

	// Proxier describes a proxier to use to for establing an API connection
	// A nil proxier means that it will not be used.
	Proxier proxy.Proxier
}

Info encapsulates information about a server holding juju state and can be used to make a connection to it.

func (*Info) Ports 

func (info *Info) Ports() []int

Ports returns the unique ports for the api addresses.

func (*Info) Validate 

func (info *Info) Validate() error

Validate validates the API info.

type OpenFunc 

type OpenFunc func(*Info, DialOpts) (Connection, error)

OpenFunc is the usual form of a function that opens an API connection.

type RedirectError 

type RedirectError struct {
	// Servers holds the sets of addresses of the redirected
	// servers.
	Servers []network.MachineHostPorts

	// CACert holds the certificate of the remote server.
	CACert string

	// FollowRedirect is set to true for cases like JAAS where the client
	// needs to automatically follow the redirect to the new controller.
	FollowRedirect bool

	// ControllerTag uniquely identifies the controller being redirected to.
	ControllerTag names.ControllerTag

	// An optional alias for the controller the model got redirected to.
	// It can be used by the client to present the user with a more
	// meaningful juju login -c XYZ command
	ControllerAlias string
}

RedirectError is returned from Open when the controller needs to inform the client that the model is hosted on a different set of API addresses.

func (*RedirectError) Error 

func (e *RedirectError) Error() string

type WebsocketDialer 

type WebsocketDialer interface {
	Dial(string, http.Header) (*websocket.Conn, *http.Response, error)
}

WebsocketDialer is something that can make a websocket connection. Enables testing the error unpacking in websocketDialWithErrors.

Source Files

View all Source files

Directories

Path Synopsis
Package application provides access to the application api facade.
 Package application provides access to the application api facade.
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
testing
Package bundle provides access to the bundle api facade.
 Package bundle provides access to the bundle api facade.
Package charms provides a client for accessing the charms API.
 Package charms provides a client for accessing the charms API.
charm
charms
Package charms provides a client for accessing the charms API.
 Package charms provides a client for accessing the charms API.
cloudspec
stream
Package hostkeyreporter implements the client-side API facade used by the hostkeyreporter worker.
 Package hostkeyreporter implements the client-side API facade used by the hostkeyreporter worker.
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
Package leadership implements the client to the analog leadership service.
 Package leadership implements the client to the analog leadership service.
Package logsender implements the API for storing log messages on the API server.
 Package logsender implements the API for storing log messages on the API server.
machineactions implements the the api side of running actions on machines
 machineactions implements the the api side of running actions on machines
Package meterstatus contains an implementation of the api facade to watch the meter status of a unit for changes and return the current meter status.
 Package meterstatus contains an implementation of the api facade to watch the meter status of a unit for changes and return the current meter status.
Package metricsadder contains an implementation of the api facade to add metrics to the state.
 Package metricsadder contains an implementation of the api facade to add metrics to the state.
The metricsdebug package contains the implementation of a client to access metrics debug functions within state.
 The metricsdebug package contains the implementation of a client to access metrics debug functions within state.
The metricsmanager package contains implementation for an api facade to access metrics functions within state
 The metricsmanager package contains implementation for an api facade to access metrics functions within state
Package migrationtarget defines the client side API facade for use by the migration master worker when communicating with the target controller.
 Package migrationtarget defines the client side API facade for use by the migration master worker when communicating with the target controller.
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
Package pubsub implements the API for streaming pubsub messages between api servers.
 Package pubsub implements the API for streaming pubsub messages between api servers.
Package raftlease implements the API for sending raft lease messages between api servers.
 Package raftlease implements the API for sending raft lease messages between api servers.
client
private
private/client

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.